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:

// 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
}

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"