Android SDK - 構成リファレンス
このドキュメントは、Androidアプリケーション向けSingular SDKで利用可能なすべての構成オプションに関する包括的なリファレンスを提供します。SingularConfigオブジェクトを使用すると、トラッキング設定、アトリビューションオプション、プライバシー制御などを含むSDKの動作をカスタマイズできます。各構成メソッドには、説明、シグネチャ、実用的な使用例が記載されています。
完全な構成例
包括的なSDK構成
次の例は、複数の構成メソッドを連結して包括的な構成を作成する方法を示しています。
完全な例
// 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)
// Create comprehensive configuration
SingularConfig config = new 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(getIntent().getData())
.withSingularLink(getIntent(), new SingularLinkHandler() {
@Override
public void onResolved(SingularLinkParams params) {
if (params.getDeeplink() != null) {
System.out.println("Deep link: " + params.getDeeplink());
handleDeepLink(params.getDeeplink());
}
}
}, 10)
// Attribution callback
.withSingularDeviceAttribution(new SingularDeviceAttributionHandler() {
@Override
public void onDeviceAttributionInfoReceived(Map<String, Object> attributionData) {
System.out.println("Attribution: " + attributionData);
}
})
// Push notifications
.withFCMDeviceToken(fcmToken)
// Privacy settings
.withLimitDataSharing(false)
// Email attribution
.withESPDomains(Arrays.asList("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);
使用例
// Create configuration object
val config = SingularConfig("SDK KEY", "YOUR_SECRET")
// Create configuration object
SingularConfig config = new SingularConfig("SDK KEY", "YOUR_SECRET");
withBrandedDomains
SingularConfig.withBrandedDomains メソッド
ウェブからアプリへのアトリビューション用のブランドドメインを設定します。アトリビューションの目的でトラッキングするカスタムドメインを指定できます。
このメソッドを呼び出すと、以前に設定されたブランドドメインがすべて置き換えられます。複数回連結する代わりに、完全なリストを1回の呼び出しで渡してください。
シグネチャ
public SingularConfig withBrandedDomains(List<String> brandedDomains);
使用例
// Set branded domains for web-to-app attribution
val brandedDomains = listOf("yourcompany.com", "go.yourcompany.com")
val config = SingularConfig("API_KEY", "SECRET")
.withBrandedDomains(brandedDomains)
// Set branded domains for web-to-app attribution
List<String> brandedDomains = Arrays.asList("yourcompany.com", "go.yourcompany.com");
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
.withBrandedDomains(brandedDomains);
withCustomSdid
SingularConfig.withCustomSdid メソッド
エンタープライズ機能: カスタムSDID(Singular Device ID)を設定します。Singularが生成したものの代わりに、独自のデバイス識別子を提供できます。
シグネチャ
public SingularConfig withCustomSdid(String customSdid, SDIDAccessorHandler accessorHandler);
使用例
// 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
}
})
// Set custom SDID with callback
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
.withCustomSdid("custom-device-id-12345", new SDIDAccessorHandler() {
@Override
public void didSetSdid(String result) {
System.out.println("SDID was set: " + result);
// Perform any actions needed after SDID is set
}
@Override
public void sdidReceived(String result) {
System.out.println("SDID received: " + result);
// Existing SDID returned by the SDK
}
});
withCustomUserId
SingularConfig.withCustomUserId メソッド
SDK初期化時にカスタムユーザーIDを設定します。これにより、最初からSingularデータを独自のユーザー識別システムと関連付けることができます。
シグネチャ
public SingularConfig withCustomUserId(String customUserId);
使用例
// Set custom user ID at initialization
val config = SingularConfig("API_KEY", "SECRET")
.withCustomUserId("user_123456")
// Set custom user ID at initialization
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
.withCustomUserId("user_123456");
withESPDomains
SingularConfig.withESPDomains メソッド
メールアトリビューション用のESP(メールサービスプロバイダー)ドメインを設定します。アトリビューションで考慮すべきメールドメインを指定できます。
このメソッドを呼び出すと、以前に設定されたESPドメインがすべて置き換えられます。複数回連結する代わりに、完全なリストを1回の呼び出しで渡してください。
シグネチャ
public SingularConfig withESPDomains(List<String> espDomains);
使用例
// Set ESP domains for email attribution
val espDomains = listOf("mailchimp.com", "sendgrid.net", "campaign-monitor.com")
val config = SingularConfig("API_KEY", "SECRET")
.withESPDomains(espDomains)
// Set ESP domains for email attribution
List<String> espDomains = Arrays.asList("mailchimp.com", "sendgrid.net", "campaign-monitor.com");
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
.withESPDomains(espDomains);
withFacebookAppId
SingularConfig.withFacebookAppId メソッド
Facebookアトリビューション連携用のFacebook App IDを設定します。これにより、SDKがFacebookキャンペーンのアトリビューションをトラッキングできます。
シグネチャ
public SingularConfig withFacebookAppId(String facebookAppId);
使用例
// Set Facebook App ID
val config = SingularConfig("API_KEY", "SECRET")
.withFacebookAppId("YOUR_FACEBOOK_APP_ID")
// Set Facebook App ID
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
.withFacebookAppId("YOUR_FACEBOOK_APP_ID");
withFCMDeviceToken
SingularConfig.withFCMDeviceToken メソッド
初期化時にFCM(Firebase Cloud Messaging)デバイストークンを設定します。これにより、最初からプッシュ通知トラッキングとアンインストール検出を有効にできます。
トークンがnullまたは空の場合、呼び出しは無視されます。有効なFCMトークンを取得した後にのみこのメソッドを呼び出してください。
シグネチャ
public SingularConfig withFCMDeviceToken(String fcmDeviceToken);
使用例
// Set FCM token at initialization if available
val config = SingularConfig("API_KEY", "SECRET")
.withFCMDeviceToken(fcmToken)
// Set FCM token at initialization if available
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
.withFCMDeviceToken(fcmToken);
withGlobalProperty
SingularConfig.withGlobalProperty メソッド
SDK初期化時にグローバルプロパティを設定します。このプロパティは、SDKがトラッキングするすべてのイベントとともに送信されます。連結構成が可能な構成メソッドです。
SDKは最大5個のグローバルプロパティをサポートします。この制限を超える呼び出しは黙って無視されます。
シグネチャ
public SingularConfig withGlobalProperty(String key, String value, boolean overrideExisting);
使用例
// Add global properties at initialization
val config = SingularConfig("API_KEY", "SECRET")
.withGlobalProperty("app_version", "1.2.3", true)
.withGlobalProperty("user_type", "free", true)
// Add global properties at initialization
SingularConfig config = new 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);
使用例
// Set device IMEI at initialization
val config = SingularConfig("API_KEY", "SECRET")
.withIMEI("123456789012345")
// Set device IMEI at initialization
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
.withIMEI("123456789012345");
withLimitAdvertisingIdentifiers
SingularConfig.withLimitAdvertisingIdentifiers メソッド
混合オーディエンスアプリで広告識別子の制限モードを有効にします。このオプションは、SDKがトラッキング用のデバイス識別子を収集および使用する方法に影響します。
シグネチャ
public SingularConfig withLimitAdvertisingIdentifiers();
使用例
// Enable limited identifiers mode
val config = SingularConfig("API_KEY", "SECRET")
.withLimitAdvertisingIdentifiers()
// Enable limited identifiers mode
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
.withLimitAdvertisingIdentifiers();
withLimitDataSharing
SingularConfig.withLimitDataSharing メソッド
初期化時にデータ共有制限のステータスを設定します。ユーザーの同意またはプライバシー要件に基づいてデータ共有を制限するには、このメソッドを使用してください。
シグネチャ
public SingularConfig withLimitDataSharing(boolean shouldLimitDataSharing);
使用例
// Enable limited data sharing at initialization
val config = SingularConfig("API_KEY", "SECRET")
.withLimitDataSharing(true)
// Enable limited data sharing at initialization
SingularConfig config = new 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);
使用例
import android.util.Log
// Set verbose logging for detailed debugging
val config = SingularConfig("API_KEY", "SECRET")
.withLoggingEnabled()
.withLogLevel(Log.VERBOSE)
import android.util.Log;
// Set verbose logging for detailed debugging
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
.withLoggingEnabled()
.withLogLevel(Log.VERBOSE);
withLoggingEnabled
SingularConfig.withLoggingEnabled メソッド
SDKロギングを有効にします。開発時のデバッグやトラブルシューティングに役立ちます。本番ビルドではロギングを無効にすることをお勧めします。
シグネチャ
public SingularConfig withLoggingEnabled();
使用例
// Enable logging for debug builds
val config = SingularConfig("API_KEY", "SECRET")
.withLoggingEnabled()
// Enable logging for debug builds
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
.withLoggingEnabled();
withOAIDCollection
SingularConfig.withOAIDCollection メソッド
OAID(Open Anonymous Device Identifier)の収集を有効にします。これは主にGoogle Play Servicesが利用できない中国でのトラッキングに使用されます。
シグネチャ
public SingularConfig withOAIDCollection();
使用例
// Enable OAID collection for China
val config = SingularConfig("API_KEY", "SECRET")
.withOAIDCollection()
// Enable OAID collection for China
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
.withOAIDCollection();
withOpenURI
SingularConfig.withOpenURI メソッド
アプリを開いたURIを設定します。これはディープリンクのアトリビューションに使用され、アプリがディープリンクを介して開かれた場合に設定する必要があります。
シグネチャ
public SingularConfig withOpenURI(Uri openUri);
使用例
// In your Activity's onCreate or onNewIntent
val uri = intent.data
val config = SingularConfig("API_KEY", "SECRET")
.withOpenURI(uri)
// In your Activity's onCreate or onNewIntent
Uri uri = getIntent().getData();
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
.withOpenURI(uri);
withPushNotificationPayload
SingularConfig.withPushNotificationPayload メソッド
アトリビューション用のプッシュ通知ペイロードを設定します。これにより、SDKは初期化時にプッシュ通知データを処理できます。
シグネチャ
public SingularConfig withPushNotificationPayload(Intent intent, String[] ... pushNotificationLinkPath);
使用例
// 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")
)
// Set push notification payload with custom link paths
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
.withPushNotificationPayload(
intent,
new String[]{"data", "deeplink"},
new String[]{"notification", "data", "url"},
new String[]{"custom", "link"}
);
withSdidAccessorHandler
SingularConfig.withSdidAccessorHandler メソッド
エンタープライズ機能: SDID(Singular Device ID)を受信したときに呼び出されるコールバック関数を設定します。これにより、SDIDが利用可能になり次第すぐにアクセスできます。
シグネチャ
public SingularConfig withSdidAccessorHandler(SDIDAccessorHandler accessorHandler);
使用例
// 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)
}
})
// Set callback for when SDID is received
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
.withSdidAccessorHandler(new SDIDAccessorHandler() {
@Override
public void didSetSdid(String result) {
System.out.println("SDID was set: " + result);
}
@Override
public void sdidReceived(String result) {
System.out.println("SDID received: " + result);
// Store or use the SDID as needed
storeDeviceIdentifier(result);
}
});
withSessionTimeoutInSec
SingularConfig.withSessionTimeoutInSec メソッド
セッションタイムアウトを秒単位で設定します。これにより、アプリがバックグラウンドに移行した後、ユーザーセッションがどのくらい持続するかが決まります。デフォルト値は60秒です。
シグネチャ
public SingularConfig withSessionTimeoutInSec(long timeout);
使用例
// Set session timeout to 2 minutes
val config = SingularConfig("API_KEY", "SECRET")
.withSessionTimeoutInSec(120)
// Set session timeout to 2 minutes
SingularConfig config = new 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);
使用例
// 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) }
}
// Set device attribution callback
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
.withSingularDeviceAttribution(new SingularDeviceAttributionHandler() {
@Override
public void onDeviceAttributionInfoReceived(Map<String, Object> attributionData) {
Log.d("Singular", "Attribution data received: " + attributionData);
String source = (String) attributionData.get("network");
String campaignName = (String) attributionData.get("campaign_name");
String campaignId = (String) attributionData.get("campaign_id");
Object clickTsObj = attributionData.get("click_timestamp");
Long clickTimestamp = clickTsObj != null
? Long.parseLong(clickTsObj.toString())
: null;
if (campaignName != null) {
showCampaignSpecificContent(campaignName);
}
}
});
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);
使用例
// 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)
// Set Singular Links handler
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
.withSingularLink(intent, new SingularLinkHandler() {
@Override
public void onResolved(SingularLinkParams params) {
// Check if we have a deep link
if (params.getDeeplink() != null) {
System.out.println("Deep link received: " + params.getDeeplink());
// Navigate based on the deep link
navigateToScreen(params.getDeeplink());
}
// Check if this is a deferred deep link
if (params.isDeferred()) {
System.out.println("This is a deferred deep link");
}
// Access passthrough parameters
if (params.getPassthrough() != null) {
System.out.println("Passthrough data: " + params.getPassthrough());
}
}
}, 10);