iOS SDK - 配置参考
本文档全面介绍了 iOS 应用程序的 Singular SDK 中的所有配置选项。通过 SingularConfig 对象,您可以自定义 SDK 的行为,包括跟踪设置、属性选项、隐私控制等。每个配置属性都附有说明、签名和实际使用示例。
应用程序组名称
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";
剪贴板属性
企业功能:基于剪贴板的 DDL 需要 Singular WebSDK,这是一项企业功能。请联系您的客户成功经理,为您的账户启用此功能。
SingularConfig.clipboardAttribution 属性
为 SDK 启用剪贴板属性。启用后,SDK 将在初始化过程中检查设备剪贴板上的属性链接。
签名
@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+ 特有的功能,可让您对精细值、粗调值和锁定值的变化做出反应。
签名
@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 设备 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 特性:设置设备属性数据可用时调用的回调函数。这样就可以在属性数据可用时立即访问。
签名
@property (copy) void(^deviceAttributionCallback)(NSDictionary *);
使用示例
// 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 属性
企业特性:设置当设置 SDID(奇异设备 ID)时调用的回调函数。这样就能在成功设置自定义 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
};
enableOdmWithTimeoutInterval
SingularConfig.enableOdmWithTimeoutInterval 属性
设置谷歌 ODM(有机数据测量)检索的超时间隔(以秒为单位)。该功能用于从 Google Play 检索有机安装数据。
签名
@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(电子邮件服务提供商)域。这使您可以指定哪些电子邮件域应被视为归属。
签名
@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"];
全局属性
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 密钥和秘密初始化一个新的 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"];
启动选项
SingularConfig.launchOptions 属性
设置应用程序委托的启动选项字典。用于处理深层链接和其他启动数据。
签名
@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 如何收集和使用设备标识符进行跟踪和归因。
签名
@property (assign) BOOL limitAdvertisingIdentifiers;
使用示例
// Enable limited identifiers mode
config.limitAdvertisingIdentifiers = true
// Enable limited identifiers mode
config.limitAdvertisingIdentifiers = YES;
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 方案的深度链接。
签名
@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 属性
设置在推送通知有效载荷中查找深度链接的路径。这有助于 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 属性
设置属性推送通知的有效载荷。这允许 SDK 在初始化过程中处理推送通知数据。
签名
@property (strong) NSDictionary *pushNotificationPayload;
使用示例
// Set push notification payload
config.pushNotificationPayload = userInfo
// Set push notification payload
config.pushNotificationPayload = userInfo;
sdidReceivedHandler
SingularConfig.sdidReceivedHandler 属性
企业特性:设置收到 SDID(奇异设备 ID)时调用的回调函数。这样就可以在 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];
};
设置全局属性
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
// 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 属性
启用或禁用 SKAdNetwork 支持。该属性控制 SDK 是否使用 Apple 的 SKAdNetwork 进行归属。默认值为 "是"。
签名
@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;
用户活动
SingularConfig.userActivity 属性
设置用于处理通用链接的用户活动对象。当应用程序通过通用链接打开时使用。
签名
@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 在继续初始化之前要等待 ATT 提示响应多长时间。
签名
@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.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:@"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) {
if (params.deeplink) {
NSLog(@"Deep link received: %@", params.deeplink);
[self handleDeepLink:params.deeplink];
}
};
// Start the SDK
[Singular start:config];