iOS SDK: Basic Integration

Singular iOS SDK
Singular iOS SDK version 11.0.1 (see Change Log)
Compatibility iOS 8+
Sample App

Our sample app includes a complete integration of the Singular SDK. Review the code to see how the different parts of the integration come together using best practices.

Integration Guides
  1. Basic Integration
  2. Tracking Events and Revenue
  3. Implementing Deep Links
  4. Adding SKAdNetwork Support
  5. Advanced Options


Installing the SDK

CocoaPods is the easiest and most recommended way to integrate the Singular SDK.

Using CocoaPods

  1. Add AdServices.framework in Link Binary With Libraries and mark it as Optional (only available for devices with iOS 14.3 and higher)
  2. Add the Singular pod to your app's podfile, as stated below.
  3. Run `pod install` from the podfile's directory.
target 'APP' do
  pod 'Singular-SDK'

Using the Singular Static Library

  1. Download and unzip the SDK (see the link at the top of this article).
  2. Click on Your App Name > Add Files To <Your Project Name>.
  3. In the dialog, select Options > Create Groups and add the folder where you unzipped the SDK.
  4. The following files should now be in your project: libSingular.a, Singular.h, SingularLinkParams.h, and Singular.js.
  5. Click on Your App Name > Build Phases and expand Link Binary With Libraries.
  6. Click the + icon and add the following libraries:
    • libsqlite3.0.tbd
    • SystemConfiguration.framework
    • Security.framework
    • libz.tbd
    • AdSupport.framework
    • iAd.framework
    • WebKit.framework
    • StoreKit.framework
    • AdServices.framework (Must be added, but mark it as Optional since it's only available for devices with iOS 14.3 and higher).

Note: If your build fails, add the directory where libSingular.a is located explicitly to your project's "Library Search Paths" (Build Settings > Search Paths > Library Search Paths).

Importing the Singular Library

Import the Singular class library by adding the following to your AppDelegate file:


// If installed with Cocoapods
#import <Singular.h>

// If installed manually
#import "Singular.h"

Initializing the SDK

Note: When implementing any Singular SDK, remember to remain compliant with the various privacy laws enacted in regions where you conduct business, including GDPR, CCPA, and COPPA. For more information, see SDK Opt-In and Opt-Out Practices.

The SDK initialization code should be called every time your app is opened. It is a prerequisite to all Singular attribution functionality, and it also sends a new user session to Singular (sessions are used to calculate user retention).

Note: If your app is coded in Swift, review the "Using Swift" section below for instructions on building a bridging header with sample code.

For most apps, add the following to the applicationDidBecomeActive function:


- (void)applicationDidBecomeActive:(UIApplication *)application
    [Singular startSession:@"yourAPIKey" withKey:@"yourSecret"];

Swift (requires bridging header):

func applicationDidBecomeActive(_ application: UIApplication) {
    Singular.startSession("yourAPIKey", withKey: "yourSecret")

Optional: Modifying the Session Timeout

By default, if the app runs in the background for 60 seconds or more before returning to the foreground, the SDK registers a new session. To change this timeout value, use the setSessionTimeout method.

setSessionTimeout Method
Description Change the session timeout value.
Signature +(void)setSessionTimeout:(int)timeout
Usage Example


[Singular setSessionTimeout:120];

Swift (requires bridging header):


Sending the User ID to Singular

The Singular SDK can send a user ID from your app to Singular. This can be a username, email address, randomly generated string, or whichever identifier you use as a user ID. Singular will use the user ID in user-level data exports as well as internal BI postbacks (if you configure any).

To set the user ID, use the setCustomUserId method. To unset it (for example, if the user logs out of their account), call unsetCustomUserId.


  • The user ID persists until you unset it by calling unsetCustomUserId or until the app is uninstalled. Closing/restarting the app does not unset the user ID.
  • If you already know the user ID when the app opens, set it before initializing the Singular SDK. This way, Singular will have the user ID from the very first session.
setCustomUserId Method
Description Send the user ID to Singular.
Signature +(void)setCustomUserId:(NSString*)customUserId
Usage Example


[Singular setCustomUserId:@"a_user_id"];

Swift (requires bridging header):

unsetCustomUserId Method
Description Unset the user ID that has been sent to Singular.
Signature +(void)unsetCustomUserId;
Usage Example Objective-C:
[Singular unsetCustomUserId];

Swift (requires bridging header):


Handling AppTrackingTransparency Consent

Starting with iOS 14.5, your app is required to ask for user consent (using the App Tracking Transparency framework) before you can access some user data, including the device's IDFA.

Singular highly benefits from having the IDFA to identify devices and perform install attribution (although there are also ways to perform attribution without the IDFA). We strongly recommend that you do ask for the user's consent to retrieve the IDFA.

If you implement the ATT consent prompt, you need to make the SDK wait before sending a user session to Singular. By default, the Singular SDK fires a user session when it's initialized. When a session is fired from a new device, it immediately triggers Singular's attribution process - which is performed based only on the data that is available to Singular at that point. Therefore, it's important to ask for consent and retrieve the IDFA before the Singular SDK fires a session.

To delay the firing of a user session, you can initialize the Singular SDK with the waitForTrackingAuthorizationWithTimeoutInterval option (see sample code below).

  1. The SDK will start recording a session and user events but will not send them to the Singular server yet.
  2. As soon as App Tracking Transparency consent is granted/denied, or the set time elapses, the SDK will send the session and any queued events to the Singular server (with or without the IDFA).
  3. Singular will then start the attribution process, taking advantage of the IDFA if it is available or using probabilistic attribution if the IDFA is not available.

Sample code:

SingularConfig* config = 
[[SingularConfig alloc] initWithApiKey:apiKey andSecret:secretKey];
// Register for SKAdNetwork tracking config.skAdNetworkEnabled = YES;
// Wait 5m for tracking authorization before sending any events config.waitForTrackingAuthorizationWithTimeoutInterval = 300;
// start [Singular start:config];
// call requestTrackingAuthorizationWithCompletionHandler
// from ATTrackingManager to start the user consent process [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:
^(ATTrackingManagerAuthorizationStatus status){     // your authorization handler here     // note: the Singular SDK will automatically detect if authorization
// has been given and initialize itself }];

The following table summarizes the possible scenarios using this integration:

Scenario IDFA Availability
The user sees the consent dialog and grants consent before the set time elapses. IDFA is available
The user sees the consent dialog and denies consent before the set time elapses. IDFA is not available
The set time expires, then the user is shown the consent dialog and grants consent. IDFA is available only for the user events that are reported after the consent is granted
The set time expires, then the user is shown the consent dialog and denies consent. IDFA is not available
The user is shown the consent dialog, exits the app without taking action, and later opens the app and grants consent after the set time has expired. Any queued events are sent to the Singular server when the app is reopened. The IDFA is not available for these events. Any events tracked after consent is granted do have IDFA associated with them.
The user is shown the consent dialog, exits the app without taking action, and later opens the app and denies consent. Any queued events are sent to the Singular servers when the app is reopened. The IDFA is not available for these events or any of the events tracked afterward.

Using Swift

To use Objective-C code in a Swift app, you have to create a bridging header.

  1. See the Swift documentation on language interoperability for information on how to build an Objective-C bridging header file.
  2. Add the following to your "*-Bridging-Header.h" file to import the Singular library:
//  *-Bridging-Header.h
#import "Singular.h"
Was this article helpful?