iOS SDK - コンフィギュレーションリファレンス
このドキュメントはSingular SDK for iOSアプリケーションで利用可能なすべての設定オプションの包括的なリファレンスです。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";
クリップボード属性
エンタープライズ機能:クリップボードベースのDDLには、エンタープライズ機能であるSingular WebSDKが必要です。お客様のアカウントでこの機能を有効にするには、カスタマーサクセスマネージャーにお問い合わせください。
SingularConfig.clipboardAttribution プロパティ
SDKのクリップボード帰属を有効にします。有効にすると、SDKは初期化中にデバイスのクリップボードの属性リンクをチェックします。
シグネチャ
@property (assign) BOOL clipboardAttribution;
使用例
// Enable clipboard attribution
config.clipboardAttribution = true
// Enable clipboard attribution
config.clipboardAttribution = YES;
コンバージョン値更新コールバック
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
};
コンバージョン値更新コールバック
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デバイス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(Singular Device 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プロパティ
Google ODM (Organic Data Measurement) 検索のタイムアウト間隔を秒単位で設定します。この機能は、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 プロパティ
Eメール帰属のためのESP(Eメールサービスプロバイダ)ドメインを設定します。これにより、どのEメールドメインを帰属の対象とするかを指定できます。
署名
@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 の初期化
新しい SingularConfig オブジェクトを API キーとシークレットで初期化します。これは 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 プロパティ
アプリデリゲートからの起動オプション辞書を設定します。これは、ディープリンクやその他の起動データを処理するために使用されます。
シグネチャ
@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;
マニュアルスキャンコンバージョン管理
SingularConfig.manualSkanConversionManagementプロパティ
SKAdNetwork変換値の手動管理を有効にします。有効にすると、SDKはコンバージョン値を自動的に更新せず、手動で管理できるようになります。
シグネチャ
@property (assign) BOOL manualSkanConversionManagement;
使用例
// Enable manual SKAdNetwork conversion management
config.manualSkanConversionManagement = true
// Enable manual SKAdNetwork conversion management
config.manualSkanConversionManagement = YES;
オープンURL
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;
}
プッシュ通知リンクパス
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"]
];
プッシュ通知ペイロード
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(Singular Device 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];
};
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
// 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を使用するかどうかを制御します。デフォルト値はYES。
シグネチャ
@property (assign) BOOL skAdNetworkEnabled;
使用例
// Disable SKAdNetwork support if needed
config.skAdNetworkEnabled = false
// Disable SKAdNetwork support if needed
config.skAdNetworkEnabled = NO;
サポートAppExtension
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];