Unreal Engine SDK - アプリ内イベントのトラッキング

フォローする
Avatar
Eyal Rabinovich
Updated

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

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

イベント実装のガイドライン

イベント命名のベストプラクティス

Singular にイベントを送信するには、 SendEvent および SendEventWithArgs メソッドを使用し、わかりやすいイベント名と、データを充実させるための任意の属性を指定します。

イベント名の推奨事項:

  • 言語: サードパーティパートナーおよび分析ソリューションとの互換性を確保するため、イベント名と属性は英語で渡してください
  • イベント名: ASCII 32 文字までです。ASCII 以外の文字列は、UTF-8 に変換したときに 32 バイト未満である必要があります
  • 属性と値: ASCII 500 文字までです

UA、マーケティング、またはビジネスチームが、組織のマーケティング KPI に基づいてイベントのリストを作成してください。計画にあたっては、 アプリ内イベントのトラッキング方法：Singular アトリビューションご利用のお客様向けガイド を参照してください。

イベントの送信

シンプルなイベントのトラッキング

ログイン、チュートリアル完了、レベルアップなどのユーザー行動をトラッキングするため、カスタムイベント名を指定して基本的なユーザーイベントを Singular に送信します。

C++ 
// Send an event without any parameters, just a name
USingularSDKBPLibrary::SendEvent(TEXT("Login"));

// Example: Track tutorial completion
USingularSDKBPLibrary::SendEvent(TEXT("TutorialComplete"));

// Example: Track level progression
USingularSDKBPLibrary::SendEvent(TEXT("LevelUp"));

メソッドシグネチャ: 

static void SendEvent(FString eventName);

属性付きイベントのトラッキング

レベル番号、アイテム ID、ユーザー行動などのコンテキスト情報を取得するため、追加のカスタムパラメータとともにユーザーイベントを送信します。

C++ 
// Example 1: Login with user tier
TMap<FString, FString> LoginArgs;
LoginArgs.Add(TEXT("user_tier"), TEXT("premium"));
LoginArgs.Add(TEXT("login_method"), TEXT("email"));
USingularSDKBPLibrary::SendEventWithArgs(TEXT("Login"), LoginArgs);

// Example 2: Tutorial completion with metadata
TMap<FString, FString> TutorialArgs;
TutorialArgs.Add(TEXT("tutorial_name"), TEXT("BasicControls"));
TutorialArgs.Add(TEXT("completion_time"), TEXT("120"));
TutorialArgs.Add(TEXT("difficulty"), TEXT("easy"));
USingularSDKBPLibrary::SendEventWithArgs(TEXT("TutorialComplete"), TutorialArgs);

// Example 3: Level progression with game state
TMap<FString, FString> LevelArgs;
LevelArgs.Add(TEXT("level_number"), TEXT("5"));
LevelArgs.Add(TEXT("character_class"), TEXT("warrior"));
LevelArgs.Add(TEXT("total_playtime"), TEXT("3600"));
USingularSDKBPLibrary::SendEventWithArgs(TEXT("LevelUp"), LevelArgs);

// Example 4: Item purchase with details
TMap<FString, FString> PurchaseArgs;
PurchaseArgs.Add(TEXT("item_id"), TEXT("sword_legendary_001"));
PurchaseArgs.Add(TEXT("item_category"), TEXT("weapons"));
PurchaseArgs.Add(TEXT("item_rarity"), TEXT("legendary"));
USingularSDKBPLibrary::SendEventWithArgs(TEXT("ItemPurchased"), PurchaseArgs);

メソッドシグネチャ: 

static void SendEventWithArgs(FString eventName, TMap<FString, FString> args);

ベストプラクティス: トラッキング対象のデータが明確に分かる、説明的な属性名を使用してください。データ分析が容易になり、マーケティングチームにとってレポートが理解しやすくなります。

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

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

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

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

通貨変換： 異なる通貨での収益は、Singularアカウントで設定されたご希望の通貨に自動的に変換されます。

収益イベントのガイドライン

収益イベントの制限

収益イベントの要件

  • イベント名： カスタム収益イベント名は32ASCII文字（UTF-8に変換した場合、非ASCIIの場合は32バイト）に制限されます。
  • 属性： イベント属性名と値は500 ASCII文字に制限されます。
  • 通貨コード： すべて大文字で、3文字の ISO 4217標準に 従わなければなりません（例：USD、EUR、INR、GBP、JPY）。

収益イベントの送信

シンプルな収益トラッキング

イベント名、通貨コード、トランザクション金額を入力して収益イベントをSingularに送信し、基本的な購入データをトラッキングします。

C++ 
// Example 1: Basic purchase tracking
USingularSDKBPLibrary::SendRevenue(TEXT("Purchase Completed"), TEXT("USD"), 9.99f);

// Example 2: Subscription purchase
USingularSDKBPLibrary::SendRevenue(TEXT("SubscriptionPurchase"), TEXT("USD"), 29.99f);

// Example 3: In-game currency purchase
USingularSDKBPLibrary::SendRevenue(TEXT("CoinPackagePurchase"), TEXT("EUR"), 4.99f);

// Example 4: Premium item purchase
USingularSDKBPLibrary::SendRevenue(TEXT("PremiumItemPurchase"), TEXT("GBP"), 19.99f);

メソッドの署名 ： 

static void SendRevenue(FString eventName, FString currency, float amount);

注： 通貨は "USD"、"EUR"、"INR "のような3文字のISO 4217通貨コードで渡します。

属性による収益追跡

商品SKU、カテゴリー、プロモコードなどのトランザクションの詳細を取得するために、カスタムパラメータを追加して収益イベントを送信します。

C++ 
// Example 1: Revenue with product details
TMap<FString, FString> PurchaseArgs;
PurchaseArgs.Add(TEXT("product_id"), TEXT("coin_pack_100"));
PurchaseArgs.Add(TEXT("product_name"), TEXT("100 Coin Pack"));
PurchaseArgs.Add(TEXT("product_category"), TEXT("currency"));
USingularSDKBPLibrary::SendRevenueWithArgs(
    TEXT("Purchase Completed"), 
    TEXT("USD"), 
    4.99f, 
    PurchaseArgs
);

// Example 2: Subscription with billing details
TMap<FString, FString> SubArgs;
SubArgs.Add(TEXT("subscription_tier"), TEXT("premium"));
SubArgs.Add(TEXT("billing_period"), TEXT("monthly"));
SubArgs.Add(TEXT("trial_period"), TEXT("false"));
SubArgs.Add(TEXT("renewal_count"), TEXT("3"));
USingularSDKBPLibrary::SendRevenueWithArgs(
    TEXT("SubscriptionRenewal"), 
    TEXT("USD"), 
    9.99f, 
    SubArgs
);

// Example 3: Purchase with promotional discount
TMap<FString, FString> PromoArgs;
PromoArgs.Add(TEXT("product_id"), TEXT("bundle_mega_001"));
PromoArgs.Add(TEXT("promo_code"), TEXT("SUMMER2025"));
PromoArgs.Add(TEXT("discount_amount"), TEXT("5.00"));
PromoArgs.Add(TEXT("original_price"), TEXT("19.99"));
USingularSDKBPLibrary::SendRevenueWithArgs(
    TEXT("BundlePurchase"), 
    TEXT("USD"), 
    14.99f, 
    PromoArgs
);

// Example 4: IAP with transaction metadata
TMap<FString, FString> IAPArgs;
IAPArgs.Add(TEXT("platform"), TEXT("google_play"));
IAPArgs.Add(TEXT("transaction_id"), TEXT("GPA.1234-5678-90AB"));
IAPArgs.Add(TEXT("item_type"), TEXT("consumable"));
IAPArgs.Add(TEXT("user_level"), TEXT("42"));
USingularSDKBPLibrary::SendRevenueWithArgs(
    TEXT("IAP_Consumable"), 
    TEXT("USD"), 
    2.99f, 
    IAPArgs
);

メソッドの署名 

static void SendRevenueWithArgs(FString eventName, FString currency, float amount, TMap<FString, FString> args);

ベストプラクティス： きめ細かい収益分析を可能にし、製品パフォーマンスに基づいてマーケティング費用を最適化するために、属性にできるだけ多くのトランザクションの詳細を含めます。

収益追跡のベストプラクティス

推奨属性

包括的なトランザクション追跡のために、収益イベントにこれらの一般的な属性を含めます：

  • product_id： 購入商品またはSKUの一意識別子
  • product_name: 人間が読める商品名
  • product_category（商品カテゴリー product_category：商品のカテゴリーまたはタイプ（例："currency"、"weapons"、"subscription")
  • transaction_id： 決済プラットフォームからの一意のトランザクション識別子
  • プラットフォーム： 購入プラットフォーム (例: "app_store", "google_play", "steam")
  • promo_code： 割引に使用されるプロモーションコード
  • user_tier： ユーザーのサブスクリプションまたはメンバーシップの階層
  • 数量 購入したアイテムの数

実装のヒント

  • 0以外の金額： 金額が0より大きいか小さいときのみ収益イベントを送信する
  • 一貫したネーミング： 分析を容易にするため、すべての収益イベントで一貫した属性名を使用する。
  • テスト購入： 本番の収益データに影響を与えないよう、テストには少額（0.01ドルなど）を使用する

ハイブリッド・イベント・トラッキング（上級者向け）

CDP およびサードパーティ連携の非互換性: SDID は CDP（Segment、mParticle）やサードパーティのサブスクリプションプロバイダー（RevenueCat、Adapty）と互換性がありません。SDID が有効になっている場合、これらのプラットフォームをイベント転送に並行して使用することはできず、不完全または破損したアトリビューションにつながります。

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

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

アトリビューションに関する重要な考慮事項

サーバー間リクエストのデバイス識別子がSingular SDKによって記録された識別子と一致しない場合、不一致が発生します：

  • 初期イベント： Singular SDK がデバイス識別子を記録する 前に イベントが到着した場合、そのイベントは未知のデバイスの「最初のセッション」となり、その結果アトリビューションが不正になります。
  • 識別子の不一致： Singular SDKがサーバー間リクエストのデバイス識別子と異なるデバイス識別子を記録した場合、イベントは 正しくアトリビューションされません 。

ハイブリッドイベントトラッキングオプション

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

クライアントサイドのトラッキングが不十分な場合、内部サーバーから収益データを収集し、キャンペーンのパフォーマンスとROIを分析します。

要件

  • デバイス識別子の取得 アプリ内登録またはログインイベント中に、デバイス識別子を取得して渡し、このデータをユーザーIDとともにサーバーに保存します。ユーザーが新しいアプリセッションを生成したときに識別子を更新し、正しいアトリビューションを確保します。
  • プラットフォーム固有の識別子： プラットフォーム（iOSデバイスのIDFAまたはIDFV、AndroidデバイスのGAIDなど）に一致するデバイス識別子でサーバーサイドのイベントを送信します。
  • リアルタイム更新： Singularの内部BIポストバックメカニズムを使用して、エンドポイントにリアルタイムでイベントをプッシュします。 内部BIポストバックのFAQを 参照してください。
  • 実装の詳細： サーバー間統合ガイドの 「収益の追跡」 セクションを参照してください。

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

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

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

注意： 収益プロバイダーを使用する場合は、アトリビューションの精度を維持するために、Singular SDKが取得したものと一致する正しいデバイス識別子を送信するように設定してください。

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

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

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

設定上の注意： Segmentの統合では、イベントが正しいデバイス識別子とアトリビューションコンテキストでSingularに正しくルーティングされるように、Cloud-Modeデスティネーションの設定が必要です。