iOS SDK - 配置方法参考
本文档为iOS应用程序的Singular SDK中可用的所有配置选项提供了全面的参考。SingularConfig对象允许您自定义SDK的行为,包括追踪设置、归因选项、隐私控制等。每个配置归因都附有描述、签名和实际使用示例。
appGroupName
SingularConfig.appGroupName 归因
设置用于在主应用和应用扩展之间共享数据的应用组名称。当在SDK中使用应用扩展时,此项是必需的。
签名
@property (strong) NSString *appGroupName;
使用示例
// 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 归因
设置用于Web到App归因的品牌域名。这允许您指定应该用于归因目的进行追踪的自定义域名。
设置此归因会替换之前设置的所有品牌域名。请在单次赋值中传递完整列表,而不是追加。
签名
@property (strong) NSArray *brandedDomains;
使用示例
// 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
企业功能: 基于剪贴板的DDL需要Singular WebSDK,这是一项企业功能。请联系您的Customer Success Manager以为您的账户启用此功能。
SingularConfig.clipboardAttribution 归因
启用SDK的剪贴板归因。启用后,SDK会在初始化期间检查设备剪贴板中的归因链接。默认值为
NO
。
签名
@property (assign) BOOL clipboardAttribution;
使用示例
// Enable clipboard attribution
config.clipboardAttribution = true
// Enable clipboard attribution
config.clipboardAttribution = YES;
conversionValueUpdatedCallback
SingularConfig.conversionValueUpdatedCallback 归因
设置在SKAdNetwork转化值更新时调用的回调函数。这使您能够对转化值的变化做出反应。
签名
@property (copy) void(^conversionValueUpdatedCallback)(NSInteger);
使用示例
// 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 归因
设置在SKAdNetwork 4.0转化值更新时调用的回调函数。这特定于iOS 16.1+,允许您对fine、coarse和lock值的变化做出反应。
签名
@property (copy) void(^conversionValuesUpdatedCallback)(NSNumber *, NSNumber *, BOOL);
使用示例
// 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 归因
企业功能: 设置自定义SDID(Singular Device ID)。这允许您提供自己的设备标识符,而不是使用Singular生成的标识符。
签名
@property (strong) NSString *customSdid;
使用示例
// Set custom SDID
config.customSdid = "custom-device-id-12345"
// 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 *);
使用示例
// 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 归因
企业功能:
设置一个回调函数,当您通过
customSdid分配SDID后,SDID(Singular Device ID)被设置时调用。
result
参数是刚刚存储的SDID字符串。
通常与
sdidReceivedHandler一起使用。在管理自定义SDID时,同时设置两者,以便在SDK接受新SDID和SDK显示现有SDID时都能收到通知。
签名
typedef void (^SdidAccessorHandler)(NSString *result);
@property (copy) SdidAccessorHandler didSetSdidHandler;
使用示例
// 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 归因
启用SDK日志记录。在开发过程中对调试和故障排除很有用。建议在生产构建中禁用日志记录。默认值为
NO
。
在
enableLogging
设置为
YES
且
logLevel
设置为高于
SingularLogLevelNone
的值之前,日志记录保持静默。
签名
@property (assign) BOOL enableLogging;
使用示例
// 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 归因
设置Google ODM(On-Device Measurement)获取的超时间隔(秒)。ODM是Google的移动广告测量系统,可在设备上展示安装归因数据。默认值为
0
(禁用ODM获取)。
签名
@property (assign) NSInteger enableOdmWithTimeoutInterval;
使用示例
// Enable Google ODM with 5 second timeout
config.enableOdmWithTimeoutInterval = 5
// Enable Google ODM with 5 second timeout
config.enableOdmWithTimeoutInterval = 5;
espDomains
SingularConfig.espDomains 归因
设置用于邮件归因的ESP(Email Service Provider)域名。这允许您指定应该考虑哪些电子邮件域名进行归因。
签名
@property (strong) NSArray *espDomains;
使用示例
// 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 (readonly) NSMutableDictionary *globalProperties;
使用示例
// Access global properties
print("Global properties: \(config.globalProperties)")
// Access global properties
NSLog(@"Global properties: %@", config.globalProperties);
initWithApiKey
SingularConfig 初始化
使用您的API密钥和secret初始化一个新的SingularConfig对象。这是配置Singular SDK的第一步。
签名
- (id)initWithApiKey:(NSString *)apikey andSecret:(NSString *)secret;
使用示例
// 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 归因
从app delegate设置launch options字典。这用于处理深度链接和其他启动数据。
签名
@property (strong) NSDictionary *launchOptions;
使用示例
// 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 归因
启用或禁用广告标识符的使用。此选项会影响SDK如何收集和使用设备标识符进行追踪和归因。默认值为
NO
。
此归因在Singular Kids SDK构建中被编译排除(由
#ifndef SINGULAR_KIDS守护)。如果您正在集成
Singular-Kids-SDK,此归因不可用 — Kids SDK会自动强制执行更严格的标识符处理。
签名
@property (assign) BOOL limitAdvertisingIdentifiers;
使用示例
// Enable limited identifiers mode
config.limitAdvertisingIdentifiers = true
// Enable limited identifiers mode
config.limitAdvertisingIdentifiers = YES;
logLevel
SingularConfig.logLevel 归因
设置SDK日志记录的详细程度。还必须通过
enableLogging
启用日志记录,才能产生任何输出。默认值为
SingularLogLevelNone
(无日志记录)。
可用级别(来自
SingularLogLevel.h):
-
SingularLogLevelNone(0) — 无日志记录 -
SingularLogLevelError(1) — 仅错误 -
SingularLogLevelWarning(2) — 错误和警告 -
SingularLogLevelInfo(3) — 错误、警告和信息 -
SingularLogLevelDebug(4) — 包括调试在内的所有日志 -
SingularLogLevelVerbose(5) — 最详细
签名
@property (assign) SingularLogLevel logLevel;
使用示例
// 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 归因
启用SKAdNetwork转化值的手动管理。启用后,SDK将不会自动更新转化值,允许您手动控制它们。
签名
@property (assign) BOOL manualSkanConversionManagement;
使用示例
// Enable manual SKAdNetwork conversion management
config.manualSkanConversionManagement = true
// Enable manual SKAdNetwork conversion management
config.manualSkanConversionManagement = YES;
openUrl
SingularConfig.openUrl 归因
设置用于打开应用的URL。这用于自定义URL scheme的深度链接。
签名
@property (strong) NSURL *openUrl;
使用示例
// 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 归因
设置在推送通知payload中查找深度链接的路径。这帮助SDK在推送通知中查找并处理归因链接。
签名
@property (strong) NSArray<NSArray<NSString*>*> *pushNotificationLinkPath;
使用示例
// 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 归因
设置用于归因的推送通知payload。这允许SDK在初始化期间处理推送通知数据。
签名
@property (strong) NSDictionary *pushNotificationPayload;
使用示例
// Set push notification payload
config.pushNotificationPayload = userInfo
// 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;
使用示例
// 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 方法
在SDK初始化期间设置全局归因。此归因将与SDK追踪的所有事件一起发送。这是一个方法而不是归因,允许链式配置。
签名
- (void)setGlobalProperty:(NSString *)key
withValue:(NSString *)value
overrideExisting:(BOOL)overrideExisiting;
使用示例
// 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 归因
设置解析短链接的超时时间(秒)。这决定了SDK在继续初始化之前等待短链接解析的时间。默认值为10秒。
签名
@property (assign) long shortLinkResolveTimeOut;
使用示例
// 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 归因
设置一个回调函数来处理由Singular处理的深度链接。这允许您的应用响应用于归因的深度链接。
签名
@property (copy) void(^singularLinksHandler)(SingularLinkParams *);
使用示例
// 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 归因
启用或禁用SKAdNetwork支持。这控制SDK是否使用Apple的SKAdNetwork进行归因。默认值为YES。
签名
@property (assign) BOOL skAdNetworkEnabled;
使用示例
// Disable SKAdNetwork support if needed
config.skAdNetworkEnabled = false
// Disable SKAdNetwork support if needed
config.skAdNetworkEnabled = NO;
supportAppExtension
SingularConfig.supportAppExtension 归因
启用对应用扩展的支持。启用后,SDK可以在应用扩展上下文中正常工作。
签名
@property (assign) BOOL supportAppExtension;
使用示例
// Enable app extension support
config.supportAppExtension = true
// Enable app extension support
config.supportAppExtension = YES;
userActivity
SingularConfig.userActivity 归因
设置用于处理通用链接(universal links)的user activity对象。当应用通过通用链接打开时使用。
签名
@property (strong) NSUserActivity *userActivity;
使用示例
// 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 归因
设置在iOS 14+上等待用户追踪授权响应的超时间隔(秒)。这决定了SDK在继续初始化之前等待AppTrackingTransparency提示响应的时间。默认值为
0
,这意味着SDK不会等待并立即继续。
签名
@property (assign) NSInteger waitForTrackingAuthorizationWithTimeoutInterval;
使用示例
// Wait up to 60 seconds for ATT prompt response
config.waitForTrackingAuthorizationWithTimeoutInterval = 60
// Wait up to 60 seconds for ATT prompt response
config.waitForTrackingAuthorizationWithTimeoutInterval = 60;
完整配置示例
全面的SDK配置
以下示例演示如何通过同时设置多个配置归因来创建全面的配置。
完整示例
// 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];