iOS SDK: Basic Integration

Singular iOS SDK
Singular iOS SDK version 10.1.5
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 the Singular pod to your app's podfile, as stated below.
  2. 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.
  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
    • StoreKit.framework

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: Remember to remain compliant with the various privacy laws enacted in regions where doing business, including but not limited to GDPR, CCPA and COPPA when implementing the Singular SDKs. 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 you initialize 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):


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?