アプリ内イベントのトラッキング

アプリ内イベントをトラッキングしてキャンペーンパフォーマンスを分析し、ユーザーのログイン、登録、チュートリアルの完了、進行のマイルストーンなどの主要業績評価指標（KPI）を測定します。

標準イベントと属性

イベントタイプを理解する

Singularは2種類のイベントをサポートし、ユニバーサルおよびアプリ固有のトラッキングニーズに対応します。

• 標準イベント：あらかじめ定義されたイベント（例：sngLogin 、sngContentView ）で、Singularによって認識され、レポートや最適化のために広告ネットワークによってサポートされます。 標準イベントを使用すると、手動で定義しなくてもSingularが自動的にイベントリストに追加するため、設定が簡単になります。完全なイベント名と推奨属性については、標準イベントと属性のリストをご覧ください。
• カスタムイベント：Singularの標準イベントと一致しない、アプリ独自のイベント（例：Signup 、AchievementUnlocked ）。

UA、マーケティング、またはビジネスチームは、組織のマーケティングKPIに基づいてイベントのリストを編集してください。アプリ内イベントをトラッキングする方法を参照してください：ガイドを参照してください。

カスタムイベントの制限

カスタムイベントには、サードパーティのパートナーや分析ソリューションとの互換性を確保するために、特定の文字とエンコーディングの制約があります。

イベントの送信

イベント・メソッド

event() メソッドを使用して、追加属性のない単純なイベントを追跡する。

// Track a simple custom event
cordova.plugins.SingularCordovaSdk.event('SignUp');

// Track a standard event
cordova.plugins.SingularCordovaSdk.event('sngLogin');

メソッドのシグネチャ：

event(eventName: string): void

メソッドの完全なリストについては、イベント・メソッド・リファレンスを参照してください。

EventWithArgs メソッド

より豊かなコンテキストを提供し、レポートの詳細なセグメンテーションを可能にするために、追加のカスタム属性を持つイベントを追跡します。

// Track custom event with attributes
cordova.plugins.SingularCordovaSdk.eventWithArgs('LevelComplete', {
  level: 5,
  score: 1250,
  time_spent: 45.3
});

// Track standard event with recommended attributes
cordova.plugins.SingularCordovaSdk.eventWithArgs('sngTutorialComplete', {
  sngAttrContent: 'Cordova Basics',
  sngAttrContentId: '32',
  sngAttrContentType: 'video',
  sngAttrSuccess: 'yes'
});

メソッドのシグネチャ：

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

メソッドの完全なリストについては、eventWithArgs メソッド・リファレンスを参照してください。

ベスト・プラクティス

アプリ内収益のトラッキング

アプリ内課金（IAP）、サブスクリプション、カスタム収益ソースからの収益を追跡して、キャンペーンのパフォーマンスと広告費用対効果（ROAS）を測定します。

収益データは3つのチャネルを通じて流れます：

• インタラクティブレポート：Singularダッシュボードで収益指標を表示
• ログのエクスポート：カスタム分析のための詳細なETLデータへのアクセス
• リアルタイムポストバック：収益イベントを外部プラットフォームへ送信

収益イベントを追跡する理由

• 豊富な分析：詳細なトランザクションデータを取得し、Singularレポートを強化
• 不正防止：トランザクションの領収書（Google PlayやApple App Storeなど）を含めることで、購入を検証し、アプリ内詐欺に対処します。
• キャンペーンの最適化：収益とマーケティング活動を結びつけてROIを測定します。

アプリ内課金の統合

IAP購入オブジェクトの取得

Cordova IAP プラグインを使用して、プラットフォームストアから完全なトランザクションの詳細を含む購入オブジェクトを取得します。

• iOS： cordova-plugin-purchaseなどを使用してStoreKitの購入詳細にアクセスします。
• AndroidGoogle Play Billing の購入詳細を取得するにはcordova-plugin-purchaseなどを使用します。

SingularIAP コンストラクタ

プラットフォーム固有のレシート検証や不正防止を行い、収益を追跡するためのアプリ内課金オブジェクトを作成します。

コンストラクタのシグネチャ：

function SingularIAP(product: Object): SingularIAP

コンストラクタの完全なリファレンスは、SingularIAPコンストラクタのリファレンスを参照してください。

完全な IAP 実装例

IAP イベントをキャプチャし、プラットフォーム固有の購入オブジェクトとともに Singular に送信する、完全な購入リスナーを実装します。

// Import Singular SDK and SingularIAP constructor
var Singular = cordova.plugins.SingularCordovaSdk;
var SingularIAP = cordova.require('singular-cordova-sdk.SingularIAP');

// iOS App Store purchase example
function handleiOSPurchase(purchase) {
  // Create iOS product object
  var iosProduct = {
    currency: 'USD',
    price: 4.99,
    id: 'com.app.premiumgems',
    transaction: {
      type: 'ios-appstore',
      appStoreReceipt: purchase.receipt, // Base64 receipt from StoreKit
      id: purchase.transactionId // Transaction identifier
    }
  };

  // Create SingularIAP object
  var iosIAP = new SingularIAP(iosProduct);

  // Track the purchase with Singular
  // The SingularIAP object is passed as additional args
  cordova.plugins.SingularCordovaSdk.eventWithArgs('iap_purchase', iosIAP);
}

// Android Play Store purchase example
function handleAndroidPurchase(purchase) {
  // Create Android product object
  var androidProduct = {
    currency: 'USD',
    price: 4.99,
    id: 'com.app.premiumgems',
    transaction: {
      type: 'android-playstore',
      receipt: purchase.receipt, // JSON receipt from Google Play
      signature: purchase.signature // Signature from Google Play
    }
  };

  // Create SingularIAP object
  var androidIAP = new SingularIAP(androidProduct);

  // Track the purchase with Singular
  cordova.plugins.SingularCordovaSdk.eventWithArgs('iap_purchase', androidIAP);
}

// Example integration with cordova-plugin-purchase
document.addEventListener('deviceready', function() {
  // Initialize the store
  store.register({
    id: 'com.app.premiumgems',
    type: store.CONSUMABLE
  });

  // Handle purchase approved
  store.when('com.app.premiumgems').approved(function(product) {
    // Determine platform and handle accordingly
    if (device.platform === 'iOS') {
      handleiOSPurchase(product.transaction);
    } else if (device.platform === 'Android') {
      handleAndroidPurchase(product.transaction);
    }

    // Finish the transaction
    product.finish();
  });

  // Refresh the store
  store.refresh();
});

手動による収益追跡

購入検証なしの収益

通貨、金額、オプションの商品詳細を購入オブジェクトなしで渡すことで、収益をトラッキングします。このメソッドは検証用のトランザクションレシートを提供しないことに注意してください。

収益メソッド

指定した通貨と金額の単純な収益イベントを追跡します。

// Track revenue without product details
cordova.plugins.SingularCordovaSdk.revenue('USD', 4.99);

メソッドの署名：

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

メソッドの完全なリストについては、Revenue メソッド・リファレンスを参照してください。

RevenueWithArgs メソッド

指定した通貨、金額、および追加のカスタム属性を持つ収益イベントを追跡します。

// Track revenue with attributes
cordova.plugins.SingularCordovaSdk.revenueWithArgs('USD', 9.98, {
  productSKU: 'coin_package_abc123',
  productName: 'Coin Pack 10',
  productCategory: 'Bundles',
  productQuantity: 2,
  productPrice: 4.99,
  transaction_id: 'T12345'
});

メソッドのシグネチャ：

revenueWithArgs(currency: string, amount: number, args: Object): void

メソッドの完全なリストについては、revenueWithArgs メソッド・リファレンスを参照してください。

CustomRevenue メソッド

指定したイベント名、通貨、および金額を持つカスタム収益イベントを追跡します。

// Track custom revenue event
cordova.plugins.SingularCordovaSdk.customRevenue('PremiumUpgrade', 'USD', 9.99);

メソッド・シグネチャ：

customRevenue(eventName: string, currency: string, amount: number): void

メソッドの完全なリストについては、customRevenue メソッドのリファレンスを参照してください。

CustomRevenueWithArgs メソッド

指定したイベント名、通貨、金額、および追加のカスタム属性を持つカスタム収益イベントを追跡します。

// Track custom revenue event with attributes
cordova.plugins.SingularCordovaSdk.customRevenueWithArgs('PremiumBundlePurchase', 'USD', 99.99, {
  productSKU: 'premium_bundle_xyz',
  productName: 'Premium Bundle',
  productCategory: 'Bundles',
  productQuantity: 1,
  productPrice: 99.99,
  discount_applied: true
});

メソッドのシグネチャ：

customRevenueWithArgs(eventName: string, currency: string, amount: number, args: Object): void

メソッドの完全なリストについては、customRevenueWithArgs メソッド・リファレンスを参照してください。

サブスクリプション収益

サブスクリプションのトラッキング

Singularは、Singular SDKを使ったサブスクリプションイベントの実装に関する包括的なガイドを提供しています。このガイドでは、様々なプラットフォームにおけるアプリ内サブスクリプションイベントのトラッキングをカバーしています。

• サブスクリプション収益をトラッキングしたい場合は、サブスクリプションイベント技術実装ガイドをお読みください。

ハイブリッドイベント追跡（上級者向け）

Singularでは、最適なアトリビューションのために、アプリに統合されたSingular SDKを通してすべてのイベントと収益を送信することを推奨しています。ただし、Singularは必要に応じて他のソースからイベントを収集することができます。

Singular SDK以外で送信されたイベントは、Singularのサーバー間イベントドキュメンテーション要件に準拠し、正しいアトリビューションのために一致するデバイス識別子を提供する必要があります。

ハイブリッドイベント追跡ガイド

内部サーバーからのイベントの送信

内部サーバーから収益データを収集し、キャンペーンのパフォーマンスとROIを分析します。

要件

• デバイス識別子を取得する：アプリ内登録またはログインイベントから、デバイス識別子をキャプチャして渡し、このデータをユーザーIDと共にサーバーに保存します。デバイス識別子はユーザーによって変更される可能性があるため、ユーザーがアプリセッションを生成したときに識別子を更新します。これにより、サーバー側のイベントが正しいデバイスに帰属することが保証されます。
• プラットフォーム固有の識別子：サーバー側イベントはプラットフォーム固有であり、デバイス・プラットフォームに一致するデバイス識別子（例えば、iOSデバイスの場合はIDFAまたはIDFV、Androidデバイスの場合はGAID）を使用して送信する必要があります。
• リアルタイム更新：Singular Internal BIのポストバックメカニズムを使用して、内部エンドポイントにリアルタイムでイベントをプッシュし、サーバー側でデータセットを更新できるようにします。内部BIポストバックのFAQを参照してください。
• 実装の詳細：詳細については、『サーバー間統合』ガイドの「収益の追跡」セクションを参照してください。

収益プロバイダからのイベントの送信

RevenueCatやadaptyのようなサードパーティの収益プロバイダーを統合して、購入や購読の収益をSingularに送信します。

サポートしているプロバイダー

• RevenueCat：詳細はRevenueCatのドキュメントをご覧ください。
• adapty詳細はadaptyのドキュメントをご覧ください。

セグメントからのイベント送信

Segmentに "Cloud-Mode "送信先を追加することで、Singular SDKと並行してSegmentからSingularへイベントを送信できるようになります。

詳細な設定方法については、実装ガイドSingular-Segment Integrationに従ってください。