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

brandedDomains

SingularConfig.brandedDomains Property

Sets branded domains for web-to-app attribution. This allows you to specify custom domains that should be tracked for attribution purposes.

Signature

@property (strong) NSArray *brandedDomains;

Usage Example

// Set branded domains for web-to-app attribution
config.brandedDomains = ["yourcompany.com", "go.yourcompany.com"]

// Set branded domains for web-to-app attribution
config.brandedDomains = @[@"yourcompany.com", @"go.yourcompany.com"];

clipboardAttribution

SingularConfig.clipboardAttribution Property

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

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

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

Signature

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

Usage Example

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

    let network = attributionData["network"] as? String
    let campaignId = attributionData["campaign_id"] as? String
    let campaignName = attributionData["campaign_name"] as? String
    let clickTimestamp = attributionData["click_timestamp"] as? NSNumber

    // UI work must be dispatched to the main thread
    DispatchQueue.main.async {
        if let campaignName = campaignName {
            self.showCampaignSpecificContent(campaignName)
        }
    }
}

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

    NSString *network = attributionData[@"network"];
    NSString *campaignId = attributionData[@"campaign_id"];
    NSString *campaignName = attributionData[@"campaign_name"];
    NSNumber *clickTimestamp = attributionData[@"click_timestamp"];

    // UI work must be dispatched to the main thread
    dispatch_async(dispatch_get_main_queue(), ^{
        if (campaignName) {
            [self showCampaignSpecificContent:campaignName];
        }
    });
};

didSetSdidHandler

SingularConfig.didSetSdidHandler Property

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

enableLogging

SingularConfig.enableLogging Property

Enables SDK logging. Useful for debugging and troubleshooting during development. It's recommended to disable logging in production builds. Default value is NO .

Signature

@property (assign) BOOL enableLogging;

Usage Example

// Enable logging for debug builds
config.enableLogging = true
config.logLevel = .debug

// Enable logging for debug builds
config.enableLogging = YES;
config.logLevel = SingularLogLevelDebug;

enableOdmWithTimeoutInterval

SingularConfig.enableOdmWithTimeoutInterval Property

Sets the timeout interval in seconds for Google ODM (On-Device Measurement) retrieval. ODM is Google's mobile ads measurement system that surfaces install attribution data on-device. Default value is 0 (ODM retrieval disabled).

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: "SDK KEY", andSecret: "YOUR_SECRET")

// Create configuration object
SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"SDK 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. Default value is NO .

Signature

@property (assign) BOOL limitAdvertisingIdentifiers;

Usage Example

// Enable limited identifiers mode
config.limitAdvertisingIdentifiers = true

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

logLevel

SingularConfig.logLevel Property

Sets the verbosity of SDK logging. Logging must also be enabled via enableLogging for any output to be emitted. Default value is SingularLogLevelNone (no logging).

Available levels (from SingularLogLevel.h):

• SingularLogLevelNone (0) — No logging
• SingularLogLevelError (1) — Errors only
• SingularLogLevelWarning (2) — Errors and warnings
• SingularLogLevelInfo (3) — Errors, warnings, and info
• SingularLogLevelDebug (4) — All logs including debug
• SingularLogLevelVerbose (5) — Most verbose

Signature

@property (assign) SingularLogLevel logLevel;

Usage Example

// Set verbose logging for detailed debugging
config.enableLogging = true
config.logLevel = .verbose

// Set verbose logging for detailed debugging
config.enableLogging = YES;
config.logLevel = SingularLogLevelVerbose;

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

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
    guard let params = params else { return }

    // Check if we have a deep link
    if let deeplink = params.getDeepLink() {
        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.getPassthrough() {
        print("Passthrough data: \(passthrough)")
    }
}

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

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

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

    // Access passthrough parameters
    NSString *passthrough = [params getPassthrough];
    if (passthrough) {
        NSLog(@"Passthrough data: %@", 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 AppTrackingTransparency prompt response before continuing with initialization. Default value is 0 , which means the SDK does not wait and continues immediately.

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: "SDK 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?.getDeepLink() {
        print("Deep link received: \(deeplink)")
        self.handleDeepLink(deeplink)
    }
}

// Configure attribution callback (fires on a background queue)
config.deviceAttributionCallback = { attributionData in
    print("Attribution data: \(attributionData ?? [:])")
}

// Start the SDK
Singular.start(config)

// Create configuration with API credentials
SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"SDK 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) {
    NSString *deeplink = [params getDeepLink];
    if (deeplink) {
        NSLog(@"Deep link received: %@", deeplink);
        [self handleDeepLink:deeplink];
    }
};

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