Android SDK - メソッドリファレンス
この包括的なリファレンスは、Androidアプリケーション向けSingular SDKで使用可能なすべてのメソッドを文書化しています。SDKは初期化、イベントトラッキング、収益レポート、アトリビューション、データプライバシーコンプライアンス、構成の機能を提供します。各メソッドには、説明、シグネチャ、実用的な使用例が記載されており、開発者がSingular SDKの機能をアプリケーションに統合するのに役立ちます。
adRevenue
Singular.adRevenue メソッド
詳細な広告データ情報とともに広告収益イベントをトラッキングします。このメソッドにより、アプリケーションに表示された広告から発生した収益をレポートできます。
シグネチャ
public static void adRevenue(SingularAdData adData);
使用例
// 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)
// Create ad data object
SingularAdData adData = new SingularAdData("AdMob", "USD", 0.05)
.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();
使用例
// Clear all global properties
Singular.clearGlobalProperties()
// Clear all global properties
Singular.clearGlobalProperties();
createReferrerShortLink
Singular.createReferrerShortLink メソッド
共有およびアトリビューションに使用できるリファラー情報を含む短縮リンクを作成します。このメソッドは、ユーザーと共有できるトラッキング可能なリンクを生成し、インストールやアクティビティを特定のリファラルソースにアトリビューションできるようにします。
シグネチャ
public static void createReferrerShortLink(String baseLink, String referrerName, String referrerId,
JSONObject passthroughParams, ShortLinkHandler shortLinkHandler);
使用例
// 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")
}
}
)
// Create a short link for referral
try {
JSONObject passthroughParams = new JSONObject();
passthroughParams.put("channel", "sms");
passthroughParams.put("campaign", "summer_promo");
Singular.createReferrerShortLink(
"https://sample.sng.link/B4tbm/v8fp",
"John Doe",
"aq239897",
passthroughParams,
new ShortLinkHandler() {
@Override
public void onSuccess(String link) {
System.out.println("Generated short link: " + link);
// Share the link with users
}
@Override
public void onError(String error) {
System.out.println("Error creating short link: " + error);
}
}
);
} catch (JSONException e) {
e.printStackTrace();
}
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);
使用例
// 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)
// Track a custom revenue event
Singular.customRevenue("premium_subscription", "USD", 9.99);
// Track a custom revenue event with attributes
Map<String, Object> attributes = new HashMap<>();
attributes.put("product_id", "com.app.gems_pack_small");
attributes.put("quantity", 1);
Singular.customRevenue("in_app_purchase", "USD", 5.99, attributes);
// Track a custom revenue event from a pre-built JSON payload
try {
JSONObject customRevenueJson = new JSONObject();
customRevenueJson.put("currency", "USD");
customRevenueJson.put("amount", 5.99);
customRevenueJson.put("product_id", "com.app.gems_pack_small");
Singular.customRevenue("in_app_purchase", customRevenueJson);
} catch (JSONException e) {
e.printStackTrace();
}
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);
使用例
// 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"
)
// 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);
使用例
// 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)
// Track an event with JSON object
try {
JSONObject eventData = new JSONObject();
eventData.put("level_id", 5);
eventData.put("score", 12500);
eventData.put("time_spent", 120);
eventData.put("difficulty", "medium");
Singular.eventJSON("level_completed", eventData);
} catch (JSONException e) {
e.printStackTrace();
}
getGlobalProperties
Singular.getGlobalProperties メソッド
現在設定されているすべてのグローバルプロパティを取得します。このメソッドは、SDKに設定されたすべてのグローバルプロパティを含むマップを返します。
シグネチャ
public static Map<String, String> getGlobalProperties();
使用例
// Get all global properties
val properties = Singular.getGlobalProperties()
println("Global properties: $properties")
// Get all global properties
Map<String, String> properties = Singular.getGlobalProperties();
System.out.println("Global properties: " + properties);
getLimitDataSharing
Singular.getLimitDataSharing メソッド
現在のデータ共有制限ステータスを取得します。このメソッドは、データ共有が現在制限されているかどうかを示すブール値を返します。
SDKが初期化されていない場合、
SingularConfig.withLimitDataSharingで以前に設定された値に関係なく
falseを返します。
falseをユーザーがオプトインした証拠としてではなく、文脈の中で確認してください。
シグネチャ
public static boolean getLimitDataSharing();
使用例
// Check if data sharing is limited
val isLimited = Singular.getLimitDataSharing()
if (isLimited) {
println("Data sharing is currently limited")
}
// Check if data sharing is limited
boolean isLimited = Singular.getLimitDataSharing();
if (isLimited) {
System.out.println("Data sharing is currently limited");
}
getSessionId
Singular.getSessionId メソッド
現在のセッションIDを返します。これは、同じセッション内のイベントを追跡し相関させるために使用できます。
SDKが初期化されていない場合、
Constants.INVALIDを返します。この値に依存する前に、必ず
Singular.init()を呼び出してください。
シグネチャ
public static long getSessionId();
使用例
// Get the current session ID
val sessionId = Singular.getSessionId()
println("Current session ID: $sessionId")
// Get the current session ID
long sessionId = Singular.getSessionId();
System.out.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);
使用例
// 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)
// Simple initialization with API key and secret
Singular.init(context, "SDK KEY", "YOUR_SECRET");
// Initialize with configuration object
SingularConfig config = new SingularConfig("SDK KEY", "YOUR_SECRET")
.withCustomUserId("user_123456")
.withSessionTimeoutInSec(60);
Singular.init(context, config);
isAllTrackingStopped
Singular.isAllTrackingStopped メソッド
すべてのトラッキングが現在停止しているかどうかを確認します。このメソッドは、トラッキングが現在停止しているかどうかを示すブール値を返します。
SDKが初期化されていない場合、
falseを返します。
falseを「アクティブにトラッキング中」ではなく「停止していないか初期化されていない」として扱ってください。
シグネチャ
public static boolean isAllTrackingStopped();
使用例
// Check if tracking is stopped
if (Singular.isAllTrackingStopped()) {
println("Tracking is currently stopped")
}
// Check if tracking is stopped
if (Singular.isAllTrackingStopped()) {
System.out.println("Tracking is currently stopped");
}
limitDataSharing
Singular.limitDataSharing メソッド
データ共有制限のステータスを設定します。ユーザーの同意またはプライバシー要件に基づいてデータ共有を制限するには、このメソッドを使用してください。
シグネチャ
public static void limitDataSharing(boolean shouldLimitDataSharing);
使用例
// 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)
// 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();
使用例
override fun onPause() {
super.onPause()
Singular.onActivityPaused()
}
@Override
protected void onPause() {
super.onPause();
Singular.onActivityPaused();
}
onActivityResumed
Singular.onActivityResumed メソッド
アクティビティが再開されたときにSDKに通知します。セッションのライフサイクルをトラッキングするため、アクティビティのonResume()メソッドから呼び出してください。
シグネチャ
public static void onActivityResumed();
使用例
override fun onResume() {
super.onResume()
Singular.onActivityResumed()
}
@Override
protected void onResume() {
super.onResume();
Singular.onActivityResumed();
}
resumeAllTracking
Singular.resumeAllTracking メソッド
以前に停止したすべてのトラッキングアクティビティを再開します。トラッキングを停止した後、再有効化するにはこのメソッドを使用してください。
シグネチャ
public static void resumeAllTracking();
使用例
// Resume tracking when user opts back in
Singular.resumeAllTracking()
// 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);
使用例
// 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)
// Track revenue with currency and amount
Singular.revenue("USD", 9.99);
// Track revenue with additional attributes
Map<String, Object> attributes = new HashMap<>();
attributes.put("product_id", "premium_gems");
attributes.put("quantity", 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
try {
JSONObject revenueJson = new JSONObject();
revenueJson.put("currency", "USD");
revenueJson.put("amount", 9.99);
revenueJson.put("product_id", "premium_gems");
Singular.revenue(revenueJson);
} catch (JSONException e) {
e.printStackTrace();
}
setCustomUserId
Singular.setCustomUserId メソッド
現在のユーザーに対するカスタムユーザーIDを設定します。これにより、Singularデータを独自のユーザー識別システムと関連付けることができます。
シグネチャ
public static void setCustomUserId(String customUserId);
使用例
// Set custom user ID after user logs in
Singular.setCustomUserId("user_123456")
// Set custom user ID after user logs in
Singular.setCustomUserId("user_123456");
setDeviceCustomUserId
非推奨機能: 代わりに setCustomUserId を使用してください。
Singular.setDeviceCustomUserId メソッド
デバイスレベルでカスタムユーザーIDを設定します。これにより、Singularデータをデバイスレベルで独自のユーザー識別システムと関連付けることができます。
シグネチャ
public static void setDeviceCustomUserId(String customUserId);
使用例
// Set device-level custom user ID
Singular.setDeviceCustomUserId("device_user_123456")
// 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);
使用例
// In your Firebase Messaging Service
override fun onNewToken(token: String) {
super.onNewToken(token)
Singular.setFCMDeviceToken(token)
}
// In your Firebase Messaging Service
@Override
public void onNewToken(String token) {
super.onNewToken(token);
Singular.setFCMDeviceToken(token);
}
setGCMDeviceToken
非推奨機能: 代わりに setFCMDeviceToken を使用してください。
Singular.setGCMDeviceToken メソッド
GCM(Google Cloud Messaging)デバイストークンを設定します。このメソッドは非推奨です。Firebase Cloud Messagingでは setFCMDeviceToken を代わりに使用してください。
シグネチャ
public static void setGCMDeviceToken(String gcmDeviceToken);
使用例
// Deprecated - use setFCMDeviceToken instead
Singular.setGCMDeviceToken(token)
// 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);
使用例
// Set a global property
val success = Singular.setGlobalProperty("user_tier", "premium", true)
if (success) {
println("Global property set successfully")
}
// Set a global property
boolean success = Singular.setGlobalProperty("user_tier", "premium", true);
if (success) {
System.out.println("Global property set successfully");
}
setIMEI
Singular.setIMEI メソッド
トラッキング用のデバイスIMEIを設定します。IMEIトラッキングが許可され、推奨される地域で有用です。
シグネチャ
public static void setIMEI(String imei);
使用例
// Set device IMEI
Singular.setIMEI("123456789012345")
// Set device IMEI
Singular.setIMEI("123456789012345");
setLimitAdvertisingIdentifiers
Singular.setLimitAdvertisingIdentifiers メソッド
混合オーディエンスアプリで広告識別子の使用を有効または無効にします。このオプションは、SDKがトラッキング用のデバイス識別子を収集および使用する方法に影響します。
シグネチャ
public static void setLimitAdvertisingIdentifiers(boolean enabled);
使用例
// Enable limited identifiers mode
Singular.setLimitAdvertisingIdentifiers(true)
// Enable limited identifiers mode
Singular.setLimitAdvertisingIdentifiers(true);
setWrapperNameAndVersion
Singular.setWrapperNameAndVersion メソッド
ラッパー(例:Unity、React Native)を介してSDKを使用する場合に、ラッパー名とバージョンを設定します。これは、使用されているラッパーフレームワークを識別するのに役立ちます。
シグネチャ
public static void setWrapperNameAndVersion(final String wrapper, final String version);
使用例
// Set wrapper information
Singular.setWrapperNameAndVersion("Unity", "1.2.3")
// Set wrapper information
Singular.setWrapperNameAndVersion("Unity", "1.2.3");
stopAllTracking
Singular.stopAllTracking メソッド
すべてのトラッキングアクティビティを停止します。ユーザーがオプトアウトする場合、またはプライバシーコンプライアンスのためにトラッキングを無効にするには、このメソッドを使用してください。
シグネチャ
public static void stopAllTracking();
使用例
// Stop tracking when user opts out
Singular.stopAllTracking()
// Stop tracking when user opts out
Singular.stopAllTracking();
trackingOptIn
Singular.trackingOptIn メソッド
ユーザーがトラッキングにオプトインしたことを示します。ユーザーがトラッキングおよびデータ収集に明示的に同意した場合に、このメソッドを呼び出してください。
シグネチャ
public static void trackingOptIn();
使用例
// User has opted in to tracking
Singular.trackingOptIn()
// User has opted in to tracking
Singular.trackingOptIn();
trackingUnder13
Singular.trackingUnder13 メソッド
ユーザーが13歳未満であることを示します。13歳未満のユーザーに対するCOPPAおよびその他の規制を遵守するには、このメソッドを呼び出してください。
シグネチャ
public static void trackingUnder13();
使用例
// Notify Singular the user is under 13 years old
Singular.trackingUnder13()
// Notify Singular the user is under 13 years old
Singular.trackingUnder13();
unsetCustomUserId
Singular.unsetCustomUserId メソッド
以前に設定されたカスタムユーザーIDを削除します。ユーザーがログアウトした場合、または現在のユーザーIDとイベントを関連付けたくなくなった場合に、このメソッドを呼び出してください。
シグネチャ
public static void unsetCustomUserId();
使用例
// Clear custom user ID when user logs out
Singular.unsetCustomUserId()
// Clear custom user ID when user logs out
Singular.unsetCustomUserId();
unsetGlobalProperty
Singular.unsetGlobalProperty メソッド
以前に設定されたグローバルプロパティを削除します。特定のグローバルプロパティをイベントとともに送信したくなくなった場合に、このメソッドを呼び出してください。
シグネチャ
public static void unsetGlobalProperty(String key);
使用例
// Remove a global property
Singular.unsetGlobalProperty("user_tier")
// Remove a global property
Singular.unsetGlobalProperty("user_tier");