手动事件跟踪

除了安装、打开、更新和购买（应用内购买）这些由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("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;
// Sending the hashed & normalized email address
GoogleODM.setHashedEmailAddress(ComputeSha256Hash("abc@abc.com"));

using hive;
// 發送已哈希和標準化的電話號碼信息
GoogleODM.setHashedPhoneNumber(ComputeSha256Hash("+821012345678"));

使用純值的範例代碼¶

電子郵件電話號碼

using hive;
// Sending the normalized email address
GoogleODM.setEmailAddress("abc@abc.com");

using hive;
// Sending the normalized phone number information
GoogleODM.setPhoneNumber("+821012345678");