iOS SDK - 構成メソッドリファレンス

フォローする
Avatar
Jared Ornstead
Updated

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-to-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を受け入れたときと既存の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 が YES に設定され、かつ logLevel が 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キーとシークレットで新しい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 プロパティ

アプリデリゲートからの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スキームのディープリンクに使用されます。

シグネチャ 

@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 プロパティ

プッシュ通知ペイロード内でディープリンクを探すパスを設定します。これにより、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 プロパティ

アトリビューション用のプッシュ通知ペイロードを設定します。これにより、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を受け入れたときと既存の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 プロパティ

ユニバーサルリンクを処理するための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)