Before You Begin: SDK Prerequisites

Follow the steps in Integrating a Singular SDK: Planning and Prerequisites.

These steps are prerequisites for any Singular SDK integration.

1. Installing the SDK

You can install the Singular SDK using CocoaPods, Swift Package Manager, or a Static Library.

2. Setting Up a Basic SDK Integration

2.1. Importing the Singular Library

In the SceneDelegate, AppDelegate, or any file where Singular will be used, import the Singular class library to start using the Singular SDK.

// If installed with Cocoapods or Swift Package Manager
    #import Singular
          
    // If installed manually in Objective-C
    #import "Singular.h"

2.2. Creating a Configuration Object

Before you initialize Singular functionality in your code, you have to create a Singular configuration object and set all your configuration options. This code block should be added in SceneDelegate (or if you are not using SceneDelegate, add it to AppDelegate).

The following code example creates a configuration object and sets some common configuration options, such as enabling SKAdNetwork in Managed Mode and setting a timeout to wait for an ATT response.

The following sections give more details about each of these options and how you can customize them.

Example: Creating a Configuration Object with Some Common Options

func getConfig() -> SingularConfig? {
          print(Date(), "-- Scene Delegate getConfig")
          // Create the config object with the SDK Key and SDK Secret
          guard let config = SingularConfig(apiKey: Constants.APIKEY, andSecret:
          Constants.SECRET) else {
              return nil
          }
              
          // Set a 300 sec delay before initialization to wait for the user's ATT response
          // Remove this if you are not displaying an ATT prompt!
          config.waitForTrackingAuthorizationWithTimeoutInterval = 300
              
          // Support custom ESP domains
          config.espDomains = ["links.your-website-domain.com"]
              
          // Set a handler method for deep links
          config.singularLinksHandler = { params in
              self.processDeeplink(params: params)
          }
              
          return config
      }

- (SingularConfig *)getConfig {
          NSLog(@"-- Scene Delegate getConfig");
          
          // Create the config object with the SDK Key and SDK Secret
          SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY andSecret:SECRET];
      
          // Set a 300 sec delay before initialization to wait for the user's ATT response
          // Remove this if you are not displaying an ATT prompt!
          config.waitForTrackingAuthorizationWithTimeoutInterval = 300;
      
          // Support custom ESP domains
          config.espDomains = @[@"links.your-website-domain.com"];
      
          // Set a handler method for deep links
          config.singularLinksHandler = ^(SingularLinkParams * params) {[self processDeeplink:params];};
          
          return config;
      }

// Enable SKAdNetwork in Managed Mode
config.skAdNetworkEnabled = true

// Enable SKAdNetwork in Managed Mode 
config.skAdNetworkEnabled = YES;

2.3. Customizing SKAdNetwork Options

SKAdNetwork is Apple's framework for determining mobile install attribution without compromising the end user's privacy. SKAdNetwork lets you measure the performance of your app marketing campaigns without sharing the user's personally identifiable information.

By default, SKAdNetwork is enabled in Managed Mode, where the conversion value is managed directly by Singular from the server side. If using Managed Mode, you don't need to add any code to your app to handle SKAdNetwork.

This allows for maximum flexibility as you can set and change your conversion values through the Singular platform without modifying your client-side code.

This server-side managed mode also helps you deal with the SKAdNetwork timers. SKAdNetwork allows you to update the conversion value within 24 hours from the time of registration to SKAdNetwork. Any call to update the conversion value extends the timer by 24 more hours. Therefore, when choosing your conversion events, you'll have to make sure the events happen within that update window. In managed mode, you can change the conversion event configuration at any time without releasing a new version of your app.

Using SKAdNetwork in Manual Mode (Advanced)

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

// 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];

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 = { onversionValue 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;
}

2.4. Handling ATT Consent (Setting an Initialization Delay)

Displaying an ATT (App Tracking Transparency) Prompt

Starting with iOS 14.5, apps are required to ask for user consent (using the App Tracking Transparency framework) before they can access and share some user data that is helpful for tracking purposes, including the device's IDFA.

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

Delaying Initialization to Wait for ATT Response

By default, the Singular SDK sends a user session when it's initialized. When a session is sent from a new device, it immediately triggers Singular's attribution process - which is performed based only on the data available to Singular at that point. Therefore, it's essential to ask for consent and retrieve the IDFA before the Singular SDK sends the first session.

To delay the firing of a user session, initialize the Singular SDK with the waitForTrackingAuthorizationWithTimeoutInterval option in the Config object. This option is already included in the code sample in 2.2. Creating a Configuration Object.

func getConfig() -> SingularConfig? {
          guard let config = SingularConfig(apiKey: Constants.APIKEY,
              andSecret: Constants.SECRET) else {
              return nil
          }
          ...
          config.waitForTrackingAuthorizationWithTimeoutInterval = 300
          ...
          return config
      }

- (SingularConfig *)getConfig {
          SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY
              andSecret:SECRET];
          ...
          config.waitForTrackingAuthorizationWithTimeoutInterval = 300;
          ...
          return config;
      }

2.5. Handling Deep Links

When a user clicks a deep link on a device that has the app installed, the app opens and shows a specific product or experience.

Singular tracking links can include deep linking functionality as well as deferred deep linking (see our Deep Linking FAQ and the Singular Links FAQ for more information).

The Singular SDK Config, implemented in the previous step, references a callback function ("processDeeplink"). The "processDeeplink" function is required to enable deep link and deferred deep link support through the Singular SDK.

Prerequisites for Implementing Deep Links

Make sure you have completed the following steps:

• Followed the instructions in Singular Links Prerequisites.
• In Xcode, added a Singular Custom Subdomain to Signing & Capabilities > Associated Domains.
• Added the app scheme to your URL Types at Info > URL Types.
• Added your Apple Developer Team ID and Scheme in the Apps page in the Singular platform.

Creating the Callback Method for the Handler

The code example below creates a callback method called processDeeplink (this method is referenced in the Config code sample above).

The block signature is void(^)(SingularLinkParams*). The SingularLinkParams contains the deep link destination, passthrough parameters, and whether the link is deferred or not.

func processDeeplink(params: SingularLinkParams!) {
          // Get Deeplink data from Singular Link
          let deeplink = params.getDeepLink()
          let passthrough = params.getPassthrough()
          let isDeferredDeeplink = params.isDeferred() ? "Yes" : "No"
          // Add deep link handling code here
      }

- (void)processDeeplink:(SingularLinkParams*)params{
          // Get Deeplink data from Singular Link
          NSString* deeplink = [params getDeepLink];
          NSString* passthrough = [params getPassthrough];
          NSString* isDeferredDeeplink = [params isDeferred] ?@"Yes": @"No";
          // Add deep link handling code here
      }

Other Link Options

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

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

2.6. Initializing Singular

The Singular SDK should be initialized every time your app is opened. This 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). The SDK is initialized using the config object that you created in 2.2. Creating a Configuration Object.

Where to Add the Initialization Code?

You have to initialize the Singular SDK in every entry point to the app:

• For iOS 13+, initialize the Singular SDK in the following SceneDelegate functions: willConnectTo session, continue userActivity, openURLContexts URLContexts.

• For older versions of iOS that don't support SceneDelegate, initialize the SDK in the following AppDelegate functions: didFinishLaunchingWithOptions, continueUserActivity, openURL.

Initialization Code Examples

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

2.7. Sending the User ID to Singular (Optional)

The Singular SDK can send an internal user ID from your app to Singular.

• This can be any identifier, but it should not be PII (Personally Identifiable Information). For example, you should not use the user's email address.
• This identifier should also be the same internal user ID that would be captured across all platforms (web/mobile).
• If you are using Singular's Cross-Device measurement, the collection of the user ID is required across all platforms.
• Singular will expose the user ID in user-level exports and internal BI postbacks (if configured). The user ID is first-party data and will not be shared with other parties.
• The user ID persists until it is unset using the unsetCustomUserId or until the app is uninstalled. Closing/restarting the app does not unset the user ID.

To set the user ID, use the setCustomUserId method. To unset it (for example, if the user logs out of their account), call unsetCustomUserId. If multiple users use a single device, we recommend implementing a logout flow and setting and unsetting the user ID for each login and logout.

If you already know the user ID when the app opens, call setCustomUserId before initializing the Singular SDK. This way, Singular can have the user ID from the very first session. However, typically, the user ID is not available until the user registers or performs a login. In that case, call setCustomUserId after the registration.

// Set the User ID in Singular.
    setCustomUserId("custom_user_id")
      
    // Unset the User ID in Singular
    unsetCustomUserId() 

// Set the User ID
    [Singular setCustomUserId:@"a_user_id"];
      
    // UnSet the User ID
    [Singular unsetCustomUserId];

2.8. Implementing Global Properties (Optional)

The Singular SDK lets you define custom properties to be sent to the Singular servers along with every session and event sent from the app. These properties can represent any information you want about the user, the app mode/status, or anything else.

You can define up to 5 global properties. They persist between app runs (with the latest value you gave them) until you unset them or the user uninstalls the app.

Use Cases

Some use cases for global properties are:

• Pass an identifier from a third-party SDK and then use it in a postback from Singular to said third party for matching purposes.
• In a gaming app, you can define a property called "Level" and set it initially to "0". Any session and event sent from the app will be sent with "Level": "0". Once the user levels up, you reset the property to "1" and so on.

Setting Global Properties through the Config Object

To set global properties before initializing the SDK, use the setGlobalProperty method in the Config object.

Note that since global properties and their values persist between app runs, the property you are setting may already be set to a different value. Use the overrideExisting parameter to tell the SDK whether to override an existing property with the new value or not.

 func getConfig() -> SingularConfig? {         
          // (Optional) Get 3rd-party identifiers to set in Global Properties:     
          // If 3rd-party SDKs are providing any identifiers to Singular, the
          // respective SDK must be initialized before Singular.     
          let thirdPartyKey = "anonymousID"     
          let thirdPartyID = "2ed20738-059d-42b5-ab80-5aa0c530e3e1"     
      
          // Singular Config Options     
          guard let config = SingularConfig(apiKey: Constants.APIKEY, 
              andSecret: Constants.SECRET)
          else {         
              return nil
          }     
          ...     
          // Using Singular Global Properties feature to capture third party identifiers
          config.setGlobalProperty(thirdPartyKey, withValue:
              thirdPartyID, overrideExisting: true)     
          ...
          return config 
      }

- (SingularConfig *)getConfig {     
          // (Optional) Get 3rd-party identifiers to set in Global Properties:     
          // If 3rd-party SDKs are providing any identifiers to Singular, the
          // respective SDK must be initialized before Singular.     
          NSString* thirdPartyKey = @"anonymousID";
          NSString* thirdPartyID = @"2ed20738-059d-42b5-ab80-5aa0c530e3e1";     
          
          // Singular Config Options     
          SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY 
              andSecret:SECRET];
          ...
          
          // Using Singular Global Properties feature to capture 3rd-party identifiers     
          [config setGlobalProperty:thirdPartyKey withValue:thirdPartyID
              overrideExisting:YES];
          ...
          return config;
      }

Setting Global Properties After Initialization

Use the following methods to set, unset, and retrieve global properties at any time in the app's run.

var result = Singular.setGlobalProperty("propertyName",
          andValue: "propertyValue", overrideExisting: true)

BOOL result = [Singular setGlobalProperty:@"propertyName"
          andValue:@"propertyValue" overrideExisting:YES];

var globalProperties = Singular.getGlobalProperties()

NSDictionary* globalProperties = [Singular getGlobalProperties];

Singular.unsetGlobalProperty("propertyName")

[Singular unsetGlobalProperty:@"propertyName"];

Singular.clearGlobalProperties()

[Singular clearGlobalProperties];

2.9. Modifying the Session Timeout (Optional)

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

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

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

3. Tracking Events and Revenue

3.1. Tracking Events

Singular can collect data about in-app events to help analyze the performance of your campaigns and measure KPIs. For example, your organization may want to collect data about user logins, registrations, tutorial completions, or leveling up in a gaming app.

The list of events sent to Singular (with the accompanying attributes) should be compiled by the UA/marketing/business team based on your Marketing KPIs.

For more details on planning user events, see Will the App Track User Events? in the SDK Planning and Prerequisites guide.

In your code, send standard events to Singular using the event or eventWithArgs methods.

Singular.event(EVENT_SNG_LOGIN);

[Singular event:EVENT_SNG_LOGIN];

dic[ATTRIBUTE_SNG_ATTR_CONTENT_TYPE] = "PrivacyController"
      dic[ATTRIBUTE_SNG_ATTR_CONTENT_ID] = "0"
      dic[ATTRIBUTE_SNG_ATTR_CONTENT] = "GDPR and CCPA Opt-Out Options"
      Singular.event(EVENT_SNG_CONTENT_VIEW, withArgs: dic)

NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
      [dic setValue:@"PrivacyController" forKey:ATTRIBUTE_SNG_ATTR_CONTENT_TYPE];
      [dic setValue:@"0" forKey:ATTRIBUTE_SNG_ATTR_CONTENT_ID];
      [dic setValue:@"GDPR and CCPA Opt-Out Options" forKey:ATTRIBUTE_SNG_ATTR_CONTENT];
      [Singular event:EVENT_SNG_CONTENT_VIEW withArgs:dic];

3.2. Tracking Revenue

Singular can collect data about revenue gained through the app to help analyze the performance and ROI of your campaigns. Singular will make the data available in reports, log export, and postbacks.

Reporting Revenue Through IAP Tracking (Recommended)

To report revenue events to Singular, use the iapComplete SDK method. This method sends an IAP (Apple's In-App Purchase) revenue event to Singular with:

• All the transaction details, which Singular will use to enrich reports.
• The transaction receipt, which can be used to validate the transaction and analyze or prevent fraud attempts.

// *** Get the SKPaymentTransaction* transaction object ***
      let transaction:SKPaymentTransaction = ...
      
      // Send a transaction event to Singular without a custom event name
      Singular.iapComplete(transaction)
      
      // Send a transaction event to Singular with a custom event name
      Singular.iapComplete(transaction, withName:"MyCustomRevenue")

// *** Get the SKPaymentTransaction* transaction object ***
      SKPaymentTransaction* transaction = ...;
      
      // Send a transaction event to Singular without a custom event name
      [Singular iapComplete:transaction];
      
      // Send a transaction event to Singular with a custom event name
      [Singular iapComplete:transaction withName:@"MyCustomRevenue"];

Alternative Revenue Event Reporting

While Singular recommends using iapComplete, we also provide two alternative methods to report revenue events to Singular, in case your app doesn't use App Store IAP tracking.

// 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];

3.3. Hybrid Event Tracking (Advanced)

Singular recommends sending all your events and revenue through the Singular SDK integrated into your app. However, if needed, Singular can collect events and revenue from other sources.

The party sending the data must comply with Singular's Server-to-Server Event documentation requirements and provide the matching device identifier to correctly attribute an event.

If the provider or server sends events or revenue with an incorrect identifier and data points, this will cause discrepancies in your data in Singular.

Hybrid Event Tracking Guides

https://s2s.singular.net/api/v1/evt?a=<SDK KEY>&i=com.myapp&p=iOS&use_ip=true&idfa131B7AF2-52E5-41A1-AA0B-C036037575AC&idfv230F6839-290B-4BF9-8C4E-F165FE5980CF&custom_user_id=user123456789&n=s2sPurchase&e=%7B%27sampleKey1%27%3A%27sampleValue1%27%2C%27sampleKey2%27%3A%27sampleValue2%27%2C%27sampleKey3%27%3A%27sampleValue3%27%7D&is_revenue=true&amt=2.99&cur=USD

4. Advanced Options

Creating Short Referrer Links

Use the createReferrerShortLink method to generate a shortened share link for the User to share the app with friends. Define the referring user details in your app code when the link is created. This allows for tracking referrer attributions in reporting.

To create a short link:

1. Build a Singular Custom Source Link with defined deep links, that leads to your app download (see the Singular Links FAQ). This link will be referred to as a base link in the code below.
2. Any campaign override parameters to add to the link dynamically (see Tracking Link Parameters for the list of options).
3. The Name and ID of the referring user, in order to track new app installs back to the user who shared the link.

Use the createReferrerShortLink method to generate the short link as in the example below.

// 1. Define variables for the referrer short link
            
    // Define your Singular tracking link to be used as a base link:
    let referrerBaseLink = "https://yourdomain.sng.link/Csfge/aknl?_dl=myscheme%3A%2F%2Fmydeeplink/referrer&_smtype=3";
    
    // Add your Referrer ID and Name
    let referrerID = referrerIDField.text;
    let referrerName = referrerNameField.text;
    
    // Customize any Passthrough Parameters
    let passthroughParams = [
        "channel": "sms"
    ]
        
    // 2. Call  ReferrerShortLink to get your shortlink to share on social media
    Singular.createReferrerShortLink(referrerBaseLink, referrerName: referrerName, 
        referrerId: referrerID, passthroughParams: passthroughParams, completionHandler: {(shortLink, error) in
        if error != nil {
            // Logic to retry/abort/modify the params passed to the function, based on the cause of the error
        }
        if (shortLink != nil || shortLink != "") {
            // Add your share logic here:
            ....
        }
    })

 
    // 1. Define variables for the referrer short link
    
    // Define your Singular tracking link to be used as a base link.
    // Include any override parameters in the string as query string parameters.
    NSString* referrerBaseLink = @"https://yourdomain.sng.link/Csfge/aknl?_dl=myscheme%3A%2F%2Fmydeeplink/referrer&_smtype=3";
    
    // Add your Referrer ID and Name
    NSString* referrerID = self.referrerIDField.text;
    NSString* referrerName = self.referrerNameField.text;
    
    // Customize any Passthrough Parameters
    NSDictionary* passthroughParams = @{@"channel": @"sms"};
    
    // 2. Call the ReferrerShortLink Method to get the shortlink to share on social media
    [Singular createReferrerShortLink:referrerBaseLink
        referrerName:referrerName
        referrerId:referrerID
        passthroughParams:passthroughParams
        completionHandler:^(NSString *shortLink, NSError *error) {
            if (error) {
                // Logic to retry/abort/modify the params passed to the function, based on the cause of the error
            }
            if (shortLink) {
                // Add your share logic here:
                ...
            }
        }
    ];

Adding Ad Revenue Attribution Support

To add ad revenue attribution support in the Singular SDK:

1. Contact your Singular Customer Success Manager to enable ad revenue attribution for your account.
2. Make sure you are using the latest version of the Singular SDK.
3. Add the appropriate code snippet to your Singular SDK integration, depending on the mediation platform used for ad revenue data.

// Note: This feature needs to be enabled in your Admob account. 
// See https://support.google.com/admob/answer/11322405#getstarted

GADRewardedAd* rewardedAd;

[GADRewardedAd loadWithAdUnitID:@"AD_UNIT_ID"
request:request
completionHandler:^(GADRewardedAd *ad, NSError *error) {
  if (error) {
    NSLog(@"Rewarded ad failed to load with error: %@", [error localizedDescription]);
    return;
  }
  self.rewardedAd = ad;
  self.rewardedAd.paidEventHandler = ^void(GADAdValue *_Nonnull adValue){
    GADAdValue* impressionData = adValue;
    SingularAdData* data = [[SingularAdData alloc] initWithAdPlatfrom:@"Admob" 
          withCurrency:[impressionData currencyCode]
          withRevenue:[impressionData value]];
  }
}];

// The object received from AppLovin MAX's event, didReceivedMessage
      ALCMessage* message;
      
      SingularAdData* data = [[SingularAdData alloc] initWithAdPlatfrom:@"AppLovin" withCurrency:@"USD" withRevenue:message.data[@"revenue"] doubleValue];
      
      [Singular adRevenue:data];

// The object received from IronSource's event, impressionDataDidSucceed
ISImpressionData* impressionData;
      
SingularAdData* data = [[SingularAdData alloc] initWithAdPlatfrom:@"IronSource"
      withCurrency:@"USD"
      withRevenue:impressionData.revenue];
      
[Singular adRevenue:data];

// Ensure that the ARM SDK Postbacks Flag in IronSource is turned on
// See https://developers.is.com/ironsource-mobile/general/ad-revenue-measurement-postbacks/#step-1

//Set impressionDelegate
[TradPlus sharedInstance].impressionDelegate = self;

//TradPlusAdImpression Callback
- (void)tradPlusAdImpression:(NSDictionary *)adInfo
{
  NSString *currency = @"USD";
  CGFloat revenue = [adInfo[@"ecpm"] floatValue]/1000.0;
  SingularAdData *data = [[SingularAdData alloc]
  initWithAdPlatfrom:@"TradPlus"
      withCurrency:currency 
      withRevenue:@(revenue)];
  [Singular adRevenue:data];
}

// Initialize the SingularAdData object with the relevant data
SingularAdData* data = [[SingularAdData alloc]
    initWithAdPlatfrom:@"YOUR_AD_PLATFORM"
    withCurrency:@"CURRENCY_CODE"
    withRevenue:[NSNumber numberWithDouble:9.90]];

// Report the data to Singular
[Singular adRevenue:data];

Tracking Uninstalls

To configure uninstall tracking:

1. Enable the app in Singular by following the guide: Setting Up iOS Install Tracking.
2. In the app, send Singular the device token returned from the Apple Push Notification Service (APNS). To pass the device token to Singular use the registerDeviceTokenForUninstall or registerDeviceToken method. Do this before the Singular SDK is Initialized. This must be called from the AppDelegate didRegisterForRemoteNotificationsWithDeviceToken method.

func application(_ application: UIApplication, 
        didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        // Send the deviceToken to Singular for uninstall tracking     
        Singular.registerDeviceToken(forUninstall: deviceToken) 
    } 

 - (void)application:(UIApplication*)application
        didRegisterForRemoteNotificationsWithDeviceToken:(NSData*)deviceToken {     
        // Send the deviceToken to Singular for uninstall tracking      
        [Singular registerDeviceTokenForUninstall:deviceToken];
    }

Singular SDK JavaScript Interface

Singular provides a JavaScript interface that you can use to call Singular in your app.

For example, if you set up the JavaScript interface, you can send events to Singular from JavaScript code as follows:

Singular.event('event');
Singular.event('test', JSON.stringify({"a1":"bar", "a2":"boo", "a3":"baz"}));

Supported Methods in JavaScript

The interface supports the following SDK methods:

• setCustomUserID
• unsetCustomUserID
• event
• revenue

Enabling the JavaScript Interface

To enable the JavaScript interface when using WKWebView, you need to add some code to the webView method of the WKNavigationDelegate protocol (this protocol helps you implement custom behaviors triggered when a web view handles a navigation request).

extension ViewController: WKNavigationDelegate { 
    func webView(_: WKWebView, decidePolicyFor: WKNavigationAction, 
      decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) { 
      // Singular handler 
      let js = "typeof(Singular)" 
       webView.evaluateJavaScript(js) { (result, error) -> Void in 
         if let resultString = result as? String { 
           if resultString.isEqual("undefined") { 
             do { 
               let contents = try String(contentsOfFile: 
               Bundle.main.path(forResource: "Singular", ofType: "js")!) 
               self.webView.evaluateJavaScript(contents, completionHandler: nil) 
             } catch { } 
           }
           else { 
             print(decidePolicyFor.request) 
             Singular.processJSRequestWK(self.webView, withURL:decidePolicyFor.request) 
           } 
         }  
       } 
       // rest of your code goes here   
    }
  }

5. Complying with Data Privacy Laws

Singular provides privacy-safeguarding functionality to help you cooperate with any partners who may be complying with consumer privacy laws such as GDPR and CCPA (California Consumer Privacy Act). These partners want to be notified if the end-user has consented to share their private information.

LimitDataSharing

If you have implemented a way to ask users for consent to share their information, use the limitDataSharing method to notify Singular of the user's choice:

• Use limitDataSharing:NO to indicate that the user consented (opted in) to share their information.
• Use limitDataSharing:YES if the user did not consent.

Singular will pass this information on to partners who require it in order to comply with relevant regulations.

// User has opted into sharing
      data Singular.limitDataSharing(false) 

// User has opted into sharing data
[Singular limitDataSharing:NO];

Additional Methods for GDPR Compliance

The Singular SDK provides several methods to help you comply with GDPR policies and let Singular know about user consent or non-consent for tracking.

Singular.trackingOptIn() 

[Singular trackingOptIn]; 

Singular.stopAllTracking() 

[Singular stopAllTracking]; 

Singular.resumeAllTracking() 

[Singular resumeAllTracking]; 

Singular.isAllTrackingStopped()
      // returns true/false 

[Singular isAllTrackingStopped];
      // returns true/false 

Frequently Asked Questions and Issues

Refer to this section if you encounter any issues or errors when building your test app.