iOS SDK

Installation

This guide covers the Mobile SDK v2.0.0 production release. Integrate it using Swift Package Manager or the published binary framework.

Swift Package Manager (SPM)

• Go to your project → Package Dependencies tab

• Click the + sign to add a new package

• Add the following SPM dependency URL, then select version 2.0.0

  https://github.com/UtiqTech/ios-sdk
  

Binary Framework

• Head to https://github.com/UtiqTech/ios-sdk/releases/tag/v2.0.0

• Download Utiq-2.0.0.zip.

• Extract this file Utiq.xcframework.

• Drag and drop it to your project.

• Use the v2.0.0 framework for the API and examples below.

3. The v2.0.0 distribution includes an iOS privacy manifest. Then initialize the SDK.

Initializing the SDK

Once added to your App, you can initialize the SDK in the AppDelegate or the main class of your iOS application.

Basic initialization

Utiq.shared.initialize(sdkToken: SDK_TOKEN)

Initializing with custom options

UtiqOptions() is an optional parameter for SDK initialization. You can initialize the SDK without it, but if you want to enable or disable specific options, configure them in UtiqOptions and pass it to the initializer.

let options = UtiqOptions().enableLogging()
Utiq.shared.initialize(sdkToken: SDK_TOKEN, options: options)

Basic usage

Once the SDK is initialized, call its public functions through Utiq.shared. Use the fetchIDs() API to get all available Utiq passes.

Fetch Utiq identifiers with fetchIDs

Utiq.shared.fetchIDs(dataCallback: { [weak self] ids in            ids.forEach { id in                print("mtid: \(String(describing: id.mtid)), atid: \(String(describing: id.atid)), attrid: \(String(describing: id.attrid)), ttl: \(String(describing: id.ttl))")            }
            
        }, errorCallback: { [weak self] error in
        
})

App Tracking Transparency (ATT)

You must use the AppTrackingTransparency framework if you intend to use the AdTechPass and share it with other companies for cross-app and cross-website tracking purposes.

The AppTrackingTransparency framework displays a tracking authorization request to the user and provides the tracking authorization status.

For more details, see here.

Request ATT

• Display the ATT pop-up. If the user accepts, proceed to the next step. If the user rejects, you can still continue, but only the MarTechPass will be returned.

• Display the Utiq consent pop-up. If the user accepts, proceed to the next step; if the user rejects, stop the flow.

ATT Validity Check - User rejects the ATT

Apple allows users to change or withdraw ATT permissions from the App settings, even when the app is not open.

To do this, go to Settings > Privacy & Security > Tracking to see a list of Apps that have requested tracking permissions. You can toggle tracking on or off for a specific App.

In some cases, the ATT might be accepted but later withdrawn, so you should periodically check the ATT status (for example, on each App start). If the status has changed to rejected, you must also reject the Utiq consent and remove the AdTechPass if it was previously set.

Utiq Consent

The SDK does not provide a built-in consent dialog. Your application must collect user consent using either a standard Consent Management Platform (CMP) or a custom pop-up that matches your app's look and feel.

User consent for the Utiq technology must be in place before calling fetchIDs().

Reject consent

Utiq.shared.rejectConsent()

You don’t need to provide success/failure closures unless you want to log the outcome.

Utiq.shared.rejectConsent(successCallback: { [weak self] in
            
        }, errorCallback: { [weak self] error in
            
})

consenthub URL

If you need to access the ConsentHub URL from within the mobile app (for example, in a web view), you can do so by calling the function that returns the ConsentHub URL.

do {
    let consentHubUrl = try Utiq.shared.consentHubUrl()

} catch {
    // Handle the error
}

Error handling

Functions with callbacks include success and failure closures. Callback APIs such as fetchIDs() and rejectConsent() do not throw; handle their error callbacks. consentHubUrl() is the throwing API and must be called with try and do/catch. The failure callback returns a custom error that is specific to the function. You can use this error to take a defined action based on the error type.

Error callbacks receive NSError values bridged from UtiqError. Mobile SDK v2.0.0 also includes InvalidIdConnectBaseURLException (-1989) for an invalid ID Connect base URL and EmptyIdGraphException (-1973) when identification completes without any ID graph records.

Support and bug reporting

If you have suggestions, want to report a bug, or have any other inquiries, please contact onboard@utiq.com