iOS SDK - 配置方法参考

文档

iOS SDK - 配置参考

本文档全面介绍了 iOS 应用程序的 Singular SDK 中的所有配置选项。通过 SingularConfig 对象,您可以自定义 SDK 的行为,包括跟踪设置、属性选项、隐私控制等。每个配置属性都附有说明、签名和实际使用示例。

应用程序组名称

SingularConfig.appGroupName 属性

设置应用程序组名称,以便在主应用程序和应用程序扩展之间共享数据。 在使用 SDK 的应用程序扩展时需要使用该名称。

签名

@property (strong) NSString *appGroupName;

使用示例

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

剪贴板属性

企业功能:基于剪贴板的 DDL 需要 Singular WebSDK,这是一项企业功能。请联系您的客户成功经理,为您的账户启用此功能。

SingularConfig.clipboardAttribution 属性

为 SDK 启用剪贴板属性。启用后,SDK 将在初始化过程中检查设备剪贴板上的属性链接。

签名

@property (assign) BOOL clipboardAttribution;

使用示例

SwiftObjective-C
// Enable clipboard attribution
config.clipboardAttribution = true

conversionValueUpdatedCallback

SingularConfig.conversionValueUpdatedCallback 属性

设置 SKAdNetwork 转换值更新时调用的回调函数。这样您就可以对转换值的变化做出反应。

签名

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

使用示例

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

conversionValuesUpdatedCallback

SingularConfig.conversionValuesUpdatedCallback 属性

设置 SKAdNetwork 4.0 转换值更新时调用的回调函数。这是 iOS 16.1+ 特有的功能,可让您对精细值、粗调值和锁定值的变化做出反应。

签名

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

使用示例

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

customSdid

SingularConfig.customSdid 属性

企业功能:设置自定义 SDID(Singular 设备 ID)。这允许你提供自己的设备标识符,而不是使用 Singular 生成的标识符。

签名

@property (strong) NSString *customSdid;

使用示例

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

deviceAttributionCallback

SingularConfig.deviceAttributionCallback 属性

BETA 特性:设置设备属性数据可用时调用的回调函数。这样就可以在属性数据可用时立即访问。

签名

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

使用示例

SwiftObjective-C
// 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)
    }
}

didSetSdidHandler

SingularConfig.didSetSdidHandler 属性

企业特性:设置当设置 SDID(奇异设备 ID)时调用的回调函数。这样就能在成功设置自定义 SDID 时通知您。

签名

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

使用示例

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

enableOdmWithTimeoutInterval

SingularConfig.enableOdmWithTimeoutInterval 属性

设置谷歌 ODM(有机数据测量)检索的超时间隔(以秒为单位)。该功能用于从 Google Play 检索有机安装数据。

签名

@property (assign) NSInteger enableOdmWithTimeoutInterval;

使用示例

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

espDomains

SingularConfig.espDomains 属性

设置用于电子邮件归因的 ESP(电子邮件服务提供商)域。这使您可以指定哪些电子邮件域应被视为归属。

签名

@property (strong) NSArray *espDomains;

使用示例

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

全局属性

SingularConfig.globalProperties 属性

提供对全局属性字典的只读访问。其中包含已为配置设置的所有全局属性。

签名

@property (readonly) NSMutableDictionary *globalProperties;

使用示例

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

initWithApiKey

初始化 SingularConfig

使用 API 密钥和秘密初始化一个新的 SingularConfig 对象。这是配置 Singular SDK 的第一步。

签名

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

使用示例

SwiftObjective-C
// Create configuration object
let config = SingularConfig(apiKey: "SDK KEY", andSecret: "YOUR_SECRET")

启动选项

SingularConfig.launchOptions 属性

设置应用程序委托的启动选项字典。用于处理深层链接和其他启动数据。

签名

@property (strong) NSDictionary *launchOptions;

使用示例

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

limitAdvertisingIdentifiers

SingularConfig.limitAdvertisingIdentifiers 属性

启用或禁用广告标识符的使用。该选项会影响 SDK 如何收集和使用设备标识符进行跟踪和归因。

签名

@property (assign) BOOL limitAdvertisingIdentifiers;

使用示例

SwiftObjective-C
// Enable limited identifiers mode
config.limitAdvertisingIdentifiers = true

manualSkanConversionManagement

SingularConfig.manualSkanConversionManagement 属性

启用手动管理 SKAdNetwork 转换值。启用后,SDK 不会自动更新转换值,您可以手动控制转换值。

签名

@property (assign) BOOL manualSkanConversionManagement;

使用示例

SwiftObjective-C
// Enable manual SKAdNetwork conversion management
config.manualSkanConversionManagement = true

openUrl

SingularConfig.openUrl 属性

设置用于打开应用程序的 URL。用于自定义 URL 方案的深度链接。

签名

@property (strong) NSURL *openUrl;

使用示例

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

pushNotificationLinkPath

SingularConfig.pushNotificationLinkPath 属性

设置在推送通知有效载荷中查找深度链接的路径。这有助于 SDK 查找和处理推送通知中的属性链接。

签名

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

使用示例

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

pushNotificationPayload

SingularConfig.pushNotificationPayload 属性

设置属性推送通知的有效载荷。这允许 SDK 在初始化过程中处理推送通知数据。

签名

@property (strong) NSDictionary *pushNotificationPayload;

使用示例

SwiftObjective-C
// Set push notification payload
config.pushNotificationPayload = userInfo

sdidReceivedHandler

SingularConfig.sdidReceivedHandler 属性

企业特性:设置收到 SDID(奇异设备 ID)时调用的回调函数。这样就可以在 SDID 可用时立即访问它。

签名

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

使用示例

SwiftObjective-C
// 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)
}

设置全局属性

SingularConfig.setGlobalProperty 方法

在 SDK 初始化过程中设置全局属性。该属性将与 SDK 跟踪的所有事件一起发送。这是一个方法而非属性,允许链式配置。

签名

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

使用示例

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

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

shortLinkResolveTimeOut

SingularConfig.shortLinkResolveTimeOut 属性

设置解析短链接的超时(以秒为单位)。这决定了 SDK 在继续初始化之前等待短链接解析的时间。默认值为 10 秒。

签名

@property (assign) long shortLinkResolveTimeOut;

使用示例

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

singularLinksHandler

SingularConfig.singularLinksHandler 属性

设置一个回调函数,用于处理由 Singular 处理的深度链接。这样,你的应用程序就能对归属中使用的深层链接做出响应。

签名

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

使用示例

SwiftObjective-C
// 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)")
    }
}

skAdNetworkEnabled

SingularConfig.skAdNetworkEnabled 属性

启用或禁用 SKAdNetwork 支持。该属性控制 SDK 是否使用 Apple 的 SKAdNetwork 进行归属。默认值为 "是"。

签名

@property (assign) BOOL skAdNetworkEnabled;

使用示例

SwiftObjective-C
// Disable SKAdNetwork support if needed
config.skAdNetworkEnabled = false

supportAppExtension

SingularConfig.supportAppExtension 属性

启用对应用程序扩展的支持。启用后,SDK 可在应用程序扩展上下文中正常运行。

签名

@property (assign) BOOL supportAppExtension;

使用示例

SwiftObjective-C
// Enable app extension support
config.supportAppExtension = true

用户活动

SingularConfig.userActivity 属性

设置用于处理通用链接的用户活动对象。当应用程序通过通用链接打开时使用。

签名

@property (strong) NSUserActivity *userActivity;

使用示例

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

waitForTrackingAuthorizationWithTimeoutInterval(使用超时间隔等待追踪授权

SingularConfig.waitForTrackingAuthorizationWithTimeoutInterval 属性

设置在 iOS 14+ 上等待用户跟踪授权响应的超时间隔(以秒为单位)。这决定了 SDK 在继续初始化之前要等待 ATT 提示响应多长时间。

签名

@property (assign) NSInteger waitForTrackingAuthorizationWithTimeoutInterval;

使用示例

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

完整配置示例

全面的 SDK 配置

下面的示例演示了如何通过同时设置多个配置属性来创建综合配置。

完整示例

SwiftObjective-C
// 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.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)