手动事件跟踪

除了安装、打开、更新和购买（应用内购买）这些由 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 密鑰和 SDK 秘密密鑰。
- 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="Tutorial Complete" />
          <event name="MissionClear" value="Mission Clear" />
      </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("TutorialComplete");
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 = "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()

// 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;
// Sending the normalized phone number information
GoogleODM.setPhoneNumber("+821012345678");