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

Android SDK - 構成リファレンス

このドキュメントは、Androidアプリケーション向けSingular SDKで利用可能なすべての構成オプションに関する包括的なリファレンスを提供します。SingularConfigオブジェクトを使用すると、トラッキング設定、アトリビューションオプション、プライバシー制御などを含むSDKの動作をカスタマイズできます。各構成メソッドには、説明、シグネチャ、実用的な使用例が記載されています。

完全な構成例

包括的なSDK構成

次の例は、複数の構成メソッドを連結して包括的な構成を作成する方法を示しています。

完全な例

Kotlin Java
// Create comprehensive configuration
val config = SingularConfig("SDK KEY", "YOUR_SECRET")
    // Basic options
    .withSessionTimeoutInSec(120)
    .withLoggingEnabled()
    .withLogLevel(Log.VERBOSE)

    // User identification
    .withCustomUserId("user_123456")

    // Global properties
    .withGlobalProperty("app_version", "1.2.3", true)
    .withGlobalProperty("user_type", "premium", true)

    // Deep links
    .withOpenURI(intent.data)
    .withSingularLink(intent, { params ->
        params.deeplink?.let { deeplink ->
            println("Deep link: $deeplink")
            handleDeepLink(deeplink)
        }
    }, 10)

    // Attribution callback
    .withSingularDeviceAttribution { attributionData ->
        println("Attribution: $attributionData")
    }

    // Push notifications
    .withFCMDeviceToken(fcmToken)

    // Privacy settings
    .withLimitDataSharing(false)

    // Email attribution
    .withESPDomains(listOf("mailchimp.com", "sendgrid.net"))

    // Facebook integration
    .withFacebookAppId("YOUR_FACEBOOK_APP_ID")

// Initialize the SDK
Singular.init(context, config)

Constructor

SingularConfig コンストラクタ

APIキーとシークレットを使用して、新しいSingularConfigオブジェクトを初期化します。これはSingular SDKを構成する最初のステップです。

シグネチャ

public SingularConfig(String apiKey, String secret);

使用例

Kotlin Java
// Create configuration object
val config = SingularConfig("SDK KEY", "YOUR_SECRET")

withBrandedDomains

SingularConfig.withBrandedDomains メソッド

ウェブからアプリへのアトリビューション用のブランドドメインを設定します。アトリビューションの目的でトラッキングするカスタムドメインを指定できます。

このメソッドを呼び出すと、以前に設定されたブランドドメインがすべて置き換えられます。複数回連結する代わりに、完全なリストを1回の呼び出しで渡してください。

シグネチャ

public SingularConfig withBrandedDomains(List<String> brandedDomains);

使用例

Kotlin Java
// Set branded domains for web-to-app attribution
val brandedDomains = listOf("yourcompany.com", "go.yourcompany.com")
val config = SingularConfig("API_KEY", "SECRET")
    .withBrandedDomains(brandedDomains)

withCustomSdid

SingularConfig.withCustomSdid メソッド

エンタープライズ機能: カスタムSDID(Singular Device ID)を設定します。Singularが生成したものの代わりに、独自のデバイス識別子を提供できます。

シグネチャ

public SingularConfig withCustomSdid(String customSdid, SDIDAccessorHandler accessorHandler);

使用例

Kotlin Java
// Set custom SDID with callback
val config = SingularConfig("API_KEY", "SECRET")
    .withCustomSdid("custom-device-id-12345", object : SDIDAccessorHandler {
        override fun didSetSdid(result: String) {
            println("SDID was set: $result")
            // Perform any actions needed after SDID is set
        }

        override fun sdidReceived(result: String) {
            println("SDID received: $result")
            // Existing SDID returned by the SDK
        }
    })

withCustomUserId

SingularConfig.withCustomUserId メソッド

SDK初期化時にカスタムユーザーIDを設定します。これにより、最初からSingularデータを独自のユーザー識別システムと関連付けることができます。

シグネチャ

public SingularConfig withCustomUserId(String customUserId);

使用例

Kotlin Java
// Set custom user ID at initialization
val config = SingularConfig("API_KEY", "SECRET")
    .withCustomUserId("user_123456")

withESPDomains

SingularConfig.withESPDomains メソッド

メールアトリビューション用のESP(メールサービスプロバイダー)ドメインを設定します。アトリビューションで考慮すべきメールドメインを指定できます。

このメソッドを呼び出すと、以前に設定されたESPドメインがすべて置き換えられます。複数回連結する代わりに、完全なリストを1回の呼び出しで渡してください。

シグネチャ

public SingularConfig withESPDomains(List<String> espDomains);

使用例

Kotlin Java
// Set ESP domains for email attribution
val espDomains = listOf("mailchimp.com", "sendgrid.net", "campaign-monitor.com")
val config = SingularConfig("API_KEY", "SECRET")
    .withESPDomains(espDomains)

withFacebookAppId

SingularConfig.withFacebookAppId メソッド

Facebookアトリビューション連携用のFacebook App IDを設定します。これにより、SDKがFacebookキャンペーンのアトリビューションをトラッキングできます。

シグネチャ

public SingularConfig withFacebookAppId(String facebookAppId);

使用例

Kotlin Java
// Set Facebook App ID
val config = SingularConfig("API_KEY", "SECRET")
    .withFacebookAppId("YOUR_FACEBOOK_APP_ID")

withFCMDeviceToken

SingularConfig.withFCMDeviceToken メソッド

初期化時にFCM(Firebase Cloud Messaging)デバイストークンを設定します。これにより、最初からプッシュ通知トラッキングとアンインストール検出を有効にできます。

トークンがnullまたは空の場合、呼び出しは無視されます。有効なFCMトークンを取得した後にのみこのメソッドを呼び出してください。

シグネチャ

public SingularConfig withFCMDeviceToken(String fcmDeviceToken);

使用例

Kotlin Java
// Set FCM token at initialization if available
val config = SingularConfig("API_KEY", "SECRET")
    .withFCMDeviceToken(fcmToken)

withGlobalProperty

SingularConfig.withGlobalProperty メソッド

SDK初期化時にグローバルプロパティを設定します。このプロパティは、SDKがトラッキングするすべてのイベントとともに送信されます。連結構成が可能な構成メソッドです。

SDKは最大5個のグローバルプロパティをサポートします。この制限を超える呼び出しは黙って無視されます。

シグネチャ

public SingularConfig withGlobalProperty(String key, String value, boolean overrideExisting);

使用例

Kotlin Java
// Add global properties at initialization
val config = SingularConfig("API_KEY", "SECRET")
    .withGlobalProperty("app_version", "1.2.3", true)
    .withGlobalProperty("user_type", "free", true)

withIMEI

SingularConfig.withIMEI メソッド

初期化時にトラッキング用のデバイスIMEIを設定します。IMEIトラッキングが許可され、推奨される地域で有用です。

シグネチャ

public SingularConfig withIMEI(String imei);

使用例

Kotlin Java
// Set device IMEI at initialization
val config = SingularConfig("API_KEY", "SECRET")
    .withIMEI("123456789012345")

withLimitAdvertisingIdentifiers

SingularConfig.withLimitAdvertisingIdentifiers メソッド

混合オーディエンスアプリで広告識別子の制限モードを有効にします。このオプションは、SDKがトラッキング用のデバイス識別子を収集および使用する方法に影響します。

シグネチャ

public SingularConfig withLimitAdvertisingIdentifiers();

使用例

Kotlin Java
// Enable limited identifiers mode
val config = SingularConfig("API_KEY", "SECRET")
    .withLimitAdvertisingIdentifiers()

withLimitDataSharing

SingularConfig.withLimitDataSharing メソッド

初期化時にデータ共有制限のステータスを設定します。ユーザーの同意またはプライバシー要件に基づいてデータ共有を制限するには、このメソッドを使用してください。

シグネチャ

public SingularConfig withLimitDataSharing(boolean shouldLimitDataSharing);

使用例

Kotlin Java
// Enable limited data sharing at initialization
val config = SingularConfig("API_KEY", "SECRET")
    .withLimitDataSharing(true)

withLogLevel

SingularConfig.withLogLevel メソッド

SDKロギングのログレベルを設定します。利用可能なレベルは以下のとおりです:

  • NONE = -1

  • VERBOSE = Log.VERBOSE (Android定数、数値2)

  • DEBUG = Log.DEBUG (3)

  • INFO = Log.INFO (4)

  • WARNING = Log.WARN (5)

  • ERROR = Log.ERROR (6)

デフォルトのログレベルは Log.ERRORです。出力が発行されるには、 withLoggingEnabled()を介してロギングも有効化する必要があります。

シグネチャ

public SingularConfig withLogLevel(int level);

使用例

Kotlin Java
import android.util.Log

// Set verbose logging for detailed debugging
val config = SingularConfig("API_KEY", "SECRET")
    .withLoggingEnabled()
    .withLogLevel(Log.VERBOSE)

withLoggingEnabled

SingularConfig.withLoggingEnabled メソッド

SDKロギングを有効にします。開発時のデバッグやトラブルシューティングに役立ちます。本番ビルドではロギングを無効にすることをお勧めします。

シグネチャ

public SingularConfig withLoggingEnabled();

使用例

Kotlin Java
// Enable logging for debug builds
val config = SingularConfig("API_KEY", "SECRET")
    .withLoggingEnabled()

withOAIDCollection

SingularConfig.withOAIDCollection メソッド

OAID(Open Anonymous Device Identifier)の収集を有効にします。これは主にGoogle Play Servicesが利用できない中国でのトラッキングに使用されます。

シグネチャ

public SingularConfig withOAIDCollection();

使用例

Kotlin Java
// Enable OAID collection for China
val config = SingularConfig("API_KEY", "SECRET")
    .withOAIDCollection()

withOpenURI

SingularConfig.withOpenURI メソッド

アプリを開いたURIを設定します。これはディープリンクのアトリビューションに使用され、アプリがディープリンクを介して開かれた場合に設定する必要があります。

シグネチャ

public SingularConfig withOpenURI(Uri openUri);

使用例

Kotlin Java
// In your Activity's onCreate or onNewIntent
val uri = intent.data
val config = SingularConfig("API_KEY", "SECRET")
    .withOpenURI(uri)

withPushNotificationPayload

SingularConfig.withPushNotificationPayload メソッド

アトリビューション用のプッシュ通知ペイロードを設定します。これにより、SDKは初期化時にプッシュ通知データを処理できます。

シグネチャ

public SingularConfig withPushNotificationPayload(Intent intent, String[] ... pushNotificationLinkPath);

使用例

Kotlin Java
// Set push notification payload with custom link paths
val config = SingularConfig("API_KEY", "SECRET")
    .withPushNotificationPayload(
        intent,
        arrayOf("data", "deeplink"),
        arrayOf("notification", "data", "url"),
        arrayOf("custom", "link")
    )

withSdidAccessorHandler

SingularConfig.withSdidAccessorHandler メソッド

エンタープライズ機能: SDID(Singular Device ID)を受信したときに呼び出されるコールバック関数を設定します。これにより、SDIDが利用可能になり次第すぐにアクセスできます。

シグネチャ

public SingularConfig withSdidAccessorHandler(SDIDAccessorHandler accessorHandler);

使用例

Kotlin Java
// Set callback for when SDID is received
val config = SingularConfig("API_KEY", "SECRET")
    .withSdidAccessorHandler(object : SDIDAccessorHandler {
        override fun didSetSdid(result: String) {
            println("SDID was set: $result")
        }

        override fun sdidReceived(result: String) {
            println("SDID received: $result")
            // Store or use the SDID as needed
            storeDeviceIdentifier(result)
        }
    })

withSessionTimeoutInSec

SingularConfig.withSessionTimeoutInSec メソッド

セッションタイムアウトを秒単位で設定します。これにより、アプリがバックグラウンドに移行した後、ユーザーセッションがどのくらい持続するかが決まります。デフォルト値は60秒です。

シグネチャ

public SingularConfig withSessionTimeoutInSec(long timeout);

使用例

Kotlin Java
// Set session timeout to 2 minutes
val config = SingularConfig("API_KEY", "SECRET")
    .withSessionTimeoutInSec(120)

withSingularDeviceAttribution

SingularConfig.withSingularDeviceAttribution メソッド

BETA機能: /start レスポンスでデバイスアトリビューションデータが利用可能になったときに呼び出されるコールバック関数を設定します。コールバックはバックグラウンドスレッドで発火するため、UI作業はメインスレッドにディスパッチしてください。

キー 備考
network String アトリビューションソース。アトリビューションされていないインストールの場合は "organic" です。
campaign_id String アトリビューションされた場合にのみ存在します。
campaign_name String アトリビューションされた場合にのみ存在します。
click_timestamp Long(エポックマイクロ秒) アトリビューションされた場合にのみ存在します。秒に変換するには1,000,000で割ります。

コールバックは、 /start レスポンスに attribution_info オブジェクトが含まれている場合にのみ呼び出されます。オーガニックインストールの場合、networkのみが入力されます。

シグネチャ

public SingularConfig withSingularDeviceAttribution(SingularDeviceAttributionHandler handler);

使用例

Kotlin Java
// Set device attribution callback
val config = SingularConfig("API_KEY", "SECRET")
      .withSingularDeviceAttribution { attributionData ->
          println("Attribution data received: $attributionData")

          val source         = attributionData["network"]        as? String
          val campaignName   = attributionData["campaign_name"]  as? String
          val campaignId     = attributionData["campaign_id"]    as? String
          val clickTimestamp = attributionData["click_timestamp"]?.toString()?.toLongOrNull()

          campaignName?.let { showCampaignSpecificContent(it) }
      }

withSingularLink

SingularConfig.withSingularLink メソッド

アトリビューション用のSingular Links(ディープリンク)を構成します。このメソッドは、ディープリンクを処理するハンドラと、短縮リンク解決のタイムアウトを設定します。

shortlinkTimeoutSec引数を省略した場合、SDKはデフォルトの10秒を使用します。インテントアクションが ACTION_VIEWの場合、SDKはセッションをディープリンクで開いたものとしてマークします。

シグネチャ

public SingularConfig withSingularLink(Intent intent, SingularLinkHandler handler);

public SingularConfig withSingularLink(Intent intent, SingularLinkHandler handler,
                                       long shortlinkTimeoutSec);

使用例

Kotlin Java
// Set Singular Links handler
val config = SingularConfig("API_KEY", "SECRET")
    .withSingularLink(intent, { params ->
        // Check if we have a deep link
        params.deeplink?.let { deeplink ->
            println("Deep link received: $deeplink")
            // Navigate based on the deep link
            navigateToScreen(deeplink)
        }

        // Check if this is a deferred deep link
        if (params.isDeferred) {
            println("This is a deferred deep link")
        }

        // Access passthrough parameters
        params.passthrough?.let { passthrough ->
            println("Passthrough data: $passthrough")
        }
    }, 10)