iOS SDK - 配置方法参考

iOS SDK - 配置方法参考

本文档为iOS应用程序的Singular SDK中可用的所有配置选项提供了全面的参考。SingularConfig对象允许您自定义SDK的行为,包括追踪设置、归因选项、隐私控制等。每个配置归因都附有描述、签名和实际使用示例。

appGroupName

SingularConfig.appGroupName 归因

设置用于在主应用和应用扩展之间共享数据的应用组名称。当在SDK中使用应用扩展时,此项是必需的。

签名

@property (strong) NSString *appGroupName;

使用示例

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

brandedDomains

SingularConfig.brandedDomains 归因

设置用于Web到App归因的品牌域名。这允许您指定应该用于归因目的进行追踪的自定义域名。

设置此归因会替换之前设置的所有品牌域名。请在单次赋值中传递完整列表,而不是追加。

签名

@property (strong) NSArray *brandedDomains;

使用示例

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

clipboardAttribution

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

SingularConfig.clipboardAttribution 归因

启用SDK的剪贴板归因。启用后,SDK会在初始化期间检查设备剪贴板中的归因链接。默认值为 NO

签名

@property (assign) BOOL clipboardAttribution;

使用示例

Swift Objective-C
// Enable clipboard attribution
config.clipboardAttribution = true

conversionValueUpdatedCallback

SingularConfig.conversionValueUpdatedCallback 归因

设置在SKAdNetwork转化值更新时调用的回调函数。这使您能够对转化值的变化做出反应。

签名

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

使用示例

Swift Objective-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+,允许您对fine、coarse和lock值的变化做出反应。

签名

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

使用示例

Swift Objective-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 Device ID)。这允许您提供自己的设备标识符,而不是使用Singular生成的标识符。

签名

@property (strong) NSString *customSdid;

使用示例

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

deviceAttributionCallback

SingularConfig.deviceAttributionCallback 归因

BETA功能: 设置一个回调函数,当设备归因数据从 /start 响应中可用时被调用。回调在后台队列上调度,因此请将任何UI工作调度到主线程。

类型 备注
network NSString 归因来源。 "organic" 表示未归因的安装(自然量)。
campaign_id NSString 仅在已归因时存在。
campaign_name NSString 仅在已归因时存在。
click_timestamp NSNumber (epoch microseconds) 仅在已归因时存在。除以1,000,000转换为秒。

仅当 /start 响应包含 attribution_info 对象时,才会调用回调。对于自然量安装,仅填充 network

签名

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

使用示例

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

didSetSdidHandler

SingularConfig.didSetSdidHandler 归因

企业功能: 设置一个回调函数,当您通过 customSdid分配SDID后,SDID(Singular Device ID)被设置时调用。 result 参数是刚刚存储的SDID字符串。

通常与 sdidReceivedHandler一起使用。在管理自定义SDID时,同时设置两者,以便在SDK接受新SDID和SDK显示现有SDID时都能收到通知。

签名

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

使用示例

Swift Objective-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
}

enableLogging

SingularConfig.enableLogging 归因

启用SDK日志记录。在开发过程中对调试和故障排除很有用。建议在生产构建中禁用日志记录。默认值为 NO

enableLogging 设置为 YESlogLevel 设置为高于 SingularLogLevelNone 的值之前,日志记录保持静默。

签名

@property (assign) BOOL enableLogging;

使用示例

Swift Objective-C
// Enable logging for debug builds
config.enableLogging = true
config.logLevel = .debug

enableOdmWithTimeoutInterval

SingularConfig.enableOdmWithTimeoutInterval 归因

设置Google ODM(On-Device Measurement)获取的超时间隔(秒)。ODM是Google的移动广告测量系统,可在设备上展示安装归因数据。默认值为 0 (禁用ODM获取)。

签名

@property (assign) NSInteger enableOdmWithTimeoutInterval;

使用示例

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

espDomains

SingularConfig.espDomains 归因

设置用于邮件归因的ESP(Email Service Provider)域名。这允许您指定应该考虑哪些电子邮件域名进行归因。

签名

@property (strong) NSArray *espDomains;

使用示例

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

globalProperties

SingularConfig.globalProperties 归因

提供对全局归因字典的只读访问。它包含为配置设置的所有全局归因。

签名

@property (readonly) NSMutableDictionary *globalProperties;

使用示例

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

initWithApiKey

SingularConfig 初始化

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

签名

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

使用示例

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

launchOptions

SingularConfig.launchOptions 归因

从app delegate设置launch options字典。这用于处理深度链接和其他启动数据。

签名

@property (strong) NSDictionary *launchOptions;

使用示例

Swift Objective-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如何收集和使用设备标识符进行追踪和归因。默认值为 NO

此归因在Singular Kids SDK构建中被编译排除(由 #ifndef SINGULAR_KIDS守护)。如果您正在集成 Singular-Kids-SDK,此归因不可用 — Kids SDK会自动强制执行更严格的标识符处理。

签名

@property (assign) BOOL limitAdvertisingIdentifiers;

使用示例

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

logLevel

SingularConfig.logLevel 归因

设置SDK日志记录的详细程度。还必须通过 enableLogging 启用日志记录,才能产生任何输出。默认值为 SingularLogLevelNone (无日志记录)。

可用级别(来自 SingularLogLevel.h):

  • SingularLogLevelNone (0) — 无日志记录
  • SingularLogLevelError (1) — 仅错误
  • SingularLogLevelWarning (2) — 错误和警告
  • SingularLogLevelInfo (3) — 错误、警告和信息
  • SingularLogLevelDebug (4) — 包括调试在内的所有日志
  • SingularLogLevelVerbose (5) — 最详细

签名

@property (assign) SingularLogLevel logLevel;

使用示例

Swift Objective-C
// Set verbose logging for detailed debugging
config.enableLogging = true
config.logLevel = .verbose

manualSkanConversionManagement

SingularConfig.manualSkanConversionManagement 归因

启用SKAdNetwork转化值的手动管理。启用后,SDK将不会自动更新转化值,允许您手动控制它们。

签名

@property (assign) BOOL manualSkanConversionManagement;

使用示例

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

openUrl

SingularConfig.openUrl 归因

设置用于打开应用的URL。这用于自定义URL scheme的深度链接。

签名

@property (strong) NSURL *openUrl;

使用示例

Swift Objective-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 归因

设置在推送通知payload中查找深度链接的路径。这帮助SDK在推送通知中查找并处理归因链接。

签名

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

使用示例

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

pushNotificationPayload

SingularConfig.pushNotificationPayload 归因

设置用于归因的推送通知payload。这允许SDK在初始化期间处理推送通知数据。

签名

@property (strong) NSDictionary *pushNotificationPayload;

使用示例

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

sdidReceivedHandler

SingularConfig.sdidReceivedHandler 归因

企业功能: 设置一个回调函数,当SDID(Singular Device ID)变为可用时调用 — 包括之前存储的SDID。 result 参数是SDID字符串。

通常与 didSetSdidHandler一起使用。在管理自定义SDID时,同时设置两者,以便在SDK接受新SDID和SDK显示现有SDID时都能收到通知。

签名

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

使用示例

Swift Objective-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)
}

setGlobalProperty

SingularConfig.setGlobalProperty 方法

在SDK初始化期间设置全局归因。此归因将与SDK追踪的所有事件一起发送。这是一个方法而不是归因,允许链式配置。

签名

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

使用示例

Swift Objective-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;

使用示例

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

singularLinksHandler

SingularConfig.singularLinksHandler 归因

设置一个回调函数来处理由Singular处理的深度链接。这允许您的应用响应用于归因的深度链接。

签名

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

使用示例

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

skAdNetworkEnabled

SingularConfig.skAdNetworkEnabled 归因

启用或禁用SKAdNetwork支持。这控制SDK是否使用Apple的SKAdNetwork进行归因。默认值为YES。

签名

@property (assign) BOOL skAdNetworkEnabled;

使用示例

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

supportAppExtension

SingularConfig.supportAppExtension 归因

启用对应用扩展的支持。启用后,SDK可以在应用扩展上下文中正常工作。

签名

@property (assign) BOOL supportAppExtension;

使用示例

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

userActivity

SingularConfig.userActivity 归因

设置用于处理通用链接(universal links)的user activity对象。当应用通过通用链接打开时使用。

签名

@property (strong) NSUserActivity *userActivity;

使用示例

Swift Objective-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在继续初始化之前等待AppTrackingTransparency提示响应的时间。默认值为 0 ,这意味着SDK不会等待并立即继续。

签名

@property (assign) NSInteger waitForTrackingAuthorizationWithTimeoutInterval;

使用示例

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

完整配置示例

全面的SDK配置

以下示例演示如何通过同时设置多个配置归因来创建全面的配置。

完整示例

Swift Objective-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?.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)