追踪应用内事件

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

标准事件和属性

使用标准事件

Singular 支持标准事件，这些事件能够被广告网络识别，用于报告和优化。请尽可能使用标准事件名称，以实现自动识别并简化设置。

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

每个事件都支持各种属性。有关实现细节，请参阅每个事件的推荐标准属性。

发送事件

事件实现指南

使用 Event() 方法向 Singular 发送事件，并可选择附带属性以丰富数据。

标准事件： 使用标准事件列表中事件的 Unity 名称，例如 Events.sngLogin
自定义事件： 对于应用特有且与标准事件不匹配的事件，可使用任何符合字符限制的描述性字符串

自定义事件限制：

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

Event 方法

使用可变参数或 Dictionary 格式，报告带或不带附加信息的用户事件。

方法签名：

public static void Event(string name)
public static void Event(string name, params object[] args)
public static void Event(Dictionary<string, object> args, string name)

注意： 使用 params object[] args 签名时，args 列表必须包含偶数个元素（键值对），否则事件将被拒绝。传递字典时，值必须是以下类型之一：string、int、long、float、double、null、ArrayList、Dictionary<string, object>

用法示例

// Example 1: Standard event without attributes
SingularSDK.Event(Events.sngLogin);

// Example 2: Standard event with recommended attributes (key-value pairs)
SingularSDK.Event(Events.sngTutorialComplete,
    Attributes.sngAttrContent, "Unity Basics",
    Attributes.sngAttrContentId, 32,
    Attributes.sngAttrContentType, "video",
    Attributes.sngAttrSuccess, "yes"
);

// Example 3: Standard event with attributes using Dictionary
Dictionary<string, object> attributes = new Dictionary<string, object>()
{
    [Attributes.sngAttrContent] = "Unity Basics",
    [Attributes.sngAttrContentId] = 32,
    [Attributes.sngAttrContentType] = "video",
    [Attributes.sngAttrSuccess] = "yes"
};
SingularSDK.Event(attributes, Events.sngTutorialComplete);

// Example 4: Custom event without attributes
SingularSDK.Event("SignUp");

// Example 5: Custom event with custom attributes
SingularSDK.Event("Bonus Points Earned", "Points", 500, "Level", 5);

追踪应用内收入

追踪来自应用内购买（IAP）、订阅和自定义收入来源的收入，以衡量广告活动效果和广告支出回报率（ROAS）。

收入数据通过三种渠道流转：

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

收入事件限制：

事件名称： 自定义收入事件名称限制为 32 个 ASCII 字符（对于非 ASCII 字符，转换为 UTF-8 后为 32 字节）
属性： 事件属性名称和值限制为 500 个 ASCII 字符
货币代码： 必须全部大写，并遵循三个字母的 ISO 4217 标准（例如 USD、EUR、INR）

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

最佳实践

标准命名： 使用 Singular 的标准事件和属性命名约定
语言： 使用英文发送自定义收入事件名称，以提高广告网络回传兼容性
非零金额： 仅在金额大于或小于 0 时发送收入事件

Unity IAP 集成

使用 Unity IAP 进行应用内购买

将 Unity 的 IAP Purchase 或 Order 对象传递给 InAppPurchase() 方法，以获得更丰富的报告和交易验证。

优势：

丰富的数据： Singular 会接收完整的交易详情，以生成全面的报告
欺诈防范： 交易收据可用于验证，以打击应用内欺诈

Unity IAP 版本兼容性：

Unity IAP v5： 使用新的 Unity Purchasing API ，搭配 Google Play Billing Library 7+。兼容 Unity 2021.3 LTS 及更高版本。请使用 InAppPurchase(Order) 方法
Unity IAP v4： 使用较旧的 Unity IAP API ，搭配 Google Play Billing Library 6。兼容 Unity 2018.4 LTS 至 2020.3 LTS。请使用 InAppPurchase(Product) 方法

InAppPurchase 方法（Unity IAP v5）

使用 Unity IAP v5 的 Order 对象发送 IAP 事件，以实现自动验证和更丰富的数据。

方法签名：

public static void InAppPurchase(Order order)
public static void InAppPurchase(Order order, Dictionary<string, object> attributes)
public static void InAppPurchase(Order order, bool isRestored)
public static void InAppPurchase(Order order, string eventName, Dictionary<string, object> attributes)

用法示例

// Example 1: IAP with order object only
SingularSDK.InAppPurchase(order);

// Example 2: IAP with order and additional attributes
Dictionary<string, object> attr = new Dictionary<string, object>()
{
    ["promo_code"] = "SUMMER2025",
    ["user_tier"] = "premium"
};
SingularSDK.InAppPurchase(order, attr);

// Example 3: IAP with restored transaction flag
SingularSDK.InAppPurchase(order, true);

// Example 4: IAP with custom event name and attributes
Dictionary<string, object> attr = new Dictionary<string, object>()
{
    ["subscription_tier"] = "gold",
    ["billing_period"] = "monthly"
};
SingularSDK.InAppPurchase(order, "PremiumSubscription", attr);

InAppPurchase 方法（Unity IAP v4）

使用 Unity IAP v4 的 Product 对象发送 IAP 事件，以实现自动验证和更丰富的数据。

方法签名：

public static void InAppPurchase(Product product, Dictionary<string, object> attributes, bool isRestored = false)
public static void InAppPurchase(string eventName, Product product, Dictionary<string, object> attributes, bool isRestored = false)
public static void InAppPurchase(IEnumerable<Product> products, Dictionary<string, object> attributes, bool isRestored = false)
public static void InAppPurchase(string eventName, IEnumerable<Product> products, Dictionary<string, object> attributes, bool isRestored = false)

用法示例

// Example 1: IAP with single product, no extra attributes
SingularSDK.InAppPurchase(myProduct, null);

// Example 2: IAP with single product and attributes
Dictionary<string, object> attr = new Dictionary<string, object>()
{
    ["promo_code"] = "SUMMER2025",
    ["user_tier"] = "premium"
};
SingularSDK.InAppPurchase(myProduct, attr);

// Example 3: IAP with custom event name
SingularSDK.InAppPurchase("PremiumUpgrade", myProduct, null);

// Example 4: IAP with list of products
SingularSDK.InAppPurchase(myProductList, null);

// Example 5: IAP with list of products and custom event name
SingularSDK.InAppPurchase("BundlePurchase", myProductList, null);

无购买验证的自定义收入

手动收入追踪

通过传递货币、金额和可选的产品详情来追踪收入，而无需 Purchase 或 Order 对象。请注意，此方法不提供用于验证的交易收据。

重要： 使用这些方法时，Singular 无法验证交易。我们强烈建议尽可能使用上文所述的 Unity IAP 方法。

Revenue 方法

发送带有货币、金额和可选产品详情的收入事件。

方法签名：

public static void Revenue(string currency, double amount)
public static void Revenue(string currency, double amount, string productSKU, string productName, string productCategory, int productQuantity, double productPrice)
public static void Revenue(string currency, double amount, Dictionary<string, object> attributes)

用法示例

// Example 1: Revenue without product details
SingularSDK.Revenue("USD", 1.99);

// Example 2: Revenue with product details
SingularSDK.Revenue("USD", 4.99, "coin_package_abc123", "Coin Pack 5", "Bundles", 1, 4.99);

// Example 3: Revenue with attributes dictionary
Dictionary<string, object> attributes = new Dictionary<string, object>()
{
    ["productSKU"] = "coin_package_abc123",
    ["productName"] = "Coin Pack 5",
    ["productCategory"] = "Bundles",
    ["productQuantity"] = 2,
    ["productPrice"] = 4.99,
    ["transaction_id"] = "T12345"
};
SingularSDK.Revenue("USD", 9.98, attributes);

CustomRevenue 方法

发送带有指定事件名称、货币、金额和可选交易属性的自定义收入事件。

方法签名：

public static void CustomRevenue(string eventName, string currency, double amount)
public static void CustomRevenue(string eventName, string currency, double amount, string productSKU, string productName, string productCategory, int productQuantity, double productPrice)
public static void CustomRevenue(string eventName, string currency, double amount, Dictionary<string, object> attributes)

用法示例

// Example 1: Custom revenue without product details
SingularSDK.CustomRevenue("MyCustomRevenue", "USD", 9.99);

// Example 2: Custom revenue with product details
SingularSDK.CustomRevenue("MyCustomRevenue", "USD", 50.50, "abc123", "Premium Item", "Virtual Goods", 2, 25.50);

// Example 3: Custom revenue with attributes dictionary
Dictionary<string, object> attributes = new Dictionary<string, object>()
{
    ["productSKU"] = "premium_bundle_xyz",
    ["productName"] = "Premium Bundle",
    ["productCategory"] = "Bundles",
    ["productQuantity"] = 1,
    ["productPrice"] = 99.99,
    ["discount_applied"] = true
};
SingularSDK.CustomRevenue("PremiumBundlePurchase", "USD", 99.99, attributes);

StoreKit2 支持

Singular Unity SDK 不直接接受 StoreKit2 交易或产品的 JSON 表示形式。要追踪通过 StoreKit2 进行的 iOS 购买，并实现自动验证和更丰富的数据，请使用上文所述的 InAppPurchase 方法（Unity IAP v5），并传递 Unity IAP 的 Order 对象。

混合事件追踪（高级）

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

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

重要：

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

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

混合事件追踪指南

从内部服务器发送事件

从您的内部服务器收集收入数据，以分析广告活动效果和投资回报率（ROI）。

要求：

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

从收入提供商发送事件

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

支持的提供商：

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

从 Segment 发送事件

通过在 Segment 中添加"云模式"（Cloud-Mode）目标，使 Segment 能够在 Singular SDK 并行的同时向 Singular 发送事件。

请遵循实现指南 Singular-Segment 集成 获取详细的设置说明。

Unity SDK - 追踪应用内事件

追踪应用内事件

标准事件和属性

使用标准事件

发送事件

事件实现指南

Event 方法

用法示例

追踪应用内收入

最佳实践

Unity IAP 集成

使用 Unity IAP 进行应用内购买

InAppPurchase 方法（Unity IAP v5）

用法示例

InAppPurchase 方法（Unity IAP v4）

用法示例

无购买验证的自定义收入

手动收入追踪

Revenue 方法

用法示例

CustomRevenue 方法

用法示例

StoreKit2 支持

混合事件追踪（高级）

混合事件追踪指南

从内部服务器发送事件

从收入提供商发送事件

从 Segment 发送事件