Cordova SDK - SDK メソッドリファレンス
この包括的なリファレンスでは、Singular SDK for Cordova アプリケーションで利用可能なすべてのメソッドについて説明しています。SDKは初期化、ユーザー識別、イベントトラッキング、収益レポート、アトリビューション、データプライバシーコンプライアンス、コンフィギュレーションなどの機能を提供します。各メソッドには説明、署名、実用的な使用例が記載されており、開発者がSingular SDKの機能をアプリケーションに統合するのに役立ちます。
広告収入
Singular.adRevenueメソッド
詳細な広告データ情報で広告収入イベントをトラッキングします。このメソッドを使用すると、アプリケーションに表示された広告から発生した収益を、広告パフォーマンスを分類・分析するための様々なパラメータと共に報告することができます。
シグネチャ
static adRevenue(adData: SingularAdData): void
使用例
// Create ad data object
const adData = new cordova.plugins.SingularCordovaSdk.SingularAdData()
.withAdPlatform("AdMob")
.withAdType("Rewarded")
.withNetworkName("Google")
.withCurrency("USD")
.withRevenue(0.05);
// Track ad revenue event
cordova.plugins.SingularCordovaSdk.adRevenue(adData);
clearGlobalProperties
Singular.clearGlobalPropertiesメソッド
以前に設定されたすべてのグローバルプロパティを削除します。これは、ユーザーがアプリケーションからログアウトした場合など、グローバルプロパティをリセットする必要がある場合に便利です。
シグネチャ
static clearGlobalProperties(): void
使用例
// Clear all global properties, for example when a user logs out
cordova.plugins.SingularCordovaSdk.clearGlobalProperties();
createReferrerShortLink
Singular.createReferrerShortLink メソッド
共有やアトリビューションに使用できるリファラー情報を持つショートリンクを作成します。このメソッドは、ユーザーと共有できる追跡可能なリンクを生成し、インストールやアクティビティを特定のリファラーソースに帰属させることができます。
署名
static createReferrerShortLink(url: string, refName: string, refId: string, passthroughParams: Object, resultHandler: Object): void
使用例
cordova.plugins.SingularCordovaSdk.createReferrerShortLink(
"https://sample.sng.link/B4tbm/v8fp?_dl=https%3A%2F%2Fabc.com",
"John Doe", // Referrer Name
"aq239897", // Referrer ID
{
"channel": "sms",
"campaign": "summer_promo"
}, // Passthrough parameters
{
onSuccess: function(shortLinkURL) {
console.log("Generated short link:", shortLinkURL);
// Share the link with users
},
onError: function(error) {
console.error("Error creating short link:", error);
}
}
);
customRevenue
Singular.customRevenueメソッド
指定したイベント名、通貨、金額でカスタム収益イベントをトラッキングします。これにより、より具体的な収益追跡のためにカスタム名で収益イベントを追跡することができます。
- 注:カスタム収益イベント名は32 ASCII文字に制限されています。ASCII文字以外の場合、UTF-8に変換すると32バイトになります。
- 通貨コードは全角で、ISO 4217の3文字の通貨コードに準拠する必要があります。
署名
static customRevenue(eventName: string, currency: string, amount: number): void
使用例
// Track a custom revenue event
cordova.plugins.SingularCordovaSdk.customRevenue("premium_subscription", "USD", 9.99);
customRevenueWithArgs
Singular.customRevenueWithArgsメソッド
指定されたイベント名、通貨、金額、追加のカスタム属性を持つカスタム収益イベントをトラッキングします。これにより、カスタムパラメータでより詳細な収益追跡が可能になります。
- 注:カスタム収益イベント名は32 ASCII文字に制限されています。非ASCII文字の場合、UTF-8に変換されると32バイトに制限されます。
- イベント属性名と属性値は500ASCII文字に制限されています。
- 通貨コードはすべて大文字で、3文字のISO 4217通貨コードに準拠する必要があります。
署名
static customRevenueWithArgs(eventName: string, currency: string, amount: number, args: Object): void
使用例
// Track a custom revenue event with additional parameters
cordova.plugins.SingularCordovaSdk.customRevenueWithArgs(
"in_app_purchase",
"USD",
5.99,
{
"product_id": "com.app.gems_pack_small",
"quantity": 1,
"transaction_id": "T12345678",
"receipt_id": "R98765432"
}
);
イベント
Singular.event メソッド
指定した名前の単純なイベントを追跡します。このメソッドを使用して、アプリケーション内のユーザーのアクションとエンゲージメントを追跡します。
シグネチャ
static event(eventName: string): void
使用例
// Track a simple event
cordova.plugins.SingularCordovaSdk.event("level_completed");
eventWithArgs
Singular.eventWithArgs メソッド
指定された名前と追加のカスタム属性を持つイベントを追跡します。これにより、カスタムパラメータを使用したより詳細なイベント追跡が可能になります。
シグネチャ
static eventWithArgs(eventName: string, args: Object): void
使用例
// Track an event with additional parameters
cordova.plugins.SingularCordovaSdk.eventWithArgs(
"level_completed",
{
"level_id": 5,
"score": 12500,
"time_spent": 120,
"difficulty": "medium"
}
);
getGlobalProperties
Singular.getGlobalPropertiesメソッド
現在設定されているすべてのグローバルプロパティを取得します。このメソッドは、SDKに設定されているすべてのグローバルプロパティを含むオブジェクトを返します。
シグネチャ
static getGlobalProperties(success: Function): void
使用例
// Get all global properties
cordova.plugins.SingularCordovaSdk.getGlobalProperties(function(properties) {
console.log("Current global properties:", properties);
});
getLimitDataSharing
Singular.getLimitDataSharingメソッド
現在のデータ共有制限ステータスを取得します。このメソッドは、データ共有が現在制限されているかどうかを示すブール値を返します。
シグネチャ
static getLimitDataSharing(success: Function): void
使用例
// Check if data sharing is limited
cordova.plugins.SingularCordovaSdk.getLimitDataSharing(function(isLimited) {
console.log("Data sharing is limited:", isLimited);
});
handlePushNotification
Singular.handlePushNotification メソッド
帰属のためにプッシュ通知のペイロードを処理します。このメソッドはアプリがプッシュ通知を受信したときに呼び出され、Singularが正しくアトリビュートできるようにします。
シグネチャ
static handlePushNotification(pushNotificationPayload: Object): void
使用例
// Handle a received push notification
document.addEventListener('push-notification', function(event) {
var notification = event.notification;
cordova.plugins.SingularCordovaSdk.handlePushNotification(notification);
}, false);
init
Singular.init メソッド
提供された設定でSingular SDKを初期化します。これはSingular SDKを使い始めるために最初に呼び出すメソッドです。
シグネチャ
static init(singularConfig: SingularConfig): void
使用例
document.addEventListener('deviceready', function() {
// Create configuration object
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
"SDK KEY",
"SDK SECRET"
);
// Initialize the SDK
cordova.plugins.SingularCordovaSdk.init(singularConfig);
}, false);
isAllTrackingStopped
Singular.isAllTrackingStoppedメソッド
全てのトラッキングが現在停止しているかどうかをチェックします。このメソッドはトラッキングが現在停止しているかどうかを示すブール値を返します。
シグネチャ
static isAllTrackingStopped(success: Function): void
使用例
// Check if tracking is stopped
cordova.plugins.SingularCordovaSdk.isAllTrackingStopped(function(isStopped) {
console.log("Tracking is stopped:", isStopped);
});
リミットデータ共有
Singular.limitDataSharing メソッド
データ共有の制限ステータスを設定します。このメソッドを使用して、ユーザーの同意またはプライバシー要件に基づいてデータ共有を制限します。
シグネチャ
static limitDataSharing(value: boolean): void
使用例
// Limit data sharing based on user consent
function onUserConsentChanged(hasConsent) {
cordova.plugins.SingularCordovaSdk.limitDataSharing(!hasConsent);
}
収益
Singular.revenue メソッド
指定された通貨と金額で収益イベントを追跡します。このメソッドは、アプリケーション内で発生した収益を報告するために使用します。
- 通貨コードはすべて大文字で、3文字のISO 4217通貨コードに準拠する必要があります。
署名
static revenue(currency: string, amount: number): void
使用例
// Track a revenue event
cordova.plugins.SingularCordovaSdk.revenue("USD", 4.99);
revenueWithArgs
Singular.revenueWithArgsメソッド
指定された通貨、金額、追加のカスタム属性で収益イベントをトラッキングします。これにより、カスタムパラメータを使用したより詳細な収益追跡が可能になります。
- イベント属性名と属性値は500 ASCII文字に制限されています。
- 通貨コードはALL CAPSで、3文字のISO 4217通貨コードに準拠する必要があります。
署名
static revenueWithArgs(currency: string, amount: number, args: Object): void
使用例
// Track a revenue event with additional parameters
cordova.plugins.SingularCordovaSdk.revenueWithArgs(
"USD",
4.99,
{
"product_id": "com.app.premium_upgrade",
"transaction_id": "T12345678"
}
);
レジュームオールトラッキング
Singular.resumeAllTrackingメソッド
停止していたトラッキングをすべて再開します。一度停止したトラッキングを再度有効にするにはこのメソッドを使用してください。
シグネチャ
static resumeAllTracking(): void
使用例
// Resume tracking, for example when user opts back in
function onUserOptIn() {
cordova.plugins.SingularCordovaSdk.resumeAllTracking();
}
setCustomUserId
Singular.setCustomUserIdメソッド
現在のユーザーのカスタムユーザーIDを設定します。これにより、Singularのデータを独自のユーザー識別システムに関連付けることができます。
シグネチャ
static setCustomUserId(userId: string): void
使用例
// Set custom user ID after user logs in
function onUserLogin(userId) {
cordova.plugins.SingularCordovaSdk.setCustomUserId(userId);
}
setGlobalProperty
Singular.setGlobalPropertyメソッド
すべてのイベントで送信されるグローバルプロパティを設定します。これにより、毎回指定することなく、すべてのイベントに一貫した属性を追加することができます。
シグネチャ
static setGlobalProperty(key: string, value: string, overrideExisting: boolean, success: Function): void
使用例
// Set a global property
cordova.plugins.SingularCordovaSdk.setGlobalProperty(
"user_tier",
"premium",
true,
function(isSuccess) {
console.log("Global property set successfully:", isSuccess);
}
);
setUninstallToken
Singular.setUninstallToken メソッド
アンインストール追跡用のデバイストークンを設定します。アンインストール追跡を有効にするには、プッシュ通知トークンとともにこのメソッドを呼び出す必要があります。
シグネチャ
static setUninstallToken(token: string): void
使用例
// Set uninstall token when push token is received
document.addEventListener('push-registration', function(event) {
var token = event.registrationId;
cordova.plugins.SingularCordovaSdk.setUninstallToken(token);
}, false);
skanGetConversionValue
Singular.skanGetConversionValueメソッド
現在のSKAdNetwork変換値を取得します。このメソッドはiOS専用で、SKAdNetworkアトリビューションに使用される現在の変換値を返します。
シグネチャ
static skanGetConversionValue(success: Function): void
使用例
// Get the current SKAdNetwork conversion value
cordova.plugins.SingularCordovaSdk.skanGetConversionValue(function(conversionValue) {
console.log("Current conversion value:", conversionValue);
});
skanRegisterAppForAdNetworkAttribution
Singular.skanRegisterAppForAdNetworkAttributionメソッド
SKAdNetworkアトリビューション用にアプリを登録します。このメソッドはiOS専用で、SKAdNetworkのアトリビューションを有効にするために呼び出す必要があります。
シグネチャ
static skanRegisterAppForAdNetworkAttribution(): void
使用例
// Register for SKAdNetwork attribution
if (device.platform === 'iOS') {
cordova.plugins.SingularCordovaSdk.skanRegisterAppForAdNetworkAttribution();
}
skanUpdateConversionValue
Singular.skanUpdateConversionValueメソッド
SKAdNetworkの変換値を更新する。このメソッドはiOS専用で、SKAdNetworkアトリビューションに使用される変換値を手動で更新することができます。
シグネチャ
static skanUpdateConversionValue(value: number, success: Function): void
使用例
// Update the SKAdNetwork conversion value
if (device.platform === 'iOS') {
cordova.plugins.SingularCordovaSdk.skanUpdateConversionValue(5, function(isSuccess) {
console.log("Conversion value updated successfully:", isSuccess);
});
}
skanUpdateConversionValues
Singular.skanUpdateConversionValuesメソッド
追加パラメータでSKAdNetworkの変換値を更新します。このメソッドはiOS 16.1+に固有で、SKAdNetwork 4.0アトリビューションのfine、coarse、lock値を更新できます。
シグネチャ
static skanUpdateConversionValues(value: number, coarse: string, lock: boolean, success: Function): void
使用例
// Update the SKAdNetwork 4.0 conversion values
if (device.platform === 'iOS') {
cordova.plugins.SingularCordovaSdk.skanUpdateConversionValues(
5, // fine value (0-63)
"medium", // coarse value (low/medium/high)
false, // lock
function(isSuccess) {
console.log("Conversion values updated successfully:", isSuccess);
}
);
}
stopAllTracking
Singular.stopAllTrackingメソッド
全てのトラッキングアクティビティを停止します。このメソッドは、ユーザーがオプトアウトしたときや、プライバシーコンプライアンスのためにトラッキングを無効にするために使用します。
シグネチャ
static stopAllTracking(): void
使用例
// Stop tracking, for example when user opts out
function onUserOptOut() {
cordova.plugins.SingularCordovaSdk.stopAllTracking();
}
トラッキングオプトイン
Singular.trackingOptIn メソッド
ユーザーがトラッキングをオプトインしたことを示します。ユーザーがトラッキングとデータ収集に明示的に同意した場合にこのメソッドを呼び出します。
シグネチャ
static trackingOptIn(): void
使用例
// User has opted in to tracking
function onUserConsentGiven() {
cordova.plugins.SingularCordovaSdk.trackingOptIn();
}
トラッキングアンダー13
Singular.trackingUnder13 メソッド
ユーザーが13歳未満であることを示します。このメソッドを呼び出すことで、13歳未満のユーザーに対するCOPPAやその他の規制に準拠することができます。
シグネチャ
static trackingUnder13(): void
使用例
// If user is determined to be under 13 years old
cordova.plugins.SingularCordovaSdk.trackingunder13();
console.log("User marked as under 13, GDPR_UNDER_13 flag applied");
unsetCustomUserId
Singular.unsetCustomUserId メソッド
以前に設定されたカスタムユーザーIDを削除します。ユーザがログアウトしたとき、または現在のユーザIDにイベントを関連付けたくなくなったときにこのメソッドを呼び出します。
シグネチャ
static unsetCustomUserId(): void
使用例
// Clear custom user ID when user logs out
function onUserLogout() {
cordova.plugins.SingularCordovaSdk.unsetCustomUserId();
}
unsetGlobalProperty
Singular.unsetGlobalProperty メソッド
以前に設定されたグローバル・プロパティを削除します。特定のグローバル・プロパティをイベントと共に送信する必要がなくなった場合に、このメソッドを呼び出します。
シグネチャ
static unsetGlobalProperty(key: string): void
使用例
// Remove a global property
cordova.plugins.SingularCordovaSdk.unsetGlobalProperty("user_tier");