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

ドキュメント

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

この包括的なリファレンスでは、Singular SDK for Cordova アプリケーションで利用可能なすべてのメソッドについて説明しています。SDKは初期化、ユーザー識別、イベントトラッキング、収益レポート、アトリビューション、データプライバシーコンプライアンス、コンフィギュレーションなどの機能を提供します。各メソッドには説明、署名、実用的な使用例が記載されており、開発者がSingular SDKの機能をアプリケーションに統合するのに役立ちます。

広告収入

Singular.adRevenueメソッド

詳細な広告データ情報で広告収入イベントをトラッキングします。このメソッドを使用すると、アプリケーションに表示された広告から発生した収益を、広告パフォーマンスを分類・分析するための様々なパラメータと共に報告することができます。

シグネチャ

static adRevenue(adData: SingularAdData): void

使用例

javascript
// 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

使用例

javascript
// 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

使用例

javascript
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

使用例

javascript
// 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

使用例

javascript
// 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

使用例

javascript
// Track a simple event
cordova.plugins.SingularCordovaSdk.event("level_completed");

eventWithArgs

Singular.eventWithArgs メソッド

指定された名前と追加のカスタム属性を持つイベントを追跡します。これにより、カスタムパラメータを使用したより詳細なイベント追跡が可能になります。

シグネチャ

static eventWithArgs(eventName: string, args: Object): void

使用例

javascript
// 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

使用例

javascript
// Get all global properties
cordova.plugins.SingularCordovaSdk.getGlobalProperties(function(properties) {
    console.log("Current global properties:", properties);
});

getLimitDataSharing

Singular.getLimitDataSharingメソッド

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

シグネチャ

static getLimitDataSharing(success: Function): void

使用例

javascript
// 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

使用例

javascript
// 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

使用例

javascript
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

使用例

javascript
// Check if tracking is stopped
cordova.plugins.SingularCordovaSdk.isAllTrackingStopped(function(isStopped) {
    console.log("Tracking is stopped:", isStopped);
});

リミットデータ共有

Singular.limitDataSharing メソッド

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

シグネチャ

static limitDataSharing(value: boolean): void

使用例

javascript
// Limit data sharing based on user consent
function onUserConsentChanged(hasConsent) {
    cordova.plugins.SingularCordovaSdk.limitDataSharing(!hasConsent);
}

収益

Singular.revenue メソッド

指定された通貨と金額で収益イベントを追跡します。このメソッドは、アプリケーション内で発生した収益を報告するために使用します。

署名

static revenue(currency: string, amount: number): void

使用例

javascript
// 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

使用例

javascript
// 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

使用例

javascript
// 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

使用例

javascript
// 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

使用例

javascript
// 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

使用例

javascript
// 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

使用例

javascript
// 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

使用例

javascript
// 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

使用例

javascript
// 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

使用例

javascript
// 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

使用例

javascript
// Stop tracking, for example when user opts out
function onUserOptOut() {
    cordova.plugins.SingularCordovaSdk.stopAllTracking();
}

トラッキングオプトイン

Singular.trackingOptIn メソッド

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

シグネチャ

static trackingOptIn(): void

使用例

javascript
// User has opted in to tracking
function onUserConsentGiven() {
    cordova.plugins.SingularCordovaSdk.trackingOptIn();
}

トラッキングアンダー13

Singular.trackingUnder13 メソッド

ユーザーが13歳未満であることを示します。このメソッドを呼び出すことで、13歳未満のユーザーに対するCOPPAやその他の規制に準拠することができます。

シグネチャ

static trackingUnder13(): void

使用例

javascript
// 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

使用例

javascript
// Clear custom user ID when user logs out
function onUserLogout() {
    cordova.plugins.SingularCordovaSdk.unsetCustomUserId();
}

unsetGlobalProperty

Singular.unsetGlobalProperty メソッド

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

シグネチャ

static unsetGlobalProperty(key: string): void

使用例

javascript
// Remove a global property
cordova.plugins.SingularCordovaSdk.unsetGlobalProperty("user_tier");