Skip to content

Manual event tracking

Aside from Install, Open, Update, and Purchase (in-app purchase) which are tracked automatically by Hive SDK (hearinafter "SDK"), you can manually track the necessary events you want. To do this, you need to register the event to the dashboard of each attribution. For example, you can track specific events like the completion of your game tutorial (TutorialComplete) or the completion of a mission objective (MissionClear). You should implement the manual event tracking after finishing setting up the automatic event tracking.

Manual Event Tracking with Adjust

  1. To track custom events manually, register the events on Adjust dashboard, and get the app token and the event tokens. The app token can be obtained on the dashboard main page, and the event tokens on Dashboard > All Settings > Events. Refer to the Adjust dashboard guide to learn how to get the tokens.
  2. Add the app token and the event token of each event on hive_config.xml. For more details, see the example codes below.

  3. The Adjust dashboard provides SDK Signature V3 for app spoofing prevention. To use the SDK Signature, you must review the contractual terms with Adjust.

    <providers>
<!-- (skipped) -->
<!-- Do not set the id field of the Adjust node. -->
<!-- The name field of the Adjust node is fixed to "Adjust." -->
<!-- The name field of the event node is defined by the game studio. But once it is set, it should be the same for the name field of all other marketing attributions for the sendEvent() request.-->
<!-- From Hive SDK v4 25.0.0, id, secretId, info1~4 are no longer used as of the application of Adjust v5 -->
<Adjust name="Adjust" key="APP_TOKEN">
        <events>
                <event name="TutorialComplete" value="TutorialComplete_EVENT_TOKEN"/>
                <event name="MissionClear" value="MissionClear_EVENT_TOKEN"/>
        </events>
<!-- (skipped) -->
</Adjust>
</providers>

  4. Send events by calling the Analytics API sendEvent(). When sending events, use the <event> tag added to hive_config.xml. Among the <event> tag values, name is used as a parameter when calling the API, and value can be checked in the dashboard of the corresponding attribution.

    • Analytics.sendEvent("TutorialComplete");
    • Analytics.sendEvent("MissionClear");

Tracking Events Manually with Airbridge

  1. Get the required token. For information on how to get a token, refer to the Airbridge Dashboard Guide.
    • Get the App SDK Token and App Name from Dashboard > Settings > Token Management.
  2. Add the token, app name, and event settings to hive_config.xml. Refer to the hive_config.xml example code below. On Windows, the token and app name settings are not required, but the Hive console settings are required.
  3. Airbridge provides SDK Signature to prevent app spoofing. To use the related function, you must first check the contract terms with Airbridge. Get the key and add it as secretId, secret value in hive_config.xml. For more information about SDK signature security information, refer to the Airbridge Guide. It is supported only on Android and iOS, not on Windows.
  4. If you are applying Windows, Android, and iOS together, contact Airbridge for presets.
  5. Send events by calling the Analytics API sendEvent(). When sending events, use the <event> tag added to hive_config.xml. Among the <event> tag values, name is used as a parameter when calling the API, and value can be checked in the dashboard of the corresponding attribution.
    • Analytics.sendEvent("TutorialComplete");
    • Analytics.sendEvent("MissionClear");

hive_config.xml example code

<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>

Track events manually with Singular, Appsflyer, and Firebase Analytics

This section explains how to manually track events with Singular, Appsflyer, and Firebase Analytics attribution.

  1. Obtain the required keys from each attribution dashboard as shown below. For instructions on how to obtain the keys, refer to each attribution's dashboard guide.
  2. Modify the hive_config.xml file as shown in the example below. In particular, when using Appsflyer attribution with Native SDK for iOS or Unity SDK for Android & iOS and Unreal Engine SDK for Android & iOS, set the itunseConnectAppId value for Apple AppID configuration. 
      <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="Tutorial Complete" />
          <event name="MissionClear" value="Mission Clear" />
      </events>
  </AppsFlyer>

  <!-- Firebase Analytics 설정하기 -->
  <!-- event 노드 name 필드는 게임사에서 임의로 설정합니다. 단, sendEvent() 호출을 위해 다른 어트리뷰션에서도 동일한 값을 사용해야 합니다.-->
  <!-- event 노드 value 필드는 게임사에서 임의로 설정합니다. -->
  <firebase>
      <events>
        <event name="TutorialComplete" value="TutorialComplete" />
        <event name="MissionClear" value="MissionClear" />
      </events>
  </firebase>
  </providers>
  3. Send events by calling the Analytics API sendEvent(). When sending events, use the <event> tag added to hive_config.xml as the argument. Among the <event> tag values, name is used as a parameter when calling the API, and value can be checked in the dashboard of the corresponding attribution.
    • Analytics.sendEvent("TutorialComplete");
    • Analytics.sendEvent("MissionClear");
## Sending Events with sendEvent() { #send-event }
This section explains how to send user action tracking events to attribution providers.

When sending tracking events to attribution, it is recommended to send events only when a user's action meets specific conditions, such as "Tutorial Complete," rather than tracking every user action.

To send user action tracking events, call the <strong>Analytics API</strong> function <code>sendEvent()</code>. The first parameter of the <code>sendEvent()</code> function should be the <code>name</code> attribute value of the <code>&lt;event&gt;</code> element defined in the hive_config.xml configuration file.

Below is an example code for sending the TutorialComplete event to marketing attribution when a user completes the tutorial.

API Reference: hive.Analytics.sendEvent

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

#include "HiveAnalytics.h"

FString EventName = TEXT("TutorialComplete");
FHiveAnalytics::SendEvent(EventName);

API Reference: Analytics::sendEvent

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

API Reference: Analytics.sendEvent

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

API Reference: AnalyticsInterface .sendEvent

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

API Reference: HIVEAnalytics:sendEvent

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

API Reference: AnalyticsInterface.sendEvent

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

sendEventWithAttributes()로 추가 어트리뷰트 전송하기

sendEvent() 대신 sendEventWithAttributes() 함수를 호출하는 경우, 사용자가 정의한 어트리뷰트를 추가하여 전송할 수 있습니다.

sendEventWithAttributes() 함수의 첫 번째 파라미터 값은 hive_config.xml 설정 파일에 정의한 <event> 요소의 name 속성 값으로 입력합니다.

Adding Custom Attributes

You can add and send custom attributes to all marketing attribution providers supported by the SDK (Airbridge, Adjust, Appsflyer, Singular, Firebase Analytics) by calling addCustomAttribute().

Note

A custom attribute is a user-defined property that supports String, Int, Float, Double, and Boolean data types. However, when sending to Adjust, all data types are converted to String regardless of their original type.

Below is an example code for adding and sending custom attributes.

API Reference: hive.Analytics.sendEventWithAttributes

using hive;    

// Create AnalyticsAttributes
var analyticsAttributes = new AnalyticsAttributes();

// Add Custom Attribute
analyticsAttributes.AddCustomAttribute("key1", "value1");
analyticsAttributes.AddCustomAttribute("key2", "value2");

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

#include "HiveAnalytics.h"

// Create AnalyticsAttributes
FHiveAnalyticsAttributes AnalyticsAttributes;

// Add Custom Attribute
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 Reference: Analytics::sendEventWithAttributes

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

// Create AnalyticsAttributes
AnalyticsAttributes analyticsAttributes;

// Add Custom Attribute
analyticsAttributes.addCustomAttribute("key1", picojson::value("value1"));
analyticsAttributes.addCustomAttribute("key2", picojson::value("value2"));

std::string eventName = "Quest Complete";

Analytics::sendEventWithAttributes(eventName, analyticsAttributes);

API Reference: Analytics.sendEventWithAttributes

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

// Create AnalyticsAttributes
val analyticsAttributes = AnalyticsAttributes()

// Add Custom Attribute
analyticsAttributes.addCustomAttribute("key1", "value1")
analyticsAttributes.addCustomAttribute("key2", "value2")

Analytics.sendEventWithAttributes("Quest Complete", analyticsAttributes)

API Reference: Analytics.sendEventWithAttributes

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

// Create AnalyticsAttributes
AnalyticsAttributes analyticsAttributes = new AnalyticsAttributes();

// Add Custom Attribute
analyticsAttributes.addCustomAttribute("key1", "value1");
analyticsAttributes.addCustomAttribute("key2", "value2");

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

API Reference: 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 Reference: HIVEAnalytics:sendEventWithAttributes

import HIVEService

// Create AnalyticsAttributes
let analyticsAttributes = AnalyticsAttributes()

// Add Custom Attribute
analyticsAttributes.addCustomAttribute("key1", value: "value1")
analyticsAttributes.addCustomAttribute("key2", value: "value2")

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

Airbridge에 시맨틱 어트리뷰트 전송하기

Airbridge에 추가 어트리뷰트 전송 시, 커스텀 어트리뷰트 외에도 아래와 같은 시맨틱 어트리뷰트를 추가하여 전송할 수 있습니다.

  • 액션(Action), 라벨(Label): Airbridge 리포트에서 그룹바이로 활용할 수 있는 정보를 수집합니다.
  • Value: Collects information used for revenue analysis.
  • 시맨틱 어트리뷰트(Semantic Attribute): Airbridge에서 미리 정의한 어트리뷰트입니다.
    • If you enter an attribute string other than the predefined attributes, it may not be collected.
    • Events with data that do not match the data format of the semantic attribute will not be collected. Since the data format varies for each semantic attribute, caution is required.
    • Semantic attributes with a data format of string are allowed up to 1024 characters. Semantic attributes with a data format of int or float are allowed up to 64 bits.

API Reference: hive.Analytics.sendEventWithAttributes

using hive;    

// Create AnalyticsAttributes
var analyticsAttributes = new AnalyticsAttributes();

// Specific Attribute for Airbridge
var airbridgeSpecific = new AirbridgeSpecific();
// Action
airbridgeSpecific.SetSemanticAction("Tool");
// Label
airbridgeSpecific.SetSemanticLabel("Hammer");
// Value
airbridgeSpecific.SetSemanticValue(10);

// Semantic Attribute
airbridgeSpecific.AddSemanticAttribute("type", "Warrior");
airbridgeSpecific.AddSemanticAttribute("score", 20);

// Add Airbridge Specific Attribute
analyticsAttributes.AddModuleSpecificAttributes(airbridgeSpecific);

// Add Custom Attribute
analyticsAttributes.AddCustomAttribute("key1", "value1");
analyticsAttributes.AddCustomAttribute("key2", "value2");

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

#include "HiveAnalytics.h"

// Create AnalyticsAttributes
FHiveAnalyticsAttributes AnalyticsAttributes;

// Specific Attribute for Airbridge
FHiveAirbridgeSpecific AirbridgeSpecific;
// Action
AirbridgeSpecific.SetSemanticAction(TEXT("Tool"));
// Label
AirbridgeSpecific.SetSemanticLabel(TEXT("Hammer"));
// Value
AirbridgeSpecific.SetSemanticValue(10.0);

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

// Add Airbridge Specific Attribute
AnalyticsAttributes.AddModuleSpecificAttribute(AirbridgeSpecific);

// Add Custom Attribute
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 Reference: Analytics::sendEventWithAttributes

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

// Create AnalyticsAttributes
AnalyticsAttributes analyticsAttributes;

// Specific Attribute for Airbridge
AirbridgeSpecific airbridgeSpecific;

std::string semanticAction = "Tool";
std::string semanticLabel = "Hammer";
double semanticValue = 10.0;

// Action
airbridgeSpecific.setSemanticAction(semanticAction);
// Label
airbridgeSpecific.setSemanticLabel(semanticLabel);
// Value
airbridgeSpecific.setSemanticValue(semanticValue);

// Semantic Attribute
airbridgeSpecific.addSemanticAttribute("type", picojson::value("Warrior"));
airbridgeSpecific.addSemanticAttribute("score", picojson::value(20.0f));

// Add Airbridge Specific Attribute
analyticsAttributes.addModuleSpecificAttribute(airbridgeSpecific);

// Add Custom Attribute
analyticsAttributes.addCustomAttribute("key1", picojson::value("value1"));
analyticsAttributes.addCustomAttribute("key2", picojson::value("value2"));

std::string eventName = "Quest Complete";

Analytics::sendEventWithAttributes(eventName, analyticsAttributes);

API Reference: Analytics.sendEventWithAttributes

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

// Create AnalyticsAttributes
val analyticsAttributes = AnalyticsAttributes()

// Specific Attribute for Airbridge
val airbridgeSpecific = AirbridgeSpecific().apply {
    setSemanticAction("Tool")                // Action
    setSemanticLabel("Hammer")               // Label
    setSemanticValue(10.0)                  // Value
    addSemanticAttribute("type", "Warrior")  // Semantic Attribute
    addSemanticAttribute("score", 20.0f)     // Semantic Attribute
}

// Add Airbridge Specific Attribute
analyticsAttributes.addModuleSpecificAttribute(airbridgeSpecific)

// Add Custom Attribute
analyticsAttributes.addCustomAttribute("key1", "value1")
analyticsAttributes.addCustomAttribute("key2", "value2")

Analytics.sendEventWithAttributes("Quest Complete", analyticsAttributes)

API Reference: Analytics.sendEventWithAttributes

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

// Create AnalyticsAttributes
AnalyticsAttributes analyticsAttributes = new AnalyticsAttributes();

// Specific Attribute for Airbridge
AirbridgeSpecific airbridgeSpecific = new AirbridgeSpecific();
airbridgeSpecific.setSemanticAction("Tool");                // Action
airbridgeSpecific.setSemanticLabel("Hammer");               // Label
airbridgeSpecific.setSemanticValue(10.0);                  // Value
airbridgeSpecific.addSemanticAttribute("type", "Warrior");  // Semantic Attribute
airbridgeSpecific.addSemanticAttribute("score", 20.0f);     // Semantic Attribute

// Add Airbridge Specific Attribute
analyticsAttributes.addModuleSpecificAttribute(airbridgeSpecific);

// Add Custom Attribute
analyticsAttributes.addCustomAttribute("key1", "value1");
analyticsAttributes.addCustomAttribute("key2", "value2");

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

API Reference: 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 Reference: HIVEAnalytics:sendEventWithAttributes

#import HIVEService

// Create AnalyticsAttributes
let analyticsAttributes = AnalyticsAttributes()

// Specific Attribute for Airbridge
let airbridgeSpecific = AirbridgeSpecific()
airbridgeSpecific.setSemanticAction("Tool")
airbridgeSpecific.setSemanticLabel("Hammer")
airbridgeSpecific.setSemanticValue(10.0)
airbridgeSpecific.addSemanticAttribute("type", value: "Warrior")
airbridgeSpecific.addSemanticAttribute("score", value: 20.0)

// Add Airbridge Specific Attribute
analyticsAttributes.addModuleSpecificAttribute(airbridgeSpecific)

// Add Custom Attribute
analyticsAttributes.addCustomAttribute("key1", value: "value1")
analyticsAttributes.addCustomAttribute("key2", value: "value2")

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

Applying Google Ads on-device measurement in Firebase environment

To measure on-device conversions provided by Google Ads in a Firebase environment, you need to implement the Firebase Google ODM Solution. This solution requires the email address or phone number that the user has consented to provide. During the implementation of this solution, if Firebase Authentication or a separate authentication environment introduced by the developer is implemented, the SDK does not collect email addresses and only passes any email address obtained in the response after authentication directly to the Firebase API.

Note

This guide is intended for iOS apps only. Android apps do not require a separate process for measuring on-device conversions in the Firebase environment.

Implementation method

Throughout the entire process below, you must make sure that personal information for identification must not leak from the user's device to the outside.

  1. Download the Google Firebase ODM Unity Plugin and add it to your Unity project.
  2. Implement authentication to obtain the IdP email address or phone number after logging in.
  3. Normalize the email address or phone number according to the method defined by Firebase.
  4. Implement the passing of the normalized email address/phone number to Firebase. Alternatively, implement the passing of the hashed value of the normalized email address/phone number to Firebase. Refer to the example code below.
Note

The plugin API can be called sequentially, but subsequent calls are essentially ignored after being called once per user.

Example code

Below is example code when using the Unity plugin.

Example code using hashed values

using hive;
// Sending the hashed & normalized email address
GoogleODM.setHashedEmailAddress(ComputeSha256Hash("abc@abc.com"));

using hive;
// Sending the hashed & normalized phone number information
GoogleODM.setHashedPhoneNumber(ComputeSha256Hash("+821012345678"));

Example code using plain values

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

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