文档

跟踪应用程序内事件

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

活动实施指南

事件命名最佳实践

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

事件名称建议：

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

您的用户体验、营销或业务团队应根据企业的营销 KPI 编制事件列表。请参考《如何跟踪应用程序内事件》指南：奇异归因客户指南》进行规划。

发送事件

简单事件跟踪

使用自定义事件名称向 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);

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

收入跟踪最佳实践

混合事件跟踪（高级）

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

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

重要归属注意事项：

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

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

混合事件跟踪选项

从内部服务器发送事件

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

要求

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

从收入提供商发送事件

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

支持的供应商：

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

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

从 Segment 发送事件

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

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

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

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

跟踪应用程序内事件

活动实施指南

事件命名最佳实践

发送事件

简单事件跟踪

带属性的事件跟踪

跟踪应用内收入

收入事件指南

收入事件限制

发送收入事件

简单的收入跟踪

使用属性跟踪收入

收入跟踪最佳实践

推荐属性

混合事件跟踪（高级）

混合事件跟踪选项

从内部服务器发送事件

从收入提供商发送事件

从 Segment 发送事件