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

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

この包括的なリファレンスは、Androidアプリケーション向けSingular SDKで使用可能なすべてのメソッドを文書化しています。SDKは初期化、イベントトラッキング、収益レポート、アトリビューション、データプライバシーコンプライアンス、構成の機能を提供します。各メソッドには、説明、シグネチャ、実用的な使用例が記載されており、開発者がSingular SDKの機能をアプリケーションに統合するのに役立ちます。

adRevenue

Singular.adRevenue メソッド

詳細な広告データ情報とともに広告収益イベントをトラッキングします。このメソッドにより、アプリケーションに表示された広告から発生した収益をレポートできます。

シグネチャ

public static void adRevenue(SingularAdData adData);

使用例

Kotlin Java
// Create ad data object
val adData = SingularAdData("AdMob", "USD", 0.05).apply {
    withAdUnitId("ca-app-pub-123456789/1234567890")
    withAdType("Rewarded")
    withAdPlacementName("level_complete")
}

// Track ad revenue event
Singular.adRevenue(adData)

clearGlobalProperties

Singular.clearGlobalProperties メソッド

以前に設定されたすべてのグローバルプロパティを削除します。ユーザーがアプリケーションからログアウトする場合など、グローバルプロパティをリセットする必要があるときに役立ちます。

シグネチャ

public static void clearGlobalProperties();

使用例

Kotlin Java
// Clear all global properties
Singular.clearGlobalProperties()

createReferrerShortLink

Singular.createReferrerShortLink メソッド

共有およびアトリビューションに使用できるリファラー情報を含む短縮リンクを作成します。このメソッドは、ユーザーと共有できるトラッキング可能なリンクを生成し、インストールやアクティビティを特定のリファラルソースにアトリビューションできるようにします。

シグネチャ

public static void createReferrerShortLink(String baseLink, String referrerName, String referrerId,
                                            JSONObject passthroughParams, ShortLinkHandler shortLinkHandler);

使用例

Kotlin Java
// Create a short link for referral
val passthroughParams = JSONObject().apply {
    put("channel", "sms")
    put("campaign", "summer_promo")
}

Singular.createReferrerShortLink(
    "https://sample.sng.link/B4tbm/v8fp",
    "John Doe",
    "aq239897",
    passthroughParams,
    object : ShortLinkHandler {
        override fun onSuccess(link: String) {
            println("Generated short link: $link")
            // Share the link with users
        }

        override fun onError(error: String) {
            println("Error creating short link: $error")
        }
    }
)

customRevenue

Singular.customRevenue メソッド

指定したイベント名、通貨、金額、およびオプションの製品情報とともにカスタム収益イベントをトラッキングします。これにより、カスタムイベント名でより具体的な収益トラッキングが可能になります。

purchaseオブジェクトを渡すとき、SDKはオブジェクトが com.android.billingclient.api.Purchaseインスタンスである場合にのみレシート、署名、SKUの詳細を抽出します。それ以外の型は、通貨と金額のみを含む基本的な収益イベントにフォールバックします。

シグネチャ

public static boolean customRevenue(String eventName, String currency, double amount, Object purchase);

public static boolean customRevenue(String eventName, String currency, double amount, Object purchase,
                                    Map<String, Object> attributes);

public static boolean customRevenue(String eventName, String currency, double amount);

public static boolean customRevenue(String eventName, String currency, double amount,
                                    Map<String, Object> attributes);

public static boolean customRevenue(String eventName, String currency, double amount,
                                    String receipt, String receiptSignature);

public static boolean customRevenue(String eventName, String currency, double amount, String productSKU,
                                    String productName, String productCategory, int productQuantity,
                                    double productPrice);

public static boolean customRevenue(String eventName, JSONObject json);

使用例

Kotlin Java
// Track a custom revenue event
Singular.customRevenue("premium_subscription", "USD", 9.99)

// Track a custom revenue event with attributes
val attributes = mapOf(
    "product_id" to "com.app.gems_pack_small",
    "quantity" to 1
)
Singular.customRevenue("in_app_purchase", "USD", 5.99, attributes)

// Track a custom revenue event from a pre-built JSON payload
val customRevenueJson = JSONObject().apply {
    put("currency", "USD")
    put("amount", 5.99)
    put("product_id", "com.app.gems_pack_small")
}
Singular.customRevenue("in_app_purchase", customRevenueJson)

event

Singular.event メソッド

指定された名前とオプションのカスタム属性でイベントをトラッキングします。これらのメソッドを使用して、アプリケーション内のユーザーアクションとエンゲージメントをトラッキングしてください。

可変長引数のオーバーロードはキー/値のペアを期待するため、 argsは偶数個の要素を含む必要があります。奇数個の場合、イベントは送信されず falseを返します。

シグネチャ

public static boolean event(String name);

public static boolean event(String name, String extra);

public static boolean event(String name, Object... args);

使用例

Kotlin Java
// Track a simple event
Singular.event("level_completed")

// Track an event with variable arguments
Singular.event("level_completed",
    "level_id", 5,
    "score", 12500,
    "time_spent", 120,
    "difficulty", "medium"
)

eventJSON

Singular.eventJSON メソッド

カスタム属性を含むJSONオブジェクトでイベントをトラッキングします。このメソッドは、複雑なイベントデータ構造により高い柔軟性を提供します。

シグネチャ

public static boolean eventJSON(String name, final JSONObject json);

使用例

Kotlin Java
// Track an event with JSON object
val eventData = JSONObject().apply {
    put("level_id", 5)
    put("score", 12500)
    put("time_spent", 120)
    put("difficulty", "medium")
}
Singular.eventJSON("level_completed", eventData)

getGlobalProperties

Singular.getGlobalProperties メソッド

現在設定されているすべてのグローバルプロパティを取得します。このメソッドは、SDKに設定されたすべてのグローバルプロパティを含むマップを返します。

シグネチャ

public static Map<String, String> getGlobalProperties();

使用例

Kotlin Java
// Get all global properties
val properties = Singular.getGlobalProperties()
println("Global properties: $properties")

getLimitDataSharing

Singular.getLimitDataSharing メソッド

現在のデータ共有制限ステータスを取得します。このメソッドは、データ共有が現在制限されているかどうかを示すブール値を返します。

SDKが初期化されていない場合、 SingularConfig.withLimitDataSharingで以前に設定された値に関係なく falseを返します。 falseをユーザーがオプトインした証拠としてではなく、文脈の中で確認してください。

シグネチャ

public static boolean getLimitDataSharing();

使用例

Kotlin Java
// Check if data sharing is limited
val isLimited = Singular.getLimitDataSharing()
if (isLimited) {
    println("Data sharing is currently limited")
}

getSessionId

Singular.getSessionId メソッド

現在のセッションIDを返します。これは、同じセッション内のイベントを追跡し相関させるために使用できます。

SDKが初期化されていない場合、 Constants.INVALIDを返します。この値に依存する前に、必ず Singular.init()を呼び出してください。

シグネチャ

public static long getSessionId();

使用例

Kotlin Java
// Get the current session ID
val sessionId = Singular.getSessionId()
println("Current session ID: $sessionId")

init

Singular.init メソッド

提供されたAPIキーとシークレット、または構成オブジェクトを使用してSingular SDKを初期化します。Singular SDKの使用を開始するには、まずこのメソッドを呼び出す必要があります。

シグネチャ

public static boolean init(final Context context, final String apiKey, final String secret);

public static boolean init(final Context context, final SingularConfig config);

使用例

Kotlin Java
// Simple initialization with API key and secret
Singular.init(context, "SDK KEY", "YOUR_SECRET")

// Initialize with configuration object
val config = SingularConfig("SDK KEY", "YOUR_SECRET")
    .withCustomUserId("user_123456")
    .withSessionTimeoutInSec(60)

Singular.init(context, config)

isAllTrackingStopped

Singular.isAllTrackingStopped メソッド

すべてのトラッキングが現在停止しているかどうかを確認します。このメソッドは、トラッキングが現在停止しているかどうかを示すブール値を返します。

SDKが初期化されていない場合、 falseを返します。 falseを「アクティブにトラッキング中」ではなく「停止していないか初期化されていない」として扱ってください。

シグネチャ

public static boolean isAllTrackingStopped();

使用例

Kotlin Java
// Check if tracking is stopped
if (Singular.isAllTrackingStopped()) {
    println("Tracking is currently stopped")
}

limitDataSharing

Singular.limitDataSharing メソッド

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

シグネチャ

public static void limitDataSharing(boolean shouldLimitDataSharing);

使用例

Kotlin Java
// To limit data sharing (e.g., when user opts out)
Singular.limitDataSharing(true)

// To enable full data sharing (e.g., when user opts in)
Singular.limitDataSharing(false)

onActivityPaused

Singular.onActivityPaused メソッド

アクティビティが一時停止されたときにSDKに通知します。セッションのライフサイクルをトラッキングするため、アクティビティのonPause()メソッドから呼び出してください。

シグネチャ

public static void onActivityPaused();

使用例

Kotlin Java
override fun onPause() {
    super.onPause()
    Singular.onActivityPaused()
}

onActivityResumed

Singular.onActivityResumed メソッド

アクティビティが再開されたときにSDKに通知します。セッションのライフサイクルをトラッキングするため、アクティビティのonResume()メソッドから呼び出してください。

シグネチャ

public static void onActivityResumed();

使用例

Kotlin Java
override fun onResume() {
    super.onResume()
    Singular.onActivityResumed()
}

resumeAllTracking

Singular.resumeAllTracking メソッド

以前に停止したすべてのトラッキングアクティビティを再開します。トラッキングを停止した後、再有効化するにはこのメソッドを使用してください。

シグネチャ

public static void resumeAllTracking();

使用例

Kotlin Java
// Resume tracking when user opts back in
Singular.resumeAllTracking()

revenue

Singular.revenue メソッド

通貨、金額、製品の詳細を含むさまざまなパラメータで収益イベントをトラッキングします。これにより、アプリケーションの包括的な収益トラッキングが可能になります。

purchaseオブジェクトを渡すとき、SDKはオブジェクトが com.android.billingclient.api.Purchaseインスタンスである場合にのみレシート、署名、SKUの詳細を抽出します。それ以外の型は、通貨と金額のみを含む基本的な収益イベントにフォールバックします。

シグネチャ

public static boolean revenue(String currency, double amount, Object purchase);

public static boolean revenue(String currency, double amount, Object purchase, Map<String, Object> attributes);

public static boolean revenue(String currency, double amount);

public static boolean revenue(String currency, double amount, Map<String, Object> attributes);

public static boolean revenue(String currency, double amount, String receipt, String receiptSignature);

public static boolean revenue(String currency, double amount, String productSKU, String productName,
                              String productCategory, int productQuantity, double productPrice);

public static boolean revenue(JSONObject json);

使用例

Kotlin Java
// Track revenue with currency and amount
Singular.revenue("USD", 9.99)

// Track revenue with additional attributes
val attributes = mapOf(
    "product_id" to "premium_gems",
    "quantity" to 2
)
Singular.revenue("USD", 19.98, attributes)

// Track revenue with Google Play purchase object
Singular.revenue("USD", 9.99, purchase)

// Track revenue with detailed product information
Singular.revenue("USD", 19.98,
    "SKU123456",
    "Premium Sword",
    "Weapons",
    2,
    9.99
)

// Track revenue from a pre-built JSON payload
val revenueJson = JSONObject().apply {
    put("currency", "USD")
    put("amount", 9.99)
    put("product_id", "premium_gems")
}
Singular.revenue(revenueJson)

setCustomUserId

Singular.setCustomUserId メソッド

現在のユーザーに対するカスタムユーザーIDを設定します。これにより、Singularデータを独自のユーザー識別システムと関連付けることができます。

シグネチャ

public static void setCustomUserId(String customUserId);

使用例

Kotlin Java
// Set custom user ID after user logs in
Singular.setCustomUserId("user_123456")

setDeviceCustomUserId

非推奨機能: 代わりに setCustomUserId を使用してください。

Singular.setDeviceCustomUserId メソッド

デバイスレベルでカスタムユーザーIDを設定します。これにより、Singularデータをデバイスレベルで独自のユーザー識別システムと関連付けることができます。

シグネチャ

public static void setDeviceCustomUserId(String customUserId);

使用例

Kotlin Java
// Set device-level custom user ID
Singular.setDeviceCustomUserId("device_user_123456")

setFCMDeviceToken

Singular.setFCMDeviceToken メソッド

プッシュ通知とアンインストールトラッキング用のFCM(Firebase Cloud Messaging)デバイストークンを設定します。FCMトークンを受信したときに呼び出してください。

シグネチャ

public static void setFCMDeviceToken(String fcmDeviceToken);

使用例

Kotlin Java
// In your Firebase Messaging Service
override fun onNewToken(token: String) {
    super.onNewToken(token)
    Singular.setFCMDeviceToken(token)
}

setGCMDeviceToken

非推奨機能: 代わりに setFCMDeviceToken を使用してください。

Singular.setGCMDeviceToken メソッド

GCM(Google Cloud Messaging)デバイストークンを設定します。このメソッドは非推奨です。Firebase Cloud Messagingでは setFCMDeviceToken を代わりに使用してください。

シグネチャ

public static void setGCMDeviceToken(String gcmDeviceToken);

使用例

Kotlin Java
// Deprecated - use setFCMDeviceToken instead
Singular.setGCMDeviceToken(token)

setGlobalProperty

Singular.setGlobalProperty メソッド

すべてのイベントとともに送信されるグローバルプロパティを設定します。これにより、毎回指定しなくてもすべてのイベントに一貫した属性を追加できます。

キーがnullまたは空の場合、SDKが初期化されていない場合、またはSDKが既に最大5個のグローバルプロパティを保持している場合、 falseを返します。プロパティが保存されたと想定する前に、戻り値を確認してください。

シグネチャ

public static boolean setGlobalProperty(final String key, final String value,
                                        final boolean overrideExisting);

使用例

Kotlin Java
// Set a global property
val success = Singular.setGlobalProperty("user_tier", "premium", true)
if (success) {
    println("Global property set successfully")
}

setIMEI

Singular.setIMEI メソッド

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

シグネチャ

public static void setIMEI(String imei);

使用例

Kotlin Java
// Set device IMEI
Singular.setIMEI("123456789012345")

setLimitAdvertisingIdentifiers

Singular.setLimitAdvertisingIdentifiers メソッド

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

シグネチャ

public static void setLimitAdvertisingIdentifiers(boolean enabled);

使用例

Kotlin Java
// Enable limited identifiers mode
Singular.setLimitAdvertisingIdentifiers(true)

setWrapperNameAndVersion

Singular.setWrapperNameAndVersion メソッド

ラッパー(例:Unity、React Native)を介してSDKを使用する場合に、ラッパー名とバージョンを設定します。これは、使用されているラッパーフレームワークを識別するのに役立ちます。

シグネチャ

public static void setWrapperNameAndVersion(final String wrapper, final String version);

使用例

Kotlin Java
// Set wrapper information
Singular.setWrapperNameAndVersion("Unity", "1.2.3")

stopAllTracking

Singular.stopAllTracking メソッド

すべてのトラッキングアクティビティを停止します。ユーザーがオプトアウトする場合、またはプライバシーコンプライアンスのためにトラッキングを無効にするには、このメソッドを使用してください。

シグネチャ

public static void stopAllTracking();

使用例

Kotlin Java
// Stop tracking when user opts out
Singular.stopAllTracking()

trackingOptIn

Singular.trackingOptIn メソッド

ユーザーがトラッキングにオプトインしたことを示します。ユーザーがトラッキングおよびデータ収集に明示的に同意した場合に、このメソッドを呼び出してください。

シグネチャ

public static void trackingOptIn();

使用例

Kotlin Java
// User has opted in to tracking
Singular.trackingOptIn()

trackingUnder13

Singular.trackingUnder13 メソッド

ユーザーが13歳未満であることを示します。13歳未満のユーザーに対するCOPPAおよびその他の規制を遵守するには、このメソッドを呼び出してください。

シグネチャ

public static void trackingUnder13();

使用例

Kotlin Java
// Notify Singular the user is under 13 years old
Singular.trackingUnder13()

unsetCustomUserId

Singular.unsetCustomUserId メソッド

以前に設定されたカスタムユーザーIDを削除します。ユーザーがログアウトした場合、または現在のユーザーIDとイベントを関連付けたくなくなった場合に、このメソッドを呼び出してください。

シグネチャ

public static void unsetCustomUserId();

使用例

Kotlin Java
// Clear custom user ID when user logs out
Singular.unsetCustomUserId()

unsetGlobalProperty

Singular.unsetGlobalProperty メソッド

以前に設定されたグローバルプロパティを削除します。特定のグローバルプロパティをイベントとともに送信したくなくなった場合に、このメソッドを呼び出してください。

シグネチャ

public static void unsetGlobalProperty(String key);

使用例

Kotlin Java
// Remove a global property
Singular.unsetGlobalProperty("user_tier")