1. Download and install the latest version of CocoaPods.

2. To create a podfile, navigate to the project root folder in the Terminal and type:

   pod init

3. To add the Singular SDK dependency, add the following to your project's Podfile:

   pod 'Singular-SDK'

   For example:

   

4. In your Terminal, navigate to the project root folder and run:

   pod install

5. From this point forward, open the Xcode workspace file .xcworkspace to open the project, instead of the .xcodeproj file.
6. Create a Swift bridging header according to the instructions below.

1. In Xcode, go to File > Add Packages and enter the Singular SDK GitHub repository:

   https://github.com/singular-labs/Singular-iOS-SDK

   

2. Update the Singular SDK version:

   

3. Click the Add Package button.

4. Go to Build Phases > Link Binary with Libraries and add the AdServices.framework library. Be sure to mark it as Optional since it's only available for devices with iOS 14.3 and higher.

   

5. Go to Build Settings > Linking > Other Linker Flags and update Other Linker Flags with the following items:
   
   $(inherited) -ObjC -l"sqlite3.0" -l"z" -framework "AdSupport" -framework "Security" -framework "Singular" -framework "StoreKit" -framework "SystemConfiguration" -framework "WebKit" -framework "iAd"

   

   

6. Create a Swift bridging header according to the instructions below.

Are you upgrading from Singular SDK 12.3.2 or lower?

Follow the steps below to remove the old Static Library

1. Navigate to the Project files and remove the Singular Static Library. Typically, you should have a folder named something like Singular-iOS-sdk-v12.3.2. Right-Click the folder and delete it from the project.
2. Proceed to the Next section to install the new Framework

Adding the Singular Framework for the first time

1. Download and unzip the SDK Framework.

   Select the correct Framework for your implementation:

   • For Xcode 12 and up use the .xcframework [DOWNLOAD HERE]
   • For Xcode 11 and below use the .framework [DOWNLOAD HERE]

2. Add the unzipped folder to a folder in your Xcode project:

   In Xcode, right-click Your App Name > Add Files To [Your Project Name]. In the dialog that opens, select Options > Create Groups and add the folder where you unzipped the SDK.
   
   
   
   
   
   The Singular framework should now be in your project
   
   

3. To add the required libraries:

   • In Xcode, select Build Phases > Link Binary With Libraries.

   • Click + and add the following libraries:

     Libsqlite3.0.tbd
     SystemConfiguration.framework
     Security.framework
     Libz.tbd
     AdSupport.framework
     WebKit.framework
     StoreKit.framework
     AdServices.framework (mark as Optional since it's only
         available for devices with iOS 14.3 and higher).

4. Embed & Sign the Singular Framework
   • Navigate to General > Frameworks, Libraries, and Embedded Content
   • Adjust the Singular Framework to be "Embed & Sign"
     
     

If you installed the SDK using CocoaPods or the Swift Package Manager, you must create a Bridging Header for Swift to use the Obj-C libraries from the Singular SDK.

1. In your project, create a new file of type Header, and name it YourProjectName-Bridging-Header.

   

2. Open the file and add the following:

   #import <Singular/Singular.h>

   For example:

   

3. Go to Build Settings > Objective-C Bridging Header and add the file's relative path:

   

If you want to update the conversion value on your own using the app code, you first have to set the manualSkanConversionManagement flag in the Singular Config. This lets you use several SDK methods to retrieve and update the conversion value manually.

To enable Manual Mode:

func getConfig() -> SingularConfig? {
     
     // Singular Config Options
     guard let config = SingularConfig(apiKey: Constants.APIKEY,
       andSecret: Constants.SECRET) else {
         return nil
         }
     
     //...
     config.manualSkanConversionManagement = true
     //...
     
     return config
}

- (SingularConfig *)getConfig {
     
     // Singular Config Options
     SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY
       andSecret:SECRET];
     
     //...
     config.manualSkanConversionManagement = YES;
     //...
     
     return config;
}

To update the conversion value:

In Manual Mode, to update the conversion value, you need to use the skanUpdateConversionValue method. You can use it wherever needed in your app's lifecycle.

// Sending a Standard Event for Login
Singular.event(EVENT_SNG_LOGIN)
      
// Manually updating the conversion value to 7 after the Event
Singular.skanUpdateConversionValue(7)

// Sending a Standard Event for Login
[Singular event:EVENT_SNG_LOGIN];
      
// Manually updating the conversion value to 7 after the Event
[Singular skanUpdateConversionValue:7];

Other SKAdNetwork methods:

To get the current conversion value, use the skanGetConversionValue method or conversionValueUpdatedCallback. Both work in Managed and Manual Mode.

let conversionValue = Singular.skanGetConversionValue()

NSNumber* conversionValue = [Singular skanGetConversionValue]; 

func getConfig() -> SingularConfig? {
     // Singular Config Options
     guard let config = SingularConfig(apiKey: Constants.APIKEY,
       andSecret: Constants.SECRET) else {         
         return nil
         }     
     //...
     config.conversionValueUpdatedCallback = { conversionValue in
     // Here you have access to the latest conversion value
     }
     //...
     return config
}

- (SingularConfig *)getConfig {
     // Singular Config Options
     SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY
       andSecret:SECRET];
     //...
     config.conversionValueUpdatedCallback=^(NSNumber *conversionValue, 
       NSNumber *coarse, BOOL lock) {
         // Here you have access to the CV + coarse CV
       };
     //...
     return config;
}

The following table summarizes the possible scenarios using this integration:

The Singular SDK also supports Universal Links that aren't served by Singular. This is required for measuring attribution for partners who support deep linking, such as for Google Ads and Facebook.

For Singular iOS SDK versions 12.0.3 and above, non-Singular Universal Links are supported by default.

func getConfig() -> SingularConfig? {
     
     // Singular Config Options
     guard let config = SingularConfig(apiKey: Constants.APIKEY,
       andSecret: Constants.SECRET) else {
         return nil
         }
     
     //...
     config.supportedDomains = ["subdomain.mywebsite.com",
       "anothersubdomain.myotherwebsite.com"]
     //...
     
     return config
}

- (SingularConfig *)getConfig {
     
     // Singular Config Options
     SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY
       andSecret:SECRET];
     
     //...
     config.supportedDomains = @[@"subdomain.mywebsite.com",
       "anothersubdomain.myotherwebsite.com"];
     //...
     
     return config;
}

The Singular SDK supports Universal Links served by ESPs (Email Service Providers).

The ESP domain must be HTTPS-enabled. Apple requires that iOS apps pull apple-app-site-association files from an HTTPS-enabled endpoint without redirects. Check with your ESP how they host this file for your app, as it may require DNS configuration on your site's DNS. Typically, the ESP will provide the steps needed to enable HTTPS.

To support an ESP domain, add the custom tracking domain to the espDomains configuration option (in the config object) every time the Singular SDK is initialized.

func getConfig() -> SingularConfig? { 
     
     // Singular Config Options 
     guard let config = SingularConfig(apiKey: Constants.APIKEY,
       andSecret: Constants.SECRET) else { 
         return nil 
         } 
     
     //... 
     config.espDomains = ["links.mywebsite.com"] 
     //... 
     
     return config 
}

- (SingularConfig *)getConfig { 
     
     // Singular Config Options 
     SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY
       andSecret:SECRET]; 
     
     //... 
     config.espDomains = @[@"links.mywebsite.com"]; 
     //... 
     
     return config; 
}

// INITIALIZE THE SDK IN THE FOLLOWING SCENEDELEGATE FUNCTIONS]
     
// willConnectTo session
func scene(_ scene: UIScene, willConnectTo session: UISceneSession,
  options connectionOptions: UIScene.ConnectionOptions) {
    let userActivity = connectionOptions.userActivities.first
    // Print IDFV to Console for use in Singular SDK Console
    print(Date(), "-- Scene Delegate IDFV:", 
    UIDevice().identifierForVendor!.uuidString as Any)
    
    //Initialize the Singular SDK here:
    if let config = self.getConfig() {
      config.userActivity = userActivity
      Singular.start(config)
    }
}
      
// continue userActivity
      
func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
  // Starts a new Singular session on continueUserActivity
  if let config = self.getConfig() {
    config.userActivity = userActivity
    Singular.start(config)
  }
}
      
//openURLContexts URLContexts
      
func scene(_ scene: UIScene, openURLContexts URLContexts: 
  Set<UIOpenURLContext>) {
    // Starts a new Singular session on cold start from deeplink scheme
    if let config = self.getConfig() {
      config.openUrl = openurlString
      Singular.start(config)
    }
    
    // Add custom code here to Redirect to non-Singular deep links
    //...
}

// INITIALIZE THE SDK IN THE FOLLOWING WINDOWGROUP FUNCTIONS
var body: some Scene {
    WindowGroup {
        ContentView()
            .onOpenURL(perform: { url in
                openURL = url
                // Initialize Singular from an openURL
                if let config = self.getConfig() {
                    config.openUrl = url
                    Singular.start(config)
                }
            })
    }
    .onChange(of: scenePhase) { oldValue, phase in
        // The SwiftUI ScenePhases replaces the old SceneDelegate lifecycle events
        switch phase {
        case .background:
            print("App Scene: backgrounded")
        case .inactive:
            print("App Scene: inactive")
        case .active:
            print("App Scene: active")
            
            // Initialize Singular
            if let config = self.getConfig() {
                Singular.start(config)
            }
        @unknown default:
            print("App Scene: unknown")
        }
    }
}

// INITIALIZE THE SDK IN THE FOLLOWING SCENEDELEGATE FUNCTIONS
     
// willConnectToSession
- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session 
  options:(UISceneConnectionOptions *)connectionOptions {
    NSUserActivity* userActivity = [[[connectionOptions userActivities] allObjects] 
      firstObject];
    // Print identifier for Vendor (IDFV) to Xcode Console for use in Singular SDK Console
    NSLog(@"-- Scene Delegate IDFV: %@", [[[UIDevice currentDevice] identifierForVendor] UUIDString]);
    
    // Start a new Singular session from a backgrounded app
    SingularConfig *config = [self getConfig];
    config.userActivity = userActivity;
    [Singular start:config];
}
    
// continueUserActivity
- (void)scene:(UIScene *)scene continueUserActivity:(NSUserActivity *)userActivity{
  // Starts a new Singular session from a backgrounded App
  SingularConfig *config = [self getConfig];
  config.userActivity = userActivity;
  [Singular start:config];
}
    
// openURLContexts
- (void)scene:(UIScene *)scene openURLContexts:(nonnull NSSet *)URLContexts {
  // Starts a new Singular session on cold start from deeplink scheme
  SingularConfig *config = [self getConfig];
  config.openUrl = url;
  [Singular start:config];
  
  // Add custom code here to Redirect to Non-Singular deep links
  //...
}

// INITIALIZE THE SDK IN THE FOLLOWING APPDELEGATE FUNCTIONS
    
// didFinishLaunchingWithOptions
- (BOOL)application:(UIApplication *)application 
  didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Starts  new session when  user opens the app if session timeout passed/opened using Singular Link
    SingularConfig *config = [self getConfig];
    config.launchOptions = launchOptions;
    [Singular start:config];
    return YES;
}
    
// continueUserActivity
- (BOOL)application:(UIApplication *)application 
  continueUserActivity:(NSUserActivity *)userActivity 
    restorationHandler:(void (^)(NSArray<id> *restorableObjects))restorationHandler {
      // Starts a new session when the user opens the app using a Singular Link while it was in the background
      SingularConfig *config = [self getConfig];
      config.userActivity = userActivity;
      [Singular start:config];
      return YES;
}
    
// openURL
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url 
  options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options{
    // Starts new session when user opens the app using a non-Singular link, like a traditional app scheme.
    SingularConfig *config = [self getConfig];
    config.openUrl = url;
    [Singular start:config];
    // Add custom code here to Redirect to non-Singular deep links
    //...
    return YES;
}

// INITIALIZE THE SDK IN THE FOLLOWING APPDELEGATE FUNCTIONS
    
// didFinishLaunchingWithOptions
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) - Bool {
     // Print IDFV to Console for use in Singular SDK Console 
     print(Date(), "-- Scene Delegate IDFV:", UIDevice().identifierForVendor!.uuidString as Any)
     
     //Initialize the Singular SDK here: 
     if let config = self.getConfig() { 
          config.launchOptions = launchOptions 
          Singular.start(config) 
     }
     
     return true
}
    
// continue userActivity
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([any UIUserActivityRestoring]?) - Void) - Bool {
     
     //Initialize the Singular SDK here: 
     if let config = self.getConfig() {
          config.userActivity = userActivity
          Singular.start(config) 
     }
     
     return true
}
     
// open url
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) - Bool {
     
     //Initialize the Singular SDK here: 
     if let config = self.getConfig() {
          config.openUrl = url
          Singular.start(config) 
     }
     
     return true
}

Singular can receive additional mobile event tracking data via a server-to-server integration. To utilize this feature, you must map the User ID to Singular’s Mobile Device tracking identifier.

setDeviceCustomUserId("custom_user_id")

[Singular setDeviceCustomUserId:@"a_user_id"];

The revenue and customRevenue methods let you specify the transaction amount and currency manually, as well as optional additional details, such as the product serial number and quantity, etc. The customRevenue method also lets you pass a custom event name.

Note that if you use these methods, Singular does not get the transaction receipt and cannot validate the transaction.

// Revenue with no product details
Singular.revenue("USD",amount:1.99)
      
// Revenue with product details
Singular.revenue("EUR",amount:5.00, productSKU:"SKU1928375", 
  productName:"Reservation Fee",productCategory:"Fee", 
  productQuantity:1, productPrice:5.00)
      
// Send a Revenue Event with attributes in a dictionary
var dic: [AnyHashable : Any] = [:]
dic[ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION] = "100% Organic Cotton Mixed Plaid Flannel Shirt"
dic[ATTRIBUTE_SNG_ATTR_ITEM_PRICE] = "$69.95"
dic[ATTRIBUTE_SNG_ATTR_RATING] = "5 Star"
dic[ATTRIBUTE_SNG_ATTR_SEARCH_STRING] = "Flannel Shirt"
Singular.revenue("USD", amount: 19.95, withAttributes: dic)

// Revenue with no product details
[Singular revenue:@"USD" amount:1.99];
      
// Revenue with product details
[Singular revenue:@"EUR" amount:5.00 productSKU:@"SKU1928375"
  productName:@"Reservation Fee" productCategory:@"Fee" 
  productQuantity:1 productPrice:5.00];
      
// Send a Revenue Event with attributes in a dictionary
NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
[dic setValue:@"100% Organic Cotton Mixed Plaid Flannel Shirt"
  forKey:ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION];
[dic setValue:@"$69.95" forKey:ATTRIBUTE_SNG_ATTR_ITEM_PRICE];
[dic setValue:@"5 Star" forKey:ATTRIBUTE_SNG_ATTR_RATING];
[dic setValue:@"Flannel Shirt" forKey:ATTRIBUTE_SNG_ATTR_SEARCH_STRING];
[Singular revenue:@"USD" amount:19.99 withAttributes:dic];

// Revenue with a custom name and no product details
Singular.customRevenue("MyCustomRevenue", currency:"USD", amount:1.99)
      
// Revenue with a custom name and product details
Singular.customRevenue("MyCustomRevenue", currency:"EUR", amount:5.00, 
  productSKU:"SKU1928375", productName:"Reservation Fee", productCategory:"Fee", 
  productQuantity:1, productPrice:5.00)
      
// Send a Custom Revenue Event with attributes in a dictionary
var dic: [AnyHashable : Any] = [:]
dic[ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION] = "100% Organic Cotton Mixed Plaid Flannel Shirt"
dic[ATTRIBUTE_SNG_ATTR_ITEM_PRICE] = "$69.95"
dic[ATTRIBUTE_SNG_ATTR_RATING] = "5 Star"
dic[ATTRIBUTE_SNG_ATTR_SEARCH_STRING] = "Flannel Shirt"
Singular.customRevenue("CustomRevenueWithArgsDic", currency: "USD", 
  amount: 44.99, withAttributes: dic)

// Revenue with a custom name and no product details
[Singular customRevenue:@"MyCustomRevenue" currency:@"USD" amount:1.99];
      
// Revenue with a custom name and product details
[Singular customRevenue:@"MyCustomRevenue" currency:@"EUR" amount:5.00 
  productSKU:@"SKU1928375" productName:@"Reservation Fee" 
  productCategory:@"Fee"  productQuantity:1 productPrice:5.00];
      
// Send a Custom Revenue Event with attributes in a dictionary
NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
[dic setValue:@"100% Organic Cotton Mixed Plaid Flannel Shirt" 
  forKey:ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION];
[dic setValue:@"$69.95" forKey:ATTRIBUTE_SNG_ATTR_ITEM_PRICE];
[dic setValue:@"5 Star" forKey:ATTRIBUTE_SNG_ATTR_RATING];
[dic setValue:@"Flannel Shirt" forKey:ATTRIBUTE_SNG_ATTR_SEARCH_STRING];
[Singular customRevenue:@"MyCustomRevenue" currency:@"USD" 
  amount:44.99 withAttributes:dic];

Singular can collect data about revenue from your Server to help analyze the performance and ROI of your campaigns.

Requirements:

• From an in-app Registration or Login Event, capture and pass the device identifiers and store this data with the User ID on your server. Because device identifiers may change for a user, be sure to update the identifiers when a user generates an app session. This guarantees the server-side event will be attributed to the correct device.
• Server-side events are platform specific and should only be sent with the device identifier matching the device platform (e.g., IDFA or IDFV for iOS devices).
• You can use the Singular Internal BI postback mechanism to push an event in real time to your internal endpoint so that you can update the data set on the server side. See the Internal BI Postback FAQ.
• Review the "Tracking Revenue" section in the Server-to-Server Integration guide for details.

Follow the links below for details on how to enable these partners.

• Learn more in the RevenueCat documentation.
• Learn more in the adapty documentation.

To enable Segment to send events to Singular, in parallel with the Singular SDK, you must add a "Cloud-Mode" Destination in Segment. Follow our guide HERE.

In Xcode 15, there’s a new option called "User Script Sandboxing" that plays a crucial role in the build The purpose is to prevent scripts from making unintended changes to the system, thereby enhancing the stability and security of the build. When enabled, the build system restricts user scripts to disallow undeclared input/output dependencies. This is problematic for the Singular SDK, as it needs to run scripts to dynamiclly link dependencies.

To resolve the issue:

1. Navigate to Build Settings > Build Options.
2. Adjust "User Script Sandboxing" to a value "No"

1. Check that the Bridging Header was created.
2. Validate the Bridging Header file is linked in Build Settings > Objective-C Bridging Header.

In some cases, the iOS Simulator requires arm64 to be excluded in Build Settings > Excluded Architectures.

Global Properties are currently not displayed in the Testing Console. They will be added in the future. Use Export Logs to validate this functionality.

Why am I getting a logging error?

The following common logging errors can be ignored:

• [logging] duplicate column name: singular_link in "ALTER TABLE sessions ADD COLUMN singular_link TEXT DEFAULT NULL"
• [logging] duplicate column name: payload in "ALTER TABLE sessions ADD COLUMN payload TEXT DEFAULT NULL"
• [logging] duplicate column name: sequence in "ALTER TABLE events ADD COLUMN sequence INTEGER DEFAULT -1"
• [logging] duplicate column name: payload in "ALTER TABLE events ADD COLUMN payload TEXT DEFAULT NULL"