Skip to main content

iOS

This guide shows you how to integrate with Kevel Audience's HTTP API on iOS using Swift with URLSession and JSONSerialization. If using Objective-C or any other HTTP client library, adapt accordingly.

Keep in mind these are simple examples without error handling, retry logic, or other production considerations that should be included in your final implementation. Additionally, the code snippets reference variables and objects that are not instantiated here but should be provided by you based on your specific implementation requirements.

Setup​

If you're planning to communicate with Kevel Audience's HTTP API via HTTP instead of HTTPS, you'll need to extend your Info.plist file to allow insecure requests to the domain Kevel Audience is deployed to. Otherwise, no setup is required.

Info.plist Configuration for HTTP​

Add the following keys to your Info.plist file to enable HTTP network requests:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSExceptionDomains</key>
    <dict>
        <key><WEBSITE_DOMAIN></key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <true/>
            <key>NSExceptionMinimumTLSVersion</key>
            <string>TLSv1.2</string>
        </dict>
    </dict>
</dict>

Replace <WEBSITE_DOMAIN> with the domain where Kevel Audience is deployed. This allows insecure HTTP requests to be made to configured whitelisted domains. HTTP connections are blocked by default.

For more information, see:

Usage​

Collecting IDs​

In iOS, User IDs should always be explicitly provided when executing requests to the HTTP API (along with the cookies query parameter set to false, when applicable to the endpoint). We recommend taking a look at Apple's documentation about User privacy and data use.

Using Your Own First-Party IDs​

You can use any ID in our list of supported IDs. If you would like to use one not present in the list, please contact our support in order for it to be added.

Using the IDFV​

The Identifier for Vendor (IDFV) is an ID that is shared amongst apps from the same vendor in the same device. It allows a vendor to uniquely identify a user's device, without relying on the device-wide IDFA, and its respective limitations. Per Apple's guidelines "The IDFV may not be combined with other data to track a user across apps and websites owned by other companies unless you have been granted permission to track by the user".

let idfv = UIDevice.current.identifierForVendor!.uuidString

Using the IDFA​

If you are using the Identifier for Advertisers (IDFA) to identify the user, please make sure that your use case is compliant with Apple's user privacy and data use guidelines.

The following examples should provide a general approach on retrieving the IDFA, but we recommend reading Apple's documentation on how to use the App Tracking Transparency framework.

Using the IDFA requires explicit authorization from the user for each application. To do so, start by establishing the message that will be presented to the user in the permission dialog. This can be done by adding the NSUserTrackingUsageDescription key to the Info.plist file of the application. The value of this key will be the message presented to the user in the pop-up dialog, replace <DIALOG_DESCRIPTION> with what you see fit.

<key>NSUserTrackingUsageDescription</key>
<dict>
    <key>NSExceptionDomains</key>
    <string><DIALOG_DESCRIPTION></string>
</dict>

Before starting to send events, we have to request access to the IDFA, and only if that permission is granted, can we send events with it. If the user has not given permission yet, this should show the permission dialog box with the message previously set.

import AppTrackingTransparency
import AdSupport

func useIDFA(completionHandler: (Bool, String) -> Void) {
  // After iOS 14, we request the IDFA to the AppTrackingTransparency framework
  if #available(iOS 14, *) {
    ATTrackingManager.requestTrackingAuthorization { status in
      let isTrackingEnabled = status == .authorized
      var idfa: String? = nil
      if isTrackingEnabled {
        idfa = ASIdentifierManager.shared().advertisingIdentifier.uuidString
      }
      completionHandler(idfa)
    }
  } else { // On older devices, we can access the IDFA directly
    let isTrackingEnabled = ASIdentifierManager.shared().isAdvertisingTrackingEnabled
    var idfa: String? = nil

    if isTrackingEnabled {
      idfa = ASIdentifierManager.shared().advertisingIdentifier.uuidString
    }
    completionHandler(idfa)
  }
}

Once we established a method of requesting permission for using the IDFA, we just have to call it and provide a completion handler where we are creating the event.

User ID Matches​

Match requests are used to link multiple identifiers in Kevel Audience. This way, any action made with any of the identifiers, across multiple channels (browser, mobile app, CRM, etc), can be associated to the same user.

A typical use case for this is, for example, during the login action, to associate the user's email with Apple's IDFA.

To send a match request, supply the provider ID which will be associated with the match event along with the two (or more) User IDs to merge via the request's query parameters.

import Foundation

let matchUrl = "https://match.cdp.\(websiteDomain)/match"
var urlComponents = URLComponents(string: matchUrl)!
urlComponents.queryItems = [
  URLQueryItem(name: "providerId", value: providerId),
  URLQueryItem(name: "id_\(idType1)", value: id1),
  URLQueryItem(name: "id_\(idType2)", value: id2),
  URLQueryItem(name: "cookies", value: "false")
]

var request = URLRequest(url: urlComponents.url!)
request.httpMethod = "GET"
request.setValue(userAgent, forHTTPHeaderField: "User-Agent")

URLSession.shared.dataTask(with: request).resume()

For more information refer to Cross-Channel Matches.

Collecting Events​

A tracking event will log a user action in Kevel Audience, allowing you to collect activity performed in your application.

In order to send a tracking event, provide the event via the POST's JSON body and the User ID to associate the event to via the request's query parameters.

import Foundation

let trackingEvent = """
{
  "clientId": "kevel",
  "siteId": "kevel.com",
  "type": "appView",
  "customFields": {
    "debug": "true",
    "role": "superuser"
  },
  "title": "Welcome Screen"
  }
"""

let trackUrl = "https://tr.cdp.\(websiteDomain)/events"
var urlComponents = URLComponents(string: trackUrl)!
urlComponents.queryItems = [
  URLQueryItem(name: "id_\(idType)", value: id),
  URLQueryItem(name: "cookies", value: "false")
]

var request = URLRequest(url: urlComponents.url!)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue(userAgent, forHTTPHeaderField: "User-Agent")
request.httpBody = trackingEvent.data(using: .utf8)!

URLSession.shared.dataTask(with: request).resume()

For more information check our list of supported events.

Last updated on