iOS SDK - Configuration Reference

This document provides a comprehensive reference for all configuration options available in the Singular SDK for iOS applications. The SingularConfig object allows you to customize the SDK's behavior, including tracking settings, attribution options, privacy controls, and more. Each configuration property is presented with a description, signature, and practical usage examples.

appGroupName

SingularConfig.appGroupName Property

Sets the app group name for sharing data between the main app and app extensions. This is required when using app extensions with the SDK.

Signature

@property (strong) NSString *appGroupName;

Usage Example

// Set app group name for app extensions
config.appGroupName = "group.com.yourcompany.yourapp"

// Set app group name for app extensions
config.appGroupName = @"group.com.yourcompany.yourapp";

clipboardAttribution

Enterprise Feature: Clipboard-Based DDL requires the Singular WebSDK which is an enterprise feature. Contact your Customer Success Manager to enable this feature for your account.

SingularConfig.clipboardAttribution Property

Enables clipboard attribution for the SDK. When enabled, the SDK will check the device clipboard for attribution links during initialization.

Signature

@property (assign) BOOL clipboardAttribution;

Usage Example

// Enable clipboard attribution
config.clipboardAttribution = true

// Enable clipboard attribution
config.clipboardAttribution = YES;

conversionValueUpdatedCallback

SingularConfig.conversionValueUpdatedCallback Property

Sets a callback function to be called when the SKAdNetwork conversion value is updated. This allows you to react to conversion value changes.

Signature

@property (copy) void(^conversionValueUpdatedCallback)(NSInteger);

Usage Example

// Set conversion value updated callback
config.conversionValueUpdatedCallback = { conversionValue in
    print("Conversion value updated to: \(conversionValue)")
    // Update UI or take other actions based on the new conversion value
}

// Set conversion value updated callback
config.conversionValueUpdatedCallback = ^(NSInteger conversionValue) {
    NSLog(@"Conversion value updated to: %ld", (long)conversionValue);
    // Update UI or take other actions based on the new conversion value
};

conversionValuesUpdatedCallback

SingularConfig.conversionValuesUpdatedCallback Property

Sets a callback function to be called when the SKAdNetwork 4.0 conversion values are updated. This is specific to iOS 16.1+ and allows you to react to changes in fine, coarse, and lock values.

Signature

@property (copy) void(^conversionValuesUpdatedCallback)(NSNumber *, NSNumber *, BOOL);

Usage Example

// Set conversion values updated callback for SKAdNetwork 4.0
config.conversionValuesUpdatedCallback = { fineValue, coarseValue, lock in
    print("Conversion values updated - Fine: \(fineValue ?? 0), Coarse: \(coarseValue ?? 0), Lock: \(lock)")
    // Update UI or take other actions based on the new conversion values
}

// Set conversion values updated callback for SKAdNetwork 4.0
config.conversionValuesUpdatedCallback = ^(NSNumber *fineValue, NSNumber *coarseValue, BOOL lock) {
    NSLog(@"Conversion values updated - Fine: %@, Coarse: %@, Lock: %d", 
          fineValue, coarseValue, lock);
    // Update UI or take other actions based on the new conversion values
};

customSdid

SingularConfig.customSdid Property

Enterprise Feature: Sets a custom SDID (Singular Device ID). This allows you to provide your own device identifier instead of using the one generated by Singular.

Signature

@property (strong) NSString *customSdid;

Usage Example

// Set custom SDID
config.customSdid = "custom-device-id-12345"

// Set custom SDID
config.customSdid = @"custom-device-id-12345";

deviceAttributionCallback

SingularConfig.deviceAttributionCallback Property

BETA Feature: Sets a callback function to be called when device attribution data is available. This allows you to access attribution data as soon as it's available.

Signature

@property (copy) void(^deviceAttributionCallback)(NSDictionary *);

Usage Example

// Set device attribution callback
config.deviceAttributionCallback = { attributionData in
    print("Attribution data received: \(attributionData)")

    // Access specific attribution parameters
    let campaign = attributionData["campaign"] as? String
    let source = attributionData["source"] as? String
    let adSet = attributionData["adSet"] as? String

    // Update UI or take actions based on attribution data
    if let campaign = campaign {
        self.showCampaignSpecificContent(campaign)
    }
}

// Set device attribution callback
config.deviceAttributionCallback = ^(NSDictionary *attributionData) {
    NSLog(@"Attribution data received: %@", attributionData);

    // Access specific attribution parameters
    NSString *campaign = attributionData[@"campaign"];
    NSString *source = attributionData[@"source"];
    NSString *adSet = attributionData[@"adSet"];

    // Update UI or take actions based on attribution data
    if (campaign) {
        [self showCampaignSpecificContent:campaign];
    }
};

didSetSdidHandler

SingularConfig.didSetSdidHandler Property

Enterprise Feature: Sets a callback function to be called when the SDID (Singular Device ID) is set. This allows you to be notified when the custom SDID has been successfully set.

Signature

typedef void (^SdidAccessorHandler)(NSString *result);
@property (copy) SdidAccessorHandler didSetSdidHandler;

Usage Example

// Set callback for when SDID is set
config.customSdid = "custom-device-id-12345"
config.didSetSdidHandler = { sdid in
    print("SDID was set: \(sdid)")
    // Perform any actions needed after SDID is set
}

// Set callback for when SDID is set
config.customSdid = @"custom-device-id-12345";
config.didSetSdidHandler = ^(NSString *sdid) {
    NSLog(@"SDID was set: %@", sdid);
    // Perform any actions needed after SDID is set
};

enableOdmWithTimeoutInterval

SingularConfig.enableOdmWithTimeoutInterval Property

Sets the timeout interval in seconds for Google ODM (Organic Data Measurement) retrieval. This feature is used to retrieve organic install data from Google Play.

Signature

@property (assign) NSInteger enableOdmWithTimeoutInterval;

Usage Example

// Enable Google ODM with 5 second timeout
config.enableOdmWithTimeoutInterval = 5

// Enable Google ODM with 5 second timeout
config.enableOdmWithTimeoutInterval = 5;

espDomains

SingularConfig.espDomains Property

Sets the ESP (Email Service Provider) domains for email attribution. This allows you to specify which email domains should be considered for attribution.

Signature

@property (strong) NSArray *espDomains;

Usage Example

// Set ESP domains for email attribution
config.espDomains = ["mailchimp.com", "sendgrid.net", "campaign-monitor.com"]

// Set ESP domains for email attribution
config.espDomains = @[@"mailchimp.com", @"sendgrid.net", @"campaign-monitor.com"];

globalProperties

SingularConfig.globalProperties Property

Provides read-only access to the global properties dictionary. This contains all global properties that have been set for the configuration.

Signature

@property (readonly) NSMutableDictionary *globalProperties;

Usage Example

// Access global properties
print("Global properties: \(config.globalProperties)")

// Access global properties
NSLog(@"Global properties: %@", config.globalProperties);

initWithApiKey

SingularConfig Initialization

Initializes a new SingularConfig object with your API key and secret. This is the first step in configuring the Singular SDK.

Signature

- (id)initWithApiKey:(NSString *)apikey andSecret:(NSString *)secret;

Usage Example

// Create configuration object
let config = SingularConfig(apiKey: "YOUR_API_KEY", andSecret: "YOUR_SECRET")

// Create configuration object
SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"YOUR_API_KEY" 
                                                       andSecret:@"YOUR_SECRET"];

launchOptions

SingularConfig.launchOptions Property

Sets the launch options dictionary from the app delegate. This is used to process deep links and other launch data.

Signature

@property (strong) NSDictionary *launchOptions;

Usage Example

// Set launch options from app delegate
func application(_ application: UIApplication, 
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    let config = SingularConfig(apiKey: "API_KEY", andSecret: "SECRET")
    config.launchOptions = launchOptions
    Singular.start(config)
    return true
}

// Set launch options from app delegate
- (BOOL)application:(UIApplication *)application 
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"API_KEY" 
                                                           andSecret:@"SECRET"];
    config.launchOptions = launchOptions;
    [Singular start:config];
    return YES;
}

limitAdvertisingIdentifiers

SingularConfig.limitAdvertisingIdentifiers Property

Enables or disables the use of advertising identifiers. This option affects how the SDK collects and uses device identifiers for tracking and attribution.

Signature

@property (assign) BOOL limitAdvertisingIdentifiers;

Usage Example

// Enable limited identifiers mode
config.limitAdvertisingIdentifiers = true

// Enable limited identifiers mode
config.limitAdvertisingIdentifiers = YES;

manualSkanConversionManagement

SingularConfig.manualSkanConversionManagement Property

Enables manual management of SKAdNetwork conversion values. When enabled, the SDK will not automatically update conversion values, allowing you to control them manually.

Signature

@property (assign) BOOL manualSkanConversionManagement;

Usage Example

// Enable manual SKAdNetwork conversion management
config.manualSkanConversionManagement = true

// Enable manual SKAdNetwork conversion management
config.manualSkanConversionManagement = YES;

openUrl

SingularConfig.openUrl Property

Sets the URL used to open the app. This is used for custom URL scheme deep links.

Signature

@property (strong) NSURL *openUrl;

Usage Example

// Set open URL for custom URL schemes
func application(_ app: UIApplication, 
                 open url: URL, 
                 options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    let config = SingularConfig(apiKey: "API_KEY", andSecret: "SECRET")
    config.openUrl = url
    Singular.start(config)
    return true
}

// Set open URL for custom URL schemes
- (BOOL)application:(UIApplication *)app 
            openURL:(NSURL *)url 
            options:(NSDictionary *)options {
    SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"API_KEY" 
                                                           andSecret:@"SECRET"];
    config.openUrl = url;
    [Singular start:config];
    return YES;
}

pushNotificationLinkPath

SingularConfig.pushNotificationLinkPath Property

Sets the paths to look for deep links in push notification payloads. This helps the SDK find and process attribution links in push notifications.

Signature

@property (strong) NSArray<NSArray<NSString*>*> *pushNotificationLinkPath;

Usage Example

// Set push notification link paths
config.pushNotificationLinkPath = [
    ["data", "deeplink"],
    ["notification", "data", "url"],
    ["custom", "link"]
]

// Set push notification link paths
config.pushNotificationLinkPath = @[
    @[@"data", @"deeplink"],
    @[@"notification", @"data", @"url"],
    @[@"custom", @"link"]
];

pushNotificationPayload

SingularConfig.pushNotificationPayload Property

Sets the push notification payload for attribution. This allows the SDK to process push notification data during initialization.

Signature

@property (strong) NSDictionary *pushNotificationPayload;

Usage Example

// Set push notification payload
config.pushNotificationPayload = userInfo

// Set push notification payload
config.pushNotificationPayload = userInfo;

sdidReceivedHandler

SingularConfig.sdidReceivedHandler Property

Enterprise Feature: Sets a callback function to be called when the SDID (Singular Device ID) is received. This allows you to access the SDID as soon as it's available.

Signature

typedef void (^SdidAccessorHandler)(NSString *result);
@property (copy) SdidAccessorHandler sdidReceivedHandler;

Usage Example

// Set callback for when SDID is received
config.sdidReceivedHandler = { sdid in
    print("SDID received: \(sdid)")
    // Store or use the SDID as needed
    self.storeDeviceIdentifier(sdid)
}

// Set callback for when SDID is received
config.sdidReceivedHandler = ^(NSString *sdid) {
    NSLog(@"SDID received: %@", sdid);
    // Store or use the SDID as needed
    [self storeDeviceIdentifier:sdid];
};

setGlobalProperty

SingularConfig.setGlobalProperty Method

Sets a global property during SDK initialization. This property will be sent with all events tracked by the SDK. This is a method rather than a property, allowing for chained configuration.

Signature

- (void)setGlobalProperty:(NSString *)key 
                withValue:(NSString *)value 
         overrideExisting:(BOOL)overrideExisiting;

Usage Example

// Add global properties
config.setGlobalProperty("app_version", 
                         withValue: "1.2.3", 
                         overrideExisting: true)

config.setGlobalProperty("user_type", 
                         withValue: "free", 
                         overrideExisting: true)

// Add global properties
[config setGlobalProperty:@"app_version" 
                withValue:@"1.2.3" 
         overrideExisting:YES];

[config setGlobalProperty:@"user_type" 
                withValue:@"free" 
         overrideExisting:YES];

shortLinkResolveTimeOut

SingularConfig.shortLinkResolveTimeOut Property

Sets the timeout in seconds for resolving short links. This determines how long the SDK will wait for a short link to resolve before continuing with initialization. Default value is 10 seconds.

Signature

@property (assign) long shortLinkResolveTimeOut;

Usage Example

// Set short link resolve timeout to 15 seconds
config.shortLinkResolveTimeOut = 15

// Set short link resolve timeout to 15 seconds
config.shortLinkResolveTimeOut = 15;

singularLinksHandler

SingularConfig.singularLinksHandler Property

Sets a callback function to handle deep links processed by Singular. This allows your app to respond to deep links used in attribution.

Signature

@property (copy) void(^singularLinksHandler)(SingularLinkParams *);

Usage Example

// Set singular links handler
config.singularLinksHandler = { params in
    // Check if we have a deep link
    if let deeplink = params.deeplink {
        print("Deep link received: \(deeplink)")

        // Navigate based on the deep link
        self.navigateToScreen(deeplink)
    }

    // Check if this is a deferred deep link
    if params.isDeferred {
        print("This is a deferred deep link")
    }

    // Access passthrough parameters
    if let passthrough = params.passthrough {
        print("Passthrough data: \(passthrough)")
    }
}

// Set singular links handler
config.singularLinksHandler = ^(SingularLinkParams *params) {
    // Check if we have a deep link
    if (params.deeplink) {
        NSLog(@"Deep link received: %@", params.deeplink);

        // Navigate based on the deep link
        [self navigateToScreen:params.deeplink];
    }

    // Check if this is a deferred deep link
    if (params.isDeferred) {
        NSLog(@"This is a deferred deep link");
    }

    // Access passthrough parameters
    if (params.passthrough) {
        NSLog(@"Passthrough data: %@", params.passthrough);
    }
};

skAdNetworkEnabled

SingularConfig.skAdNetworkEnabled Property

Enables or disables SKAdNetwork support. This controls whether the SDK will use Apple's SKAdNetwork for attribution. Default value is YES.

Signature

@property (assign) BOOL skAdNetworkEnabled;

Usage Example

// Disable SKAdNetwork support if needed
config.skAdNetworkEnabled = false

// Disable SKAdNetwork support if needed
config.skAdNetworkEnabled = NO;

supportAppExtension

SingularConfig.supportAppExtension Property

Enables support for app extensions. When enabled, the SDK can function properly in app extension contexts.

Signature

@property (assign) BOOL supportAppExtension;

Usage Example

// Enable app extension support
config.supportAppExtension = true

// Enable app extension support
config.supportAppExtension = YES;

userActivity

SingularConfig.userActivity Property

Sets the user activity object for handling universal links. This is used when the app is opened via a universal link.

Signature

@property (strong) NSUserActivity *userActivity;

Usage Example

// Set user activity for universal links
func application(_ application: UIApplication, 
                 continue userActivity: NSUserActivity, 
                 restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    let config = SingularConfig(apiKey: "API_KEY", andSecret: "SECRET")
    config.userActivity = userActivity
    Singular.start(config)
    return true
}

// Set user activity for universal links
- (BOOL)application:(UIApplication *)application 
continueUserActivity:(NSUserActivity *)userActivity 
  restorationHandler:(void (^)(NSArray *))restorationHandler {
    SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"API_KEY" 
                                                           andSecret:@"SECRET"];
    config.userActivity = userActivity;
    [Singular start:config];
    return YES;
}

waitForTrackingAuthorizationWithTimeoutInterval

SingularConfig.waitForTrackingAuthorizationWithTimeoutInterval Property

Sets the timeout interval in seconds to wait for the user's tracking authorization response on iOS 14+. This determines how long the SDK will wait for the ATT prompt response before continuing with initialization.

Signature

@property (assign) NSInteger waitForTrackingAuthorizationWithTimeoutInterval;

Usage Example

// Wait up to 60 seconds for ATT prompt response
config.waitForTrackingAuthorizationWithTimeoutInterval = 60

// Wait up to 60 seconds for ATT prompt response
config.waitForTrackingAuthorizationWithTimeoutInterval = 60;

Complete Configuration Example

Comprehensive SDK Configuration

The following example demonstrates how to create a comprehensive configuration by setting multiple configuration properties together.

Complete Example

// Create configuration with API credentials
let config = SingularConfig(apiKey: "YOUR_API_KEY", andSecret: "YOUR_SECRET")

// Set basic options
config.waitForTrackingAuthorizationWithTimeoutInterval = 60
config.clipboardAttribution = true

// Set global properties
config.setGlobalProperty("app_version", 
                         withValue: "1.2.3", 
                         overrideExisting: true)
config.setGlobalProperty("user_type", 
                         withValue: "premium", 
                         overrideExisting: true)

// Configure SKAdNetwork
config.skAdNetworkEnabled = true
config.manualSkanConversionManagement = false
config.conversionValueUpdatedCallback = { conversionValue in
    print("Conversion value updated: \(conversionValue)")
}

// Configure deep links
config.launchOptions = launchOptions
config.singularLinksHandler = { params in
    if let deeplink = params.deeplink {
        print("Deep link received: \(deeplink)")
        self.handleDeepLink(deeplink)
    }
}

// Configure attribution callback
config.deviceAttributionCallback = { attributionData in
    print("Attribution data: \(attributionData)")
}

// Start the SDK
Singular.start(config)

// Create configuration with API credentials
SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"YOUR_API_KEY" 
                                                       andSecret:@"YOUR_SECRET"];

// Set basic options
config.waitForTrackingAuthorizationWithTimeoutInterval = 60;
config.clipboardAttribution = YES;

// Set global properties
[config setGlobalProperty:@"app_version" 
                withValue:@"1.2.3" 
         overrideExisting:YES];
[config setGlobalProperty:@"user_type" 
                withValue:@"premium" 
         overrideExisting:YES];

// Configure deep links
config.launchOptions = launchOptions;
config.singularLinksHandler = ^(SingularLinkParams *params) {
    if (params.deeplink) {
        NSLog(@"Deep link received: %@", params.deeplink);
        [self handleDeepLink:params.deeplink];
    }
};

// Start the SDK
[Singular start:config];

iOS SDK - Configuration Methods Reference

iOS SDK - Configuration Reference

appGroupName

SingularConfig.appGroupName Property

Signature

Usage Example

clipboardAttribution

SingularConfig.clipboardAttribution Property

Signature

Usage Example

conversionValueUpdatedCallback

SingularConfig.conversionValueUpdatedCallback Property

Signature

Usage Example

conversionValuesUpdatedCallback

SingularConfig.conversionValuesUpdatedCallback Property

Signature

Usage Example

customSdid

SingularConfig.customSdid Property

Signature

Usage Example

deviceAttributionCallback

SingularConfig.deviceAttributionCallback Property

Signature

Usage Example

didSetSdidHandler

SingularConfig.didSetSdidHandler Property

Signature

Usage Example

enableOdmWithTimeoutInterval

SingularConfig.enableOdmWithTimeoutInterval Property

Signature

Usage Example

espDomains

SingularConfig.espDomains Property

Signature

Usage Example

globalProperties

SingularConfig.globalProperties Property

Signature

Usage Example

initWithApiKey

SingularConfig Initialization

Signature

Usage Example

launchOptions

SingularConfig.launchOptions Property

Signature

Usage Example

limitAdvertisingIdentifiers

SingularConfig.limitAdvertisingIdentifiers Property

Signature

Usage Example

manualSkanConversionManagement

SingularConfig.manualSkanConversionManagement Property

Signature

Usage Example

openUrl

SingularConfig.openUrl Property

Signature

Usage Example

pushNotificationLinkPath

SingularConfig.pushNotificationLinkPath Property

Signature

Usage Example

pushNotificationPayload

SingularConfig.pushNotificationPayload Property

Signature

Usage Example

sdidReceivedHandler

SingularConfig.sdidReceivedHandler Property

Signature

Usage Example

setGlobalProperty

SingularConfig.setGlobalProperty Method

Signature

Usage Example

shortLinkResolveTimeOut

SingularConfig.shortLinkResolveTimeOut Property