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

フォローする
Avatar
Eyal Rabinovich
Updated
ドキュメント

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

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

イベント実施ガイドライン

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

SendEvent 、SendEventWithArgs メソッドを使用して、説明的なイベント名とエンリッチデータ用のオプション属性を付けてSingularにイベントを送信します。

イベント名の推奨事項

  • 言語：サードパーティのパートナーや分析ソリューションとの互換性を確保するため、イベント名と属性は英語で入力してください。
  • イベント名：非 ASCII 文字列は、UTF-8 に変換されたときに 32 バイト未満でなければならない。
  • 属性と値：500ASCII文字に制限

UA、マーケティング、またはビジネスチームは、組織のマーケティングKPIに基づいてイベントのリストをコンパイルする必要があります。アプリ内イベントをトラッキングする方法」を参照してください：ガイド（How to Track In-App Events:Guide For Singular Attribution Customers）を参照してください。

イベントの送信

簡単なイベントトラッキング

ログイン、チュートリアル完了、レベルアップなどのユーザーアクションを追跡するために、カスタムイベント名を付けて基本的なユーザーイベントを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ドルなど）を使用する

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

最適なアトリビューションのために、アプリに統合された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デスティネーションの設定が必要です。