手动事件跟踪

除了安装、打开、更新和购买（应用内购买）这些由Hive SDK自动跟踪的事件外，您还可以手动跟踪所需的事件。为此，您需要将事件注册到每个归因的仪表板上。例如，您可以跟踪特定事件，如完成游戏教程（TutorialComplete）或完成任务目标（MissionClear）。您应该在完成自动事件跟踪的设置后实施手动事件跟踪。

手动事件跟踪与 Adjust¶

要手动跟踪自定义事件，请在 Adjust 仪表板上注册事件，并获取应用程序令牌和事件令牌。应用程序令牌可以在仪表板主页面上获得，事件令牌可以在仪表板 > 所有设置 > 事件中找到。请参考 Adjust 仪表板指南了解如何获取令牌。
在 hive_config.xml 中添加每个事件的应用程序令牌和事件令牌。有关更多详细信息，请参见下面的示例代码。

Adjust 仪表板提供 SDK 签名 V3 以防止应用程序欺骗。要使用 SDK 签名，您必须审查与 Adjust 的合同条款。

<providers>
<!-- （已跳过） -->
<!-- 请勿设置Adjust节点的id字段。 -->
<!-- Adjust节点的name字段固定为“Adjust”。 -->
<!-- 事件节点的name字段由游戏工作室定义。但一旦设置，它应该与sendEvent()请求的所有其他营销归因的name字段相同。-->
<!-- 从Hive SDK v4 25.0.0开始，id、secretId、info1~4不再用于Adjust v5的应用 -->
<Adjust name="Adjust" key="APP_TOKEN">
        <events>
                <event name="TutorialComplete" value="TutorialComplete_EVENT_TOKEN"/>
                <event name="MissionClear" value="MissionClear_EVENT_TOKEN"/>
        </events>
<!-- （已跳过） -->
</Adjust>
</providers>

通过调用分析 API sendEvent() 发送事件。发送事件时，使用添加到 hive_config.xml 的 <event> 标签。在 <event> 标签值中，name 用作调用 API 时的参数，value 可以在相应归因的仪表板中查看。
- Analytics.sendEvent("TutorialComplete");
- Analytics.sendEvent("MissionClear");

手动跟踪事件与 Airbridge¶

获取所需的令牌。有关如何获取令牌的信息，请参阅Airbridge仪表板指南。
- 从仪表板 > 设置 > 令牌管理中获取应用程序SDK令牌和应用程序名称。
将令牌、应用程序名称和事件设置添加到hive_config.xml中。请参阅下面的 hive_config.xml 示例代码。在Windows上，令牌和应用程序名称设置不是必需的，但Hive控制台设置是必需的。
Airbridge提供SDK签名以防止应用程序欺骗。要使用相关功能，您必须首先检查与Airbridge的合同条款。获取密钥并将其作为secretId、secret值添加到hive_config.xml中。有关SDK签名安全信息的更多信息，请参阅Airbridge指南。仅支持Android和iOS，不支持Windows。
如果您同时应用Windows、Android和iOS，请联系Airbridge以获取预设。
通过调用分析API sendEvent()发送事件。发送事件时，使用添加到hive_config.xml中的<event>标签。在<event>标签值中，name作为调用API时的参数，value可以在相应归因的仪表板中查看。
- Analytics.sendEvent("TutorialComplete");
- Analytics.sendEvent("MissionClear");

hive_config.xml 示例代码¶

<providers>
    <Airbridge name="Airbridge" key="APP_SDK_TOKEN" appName="APP_NAME" secretId="SECRET_ID" secret="SECRET">
                <events>
                        <event name="TutorialComplete" value="Tutorial Complete" />
                        <event name="MissionClear" value="Mission Clear" />
                </events>
        </Airbridge>
</providers>

手动跟踪事件与 Singular、Appsflyer 和 Firebase Analytics¶

本节解释了如何使用Singular、Appsflyer和Firebase Analytics归因手动跟踪事件。

如下面所示，在每个归因的仪表板上获取所需的密钥。有关密钥发放方法，请参考各归因提供的仪表板指南。
- Singular: 在仪表板上获取 SDK Key 和 SDK SecretKey。
- Appsflyer: 在仪表板 > 应用设置中获取 Dev 密钥。
- Firebase Analytics: 不需要发放密钥。

hive_config.xml 文件按照下面的示例进行修改。特别是，当在 Hive SDK 的原生 iOS 或 Unity Android & iOS 以及 Unreal Engine Android & iOS 中使用 Appsflyer 归因时，需要设置 itunseConnectAppId 值以配置 Apple AppID。

  <providers>
  <!-- 设置 Singular -->
  <!-- Singular 节点 name 字段为 "Singular" 固定值。 -->
  <!-- event 节点 name 字段由游戏公司自行设置。 但是，为了调用 sendEvent()，其他归因也必须使用相同的值。-->
  <!-- event 节点 value 字段由游戏公司自行设置。 -->
  <Singular name="Singular" id="SDK_KEY" key="SDK_SECRET_KEY">
      <events>
          <event name="TutorialComplete" value="教程完成" />
          <event name="MissionClear" value="任务完成" />
      </events>
  </Singular> 

  <!-- 设置 AppsFlyer -->
  <!-- AppsFlyer 节点 name 字段为 "AppsFlyer" 固定值。 -->
  <!-- AppsFlyer 节点 id 字段不进行设置。 -->
  <!-- event 节点 name 字段由游戏公司自行设置。 但是，为了调用 sendEvent()，在其他归因中也必须使用相同的值。-->
  <!-- event 节点 value 字段由游戏公司自行设置。 -->
  <AppsFlyer name="AppsFlyer" id="unused" key="DEV_KEY" itunseConnectAppId="909923112">
      <events>
          <event name="TutorialComplete" value="教程完成" />
          <event name="MissionClear" value="任务完成" />
      </events>
  </AppsFlyer>

  <!-- Firebase Analytics 设置 -->
  <!-- event 节点 name 字段由游戏公司自行设置。调用 sendEvent() 时，其他归因也必须使用相同的值。-->
  <!-- event 节点 value 字段由游戏公司自行设置。 -->
  <firebase>
      <events>
        <event name="TutorialComplete" value="TutorialComplete" />
        <event name="MissionClear" value="MissionClear" />
      </events>
  </firebase>
  </providers>

通过调用 Analytics API sendEvent() 发送事件。在发送事件时，使用在 hive_config.xml 中添加的 <event> 标签值作为传递参数来发送事件。 <event> 标签值中的 name 在 API 调用时作为参数使用，value 可以在相应归因的仪表板中查看。
- Analytics.sendEvent("TutorialComplete");
- Analytics.sendEvent("MissionClear");

sendEvent()로事件发送¶

解释如何发送用于跟踪用户行为的事件到归因。

在发送追踪事件时，建议在用户的行为满足特定条件时发送，例如“完成教程”，而不是追踪用户的所有行为。

要发送用户行为跟踪事件，请调用Analytics API的sendEvent()函数。sendEvent()函数的第一个参数值应输入在hive_config.xml设置文件中定义的<event>元素的name属性值。

当用户完成教程时，发送 TutorialComplete 事件到营销归因的示例代码如下所示。

Unity虚幻引擎C++KotlinJavaObjective-CSwift

API 参考: hive.Analytics.sendEvent

using hive;    
    String eventName = "TutorialComplete";    
Analytics.sendEvent(eventName);

#include "HiveAnalytics.h"

FString 事件名称 = TEXT("教程完成");
FHiveAnalytics::SendEvent(事件名称);

API 参考: Analytics::sendEvent

#include <HIVE_SDK_Plugin/HIVE_CPP.h>    
    using namespace std;    
    using namespace hive;    
    string eventName = "TutorialComplete";    
Analytics::sendEvent(eventName);

API 参考: Analytics.sendEvent

import com.hive.Analytics    
    val eventName = "TutorialComplete"    
Analytics.sendEvent(eventName)

API 参考: AnalyticsInterface .sendEvent

import HIVEService    
    let eventName = "TutorialComplete"    
AnalyticsInterface.sendEvent(eventName)

API 参考: HIVEAnalytics:sendEvent

#import <HIVEService/HIVEService-Swift.h>    
    NSString eventName = @"TutorialComplete";    
[HIVEAnalytics sendEvent: eventName];

API 参考: AnalyticsInterface.sendEvent

#import HIVEService   
    let eventName = "TutorialComplete"
AnalyticsInterface.sendEvent(eventName)

使用sendEventWithAttributes()发送附加属性¶

当调用sendEventWithAttributes()函数代替sendEvent()时，可以添加用户定义的属性进行发送。

sendEventWithAttributes() 函数的第一个参数值是输入在 hive_config.xml 配置文件中定义的 <event> 元素的 name 属性值。

添加自定义属性¶

可以通过调用addCustomAttribute()将自定义属性添加到Hive SDK支持的所有营销归因（Airbridge、Adjust、Appsflyer、Singular、Firebase Analytics）并进行传输。

Note

自定义属性（Custom Attribute）是用户定义的属性，支持 String、Int、Float、Double、Boolean 数据类型。不过，在通过 Adjust 发送时，无论数据类型如何，所有数据类型都会转换为 String 发送。

以下是添加自定义属性并发送的示例代码。

Unity虚幻引擎C++KotlinJavaObjective-CSwift

API 参考: hive.Analytics.sendEventWithAttributes

using hive;    

// 创建 AnalyticsAttributes
var analyticsAttributes = new AnalyticsAttributes();

// 添加自定义属性
analyticsAttributes.AddCustomAttribute("key1", "value1");
analyticsAttributes.AddCustomAttribute("key2", "value2");

Analytics.sendEventWithAttributes("Quest Complete", analyticsAttributes);

#include "HiveAnalytics.h"

// 创建 AnalyticsAttributes
FHiveAnalyticsAttributes AnalyticsAttributes;

// 添加自定义属性
TSharedPtr<FJsonValue> CustomJsonValue1 = MakeShareable(new FJsonValueString("value1"));
AnalyticsAttributes.AddCustomAttribute(TEXT("key1"), CustomJsonValue1);
TSharedPtr<FJsonValue> CustomJsonValue2 = MakeShareable(new FJsonValueString("value2"));
AnalyticsAttributes.AddCustomAttribute(TEXT("key2"), CustomJsonValue2);

FHiveAnalytics::SendEventWithAttributes(strEventName, AnalyticsAttributes);

API 参考: Analytics::sendEventWithAttributes

#include <HIVE_SDK_Plugin/HIVE_CPP.h>    
using namespace std;   
using namespace hive;

// 创建 AnalyticsAttributes
AnalyticsAttributes analyticsAttributes;

// 添加自定义属性
analyticsAttributes.addCustomAttribute("key1", picojson::value("value1"));
analyticsAttributes.addCustomAttribute("key2", picojson::value("value2"));

std::string eventName = "Quest Complete";

Analytics::sendEventWithAttributes(eventName, analyticsAttributes);

API 参考: Analytics.sendEventWithAttributes

import com.hive.Analytics    
import com.hive.analytics.provider.attributes.AirbridgeSpecific
import com.hive.analytics.provider.attributes.AnalyticsAttributes

// 创建 AnalyticsAttributes
val analyticsAttributes = AnalyticsAttributes()

// 添加自定义属性
analyticsAttributes.addCustomAttribute("key1", "value1")
analyticsAttributes.addCustomAttribute("key2", "value2")

Analytics.sendEventWithAttributes("Quest Complete", analyticsAttributes)

API 参考: Analytics.sendEventWithAttributes

import com.hive.Analytics;
import com.hive.analytics.provider.attributes.AirbridgeSpecific;
import com.hive.analytics.provider.attributes.AnalyticsAttributes;

// 创建 AnalyticsAttributes
AnalyticsAttributes analyticsAttributes = new AnalyticsAttributes();

// 添加自定义属性
analyticsAttributes.addCustomAttribute("key1", "value1");
analyticsAttributes.addCustomAttribute("key2", "value2");

Analytics.sendEventWithAttributes("Quest Complete", analyticsAttributes);

API 参考: HIVEAnalytics:sendEventWithAttributes

#import <HIVEService/HIVEService-Swift.h>

HiveAnalyticsAttributes* analyticsAttributes = [[HiveAnalyticsAttributes alloc] init];

[analyticsAttributes addModuleSpecificAttribute: airbridgeSpecific];
[analyticsAttributes addCustomAttribute: @"key1" value: @"value1"];
[analyticsAttributes addCustomAttribute: @"key2" value: @"value2"];

[HIVEAnalytics sendEventWithAttributes: @"Quest Complete" attributes: analyticsAttributes];

API 参考: HIVEAnalytics:sendEventWithAttributes

#import HIVEService

// 创建 AnalyticsAttributes
let analyticsAttributes = AnalyticsAttributes()

// 添加自定义属性
analyticsAttributes.addCustomAttribute("key1", value: "value1")
analyticsAttributes.addCustomAttribute("key2", value: "value2")

AnalyticsInterface.sendEventWithAttributes("Quest Complete", attributes: analyticsAttributes)

向 Airbridge 发送语义属性¶

在向 Airbridge 发送附加属性时，可以添加以下语义属性，除了自定义属性之外。

动作(Action)、标签(Label)：从 Airbridge 报告中收集可以用于分组的信息。
值：收集用于收入分析的信息。
语义属性(Semantic Attribute)：在 Airbridge 中的预定义属性。
- 如果输入的属性字符串与预定义属性不同，可能无法收集。
- 数据格式与语义属性不匹配的事件将不会被收集。由于每个语义属性的数据格式各不相同，因此需要谨慎。
- 数据格式为字符串的语义属性允许最多 1024 个字符。数据格式为整数或浮点数的语义属性允许最多 64 位。

Unity虚幻引擎C++KotlinJavaObjective-CSwift

API 参考: hive.Analytics.sendEventWithAttributes

using hive;    

// 创建 AnalyticsAttributes
var analyticsAttributes = new AnalyticsAttributes();

// Airbridge的特定属性
var airbridgeSpecific = new AirbridgeSpecific();
// 动作
airbridgeSpecific.SetSemanticAction("工具");
// 标签
airbridgeSpecific.SetSemanticLabel("锤子");
// 值
airbridgeSpecific.SetSemanticValue(10);

// 语义属性
airbridgeSpecific.AddSemanticAttribute("type", "Warrior");
airbridgeSpecific.AddSemanticAttribute("score", 20);

// 添加 Airbridge 特定属性
analyticsAttributes.AddModuleSpecificAttributes(airbridgeSpecific);

// 添加自定义属性
analyticsAttributes.AddCustomAttribute("key1", "value1");
analyticsAttributes.AddCustomAttribute("key2", "value2");

Analytics.sendEventWithAttributes("Quest Complete", analyticsAttributes);

#include "HiveAnalytics.h"

// 创建 AnalyticsAttributes
FHiveAnalyticsAttributes AnalyticsAttributes;

// Airbridge的特定属性
FHiveAirbridgeSpecific AirbridgeSpecific;
// 动作
AirbridgeSpecific.SetSemanticAction(TEXT("工具"));
// 标签
AirbridgeSpecific.SetSemanticLabel(TEXT("锤子"));
// 值
AirbridgeSpecific.SetSemanticValue(10.0);

// 语义属性
TSharedPtr<FJsonValue> SemanticJsonValue1 = MakeShared<FJsonValueString>(TEXT("Warrior"));
AirbridgeSpecific.AddSemanticAttribute(TEXT("type"), SemanticJsonValue1);
TSharedPtr<FJsonValue> SemanticJsonValue2 = MakeShared<FJsonValueNumber>(20);
AirbridgeSpecific.AddSemanticAttribute(TEXT("score"), SemanticJsonValue2);

// 添加 Airbridge 特定属性
AnalyticsAttributes.AddModuleSpecificAttribute(AirbridgeSpecific);

// 添加自定义属性
TSharedPtr<FJsonValue> CustomJsonValue1 = MakeShareable(new FJsonValueString("value1"));
AnalyticsAttributes.AddCustomAttribute(TEXT("key1"), CustomJsonValue1);
TSharedPtr<FJsonValue> CustomJsonValue2 = MakeShareable(new FJsonValueString("value2"));
AnalyticsAttributes.AddCustomAttribute(TEXT("key2"), CustomJsonValue2);

FHiveAnalytics::SendEventWithAttributes(strEventName, AnalyticsAttributes);

API 参考: Analytics::sendEventWithAttributes

#include <HIVE_SDK_Plugin/HIVE_CPP.h>    
using namespace std;   
using namespace hive;

// 创建 AnalyticsAttributes
AnalyticsAttributes analyticsAttributes;

// Airbridge的特定属性
AirbridgeSpecific airbridgeSpecific;

std::string semanticAction = "工具";
std::string semanticLabel = "锤子";
double semanticValue = 10.0;

// 动作
airbridgeSpecific.setSemanticAction(semanticAction);
// 标签
airbridgeSpecific.setSemanticLabel(semanticLabel);
// 值
airbridgeSpecific.setSemanticValue(semanticValue);

// 语义属性
airbridgeSpecific.addSemanticAttribute("type", picojson::value("Warrior"));
airbridgeSpecific.addSemanticAttribute("score", picojson::value(20.0f));

// 添加 Airbridge 特定属性
analyticsAttributes.addModuleSpecificAttribute(airbridgeSpecific);

// 添加自定义属性
analyticsAttributes.addCustomAttribute("key1", picojson::value("value1"));
analyticsAttributes.addCustomAttribute("key2", picojson::value("value2"));

std::string eventName = "任务完成";

Analytics::sendEventWithAttributes(eventName, analyticsAttributes);

API 参考: Analytics.sendEventWithAttributes

import com.hive.Analytics    
import com.hive.analytics.provider.attributes.AirbridgeSpecific
import com.hive.analytics.provider.attributes.AnalyticsAttributes

// 创建 AnalyticsAttributes
val analyticsAttributes = AnalyticsAttributes()

// Airbridge的特定属性
val airbridgeSpecific = AirbridgeSpecific().apply {
    setSemanticAction("工具")                // 动作
    setSemanticLabel("锤子")               // 标签
    setSemanticValue(10.0)                  // 值
    addSemanticAttribute("类型", "战士")  // 语义属性
    addSemanticAttribute("分数", 20.0f)     // 语义属性
}

// 添加 Airbridge 特定属性
analyticsAttributes.addModuleSpecificAttribute(airbridgeSpecific)

// 添加自定义属性
analyticsAttributes.addCustomAttribute("key1", "value1")
analyticsAttributes.addCustomAttribute("key2", "value2")

Analytics.sendEventWithAttributes("Quest Complete", analyticsAttributes)

API 参考: Analytics.sendEventWithAttributes

import com.hive.Analytics;
import com.hive.analytics.provider.attributes.AirbridgeSpecific;
import com.hive.analytics.provider.attributes.AnalyticsAttributes;

// 创建 AnalyticsAttributes
AnalyticsAttributes analyticsAttributes = new AnalyticsAttributes();

// Airbridge的特定属性
AirbridgeSpecific airbridgeSpecific = new AirbridgeSpecific();
airbridgeSpecific.setSemanticAction("工具");                // 动作
airbridgeSpecific.setSemanticLabel("锤子");               // 标签
airbridgeSpecific.setSemanticValue(10.0);                  // 值
airbridgeSpecific.addSemanticAttribute("类型", "战士");  // 语义属性
airbridgeSpecific.addSemanticAttribute("分数", 20.0f);     // 语义属性

// 添加 Airbridge 特定属性
analyticsAttributes.addModuleSpecificAttribute(airbridgeSpecific);

// 添加自定义属性
analyticsAttributes.addCustomAttribute("key1", "value1");
analyticsAttributes.addCustomAttribute("key2", "value2");

Analytics.sendEventWithAttributes("Quest Complete", analyticsAttributes);

API 参考: HIVEAnalytics:sendEventWithAttributes

#import <HIVEService/HIVEService-Swift.h>

HiveAnalyticsAttributes* analyticsAttributes = [[HiveAnalyticsAttributes alloc] init];

HiveAirbridgeSpecific* airbridgeSpecific = [[HiveAirbridgeSpecific alloc] init];
[airbridgeSpecific setSemanticAction: @"Tool"];
[airbridgeSpecific setSemanticAction: @"Hammer"];
[airbridgeSpecific setSemanticValue: 10.0];
[airbridgeSpecific addSemanticAttribute: @"type" value: @"Warrior"];
[airbridgeSpecific addSemanticAttribute: @"score" value: @20.0f];

[analyticsAttributes addModuleSpecificAttribute: airbridgeSpecific];
[analyticsAttributes addCustomAttribute: @"key1" value: @"value1"];
[analyticsAttributes addCustomAttribute: @"key2" value: @"value2"];

[HIVEAnalytics sendEventWithAttributes: @"Quest Complete" attributes: analyticsAttributes];

API 参考: HIVEAnalytics:sendEventWithAttributes

#import HIVEService

// 创建 AnalyticsAttributes
let analyticsAttributes = AnalyticsAttributes()

// Airbridge的特定属性
let airbridgeSpecific = AirbridgeSpecific()
airbridgeSpecific.setSemanticAction("工具")
airbridgeSpecific.setSemanticLabel("锤子")
airbridgeSpecific.setSemanticValue(10.0)
airbridgeSpecific.addSemanticAttribute("类型", value: "战士")
airbridgeSpecific.addSemanticAttribute("分数", value: 20.0)

// 添加 Airbridge 特定属性
analyticsAttributes.addModuleSpecificAttribute(airbridgeSpecific)

// 添加自定义属性
analyticsAttributes.addCustomAttribute("key1", value: "value1")
analyticsAttributes.addCustomAttribute("key2", value: "value2")

AnalyticsInterface.sendEventWithAttributes("Quest Complete", attributes: analyticsAttributes)

在 Firebase 环境中应用 Google Ads 设备内测量¶

要在Firebase环境中测量Google Ads提供的设备内转化，您需要实施Firebase Google ODM解决方案。该解决方案要求用户同意提供的电子邮件地址或电话号码。在实施此解决方案期间，如果实现了Firebase身份验证或开发者引入的单独身份验证环境，则Hive SDK不会收集电子邮件地址，而是将身份验证后获得的任何电子邮件地址直接传递给Firebase API。

Note

本指南仅适用于iOS应用。Android应用在Firebase环境中测量设备内转换时不需要单独的流程。

实施方法¶

在下面的整个过程中，您必须确保用户设备上的个人识别信息不会泄露到外部。

下载Google Firebase ODM Unity 插件并将其添加到您的 Unity 项目中。
实现身份验证以在登录后获取 IdP 电子邮件地址或电话号码。
根据 Firebase 定义的方法规范化电子邮件地址或电话号码。
实现将规范化的电子邮件地址/电话号码传递给 Firebase。或者，实现将规范化的电子邮件地址/电话号码的哈希值传递给 Firebase。请参阅下面的示例代码。

Note

插件 API 可以按顺序调用，但后续调用在每个用户调用一次后基本上会被忽略。

示例代码¶

以下是使用Unity插件时的示例代码。

使用哈希值的示例代码¶

电子邮件电话号码

using hive;
// 发送哈希和标准化的电子邮件地址
GoogleODM.setHashedEmailAddress(ComputeSha256Hash("abc@abc.com"));

using hive;
// 发送哈希和标准化的电话号码信息
GoogleODM.setHashedPhoneNumber(ComputeSha256Hash("+821012345678"));

使用纯值的示例代码¶

电子邮件电话号码

using hive;
// 发送规范化的电子邮件地址
GoogleODM.setEmailAddress("abc@abc.com");

using hive;
// 发送标准化的电话号码信息
GoogleODM.setPhoneNumber("+821012345678");