应用内事件跟踪

跟踪应用内事件，以分析广告系列效果并衡量关键绩效指标 (KPI)，例如用户登录、注册、教程完成或进度里程碑。

事件实现指南

事件命名最佳实践

使用 SendEvent 和 SendEventWithArgs 方法向 Singular 发送事件，并使用具描述性的事件名称和可选属性来丰富数据。

事件命名建议：

语言： 请以英文传递事件名称和属性，以确保与第三方合作伙伴和分析解决方案兼容
事件名称： 限制为 32 个 ASCII 字符。非 ASCII 字符串转换为 UTF-8 后必须小于 32 字节
属性与值： 限制为 500 个 ASCII 字符

您的 UA、市场或业务团队应根据组织的营销 KPI 编制事件列表。规划时请参阅如何跟踪应用内事件：Singular 归因客户指南。

发送事件

简单事件跟踪

使用自定义事件名称向 Singular 发送基础用户事件，以跟踪登录、教程完成或升级等用户行为。

// 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 或用户行为等上下文信息。

// 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)。

收入数据通过三个渠道流动：

互动报告： 在 Singular 面板中查看收入指标
导出日志： 访问详细的 ETL 数据，进行自定义分析
实时回传： 向外部平台发送收入事件

货币转换： 不同货币的收入会自动转换为您的 Singular 账户中设置的贵组织首选货币。

收入事件指南

收入事件限制

收入事件要求 ：

事件名称： 自定义收入事件名称限制为 32 个 ASCII 字符（或转换为 UTF-8 后 32 个字节的非 ASCII 字符
属性： 事件属性名称和值限制为 500 个 ASCII 字符
货币代码： 必须使用大写字母，并遵循三个字母的 ISO 4217 标准（例如，美元、欧元、印度卢比、英镑、日元

发送收入事件

简单的收入跟踪

向 Singular 发送包含事件名称、货币代码和交易金额的收入事件，以跟踪基本购买数据。

// 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);

注意： 以三个字母的 ISO 4217 货币代码形式传递货币，如 "USD"、"EUR"、"INR"。

使用属性跟踪收入

发送带有附加自定义参数的收入事件，以捕捉交易细节，如产品 SKU、类别或促销代码。

// 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);

最佳做法： 在属性中包含尽可能多的交易详情，以便进行精细的收入分析，并根据产品性能优化营销支出。

收入跟踪最佳实践

混合事件跟踪（高级）

CDP 及第三方集成不兼容： SDID 与 CDP（Segment、mParticle）或第三方订阅提供商（RevenueCat、Adapty）不兼容。如果启用了 SDID，这些平台无法并行用于事件转发，将导致归因不完整或中断。

通过集成到应用程序中的 Singular SDK 发送所有事件和收入，以获得最佳归因。不过，必要时，Singular 也可以从其他来源收集事件。

在 Singular SDK 之外发送的事件必须符合 Singular 的服务器到服务器事件文档，并提供匹配的设备标识符，以便正确归因。

重要归因注意事项 ：

当服务器到服务器请求中的设备标识符与 Singular SDK 记录的标识符不匹配时，就会出现差异：

早期事件： 如果事件在 Singular SDK 记录设备标识符之前到达，该事件就会成为未知设备的 "首次会话"，从而导致自然量归因。
标识符不匹配： 如果 Singular SDK 记录的设备标识符与服务器到服务器请求中的设备标识符不同，则事件将被 错误归因

混合事件跟踪选项

从内部服务器发送事件

在客户端跟踪不足的情况下，从内部服务器收集收入数据，分析营销活动绩效和投资回报率。

要求

捕获设备标识符： 在应用内注册或登录事件中，捕获并传递设备标识符，然后将此数据与用户 ID 一起存储在服务器上。当用户生成新的应用程序会话时更新标识符，以确保正确的归因
平台特定标识符： 使用与平台匹配的设备标识符发送服务器端事件（例如，iOS 设备使用 IDFA 或 IDFV，Android 设备使用 GAID
实时更新： 使用Singular内部商业智能回传机制将事件实时推送到您的终端。请参阅内部商业智能回传常见问题
实施细节： 查看服务器到服务器集成指南中的 "跟踪收入 " 部分

从收入提供商发送事件

集成 RevenueCat 或 adapty 等第三方收入提供商，向 Singular 发送购买和订阅收入。

支持的供应商 ：

RevenueCat： 在 RevenueCat 文档中了解更多信息
adapty： 在 adapty 文档中了解更多信息
Superwall： 在 Superwall 文档中了解更多信息
Xsolla： 在 Xsolla 文档中了解更多信息

注意： 在使用收入提供商时，请确保它们配置为发送与 Singular SDK 捕捉到的内容相匹配的正确设备标识符，以保持归因的准确性。

从 Segment 发送事件

通过在Segment中添加 "云模式 "目标，使Segment能与Singular SDK并行发送事件到Singular。

请按照实施指南 Singular-Segment Integration 获取详细设置说明。

配置说明： Segment 集成需要设置 Cloud-Mode 目标地址，以确保事件正确路由到 Singular，并带有正确的设备标识符和属性上下文。

虚幻引擎 SDK - 跟踪应用程序内事件

应用内事件跟踪

事件实现指南

事件命名最佳实践

发送事件

简单事件跟踪

带属性的事件跟踪

跟踪应用内收入

收入事件指南

收入事件限制

发送收入事件

简单的收入跟踪

使用属性跟踪收入

收入跟踪最佳实践

推荐属性

混合事件跟踪（高级）

混合事件跟踪选项

从内部服务器发送事件

从收入提供商发送事件

从 Segment 发送事件