3. Send in-game event data

Sending sufficient in-game event and player attribute data to Airflux is essential for model training and ad display optimization. This step may take approximately 30 minutes to 1 hour, depending on the number of events and attributes you want to track.


1. Implement session tracking

To implement session tracking within a Unity project, integrate the following methods into the Airflux SDK as shown below.

The NotifyAppForeground() function should be called when the app gains focus, signaling the start of a user session. Conversely, NotifyAppBackground() should be called when the application is sent to the background, indicating the end of the session.

By integrating these calls, Airflux can collect session information, including session count, duration, and maximum session length.

using UnityEngine;

public class AirfluxBehaviour : MonoBehaviour
{
    void OnApplicationFocus(bool hasFocus)
    {
        Airflux.NotifyAppForeground();
    }

    void OnApplicationPause(bool pauseStatus)
    {
        Airflux.NotifyAppBackground();
    }
}

2. Send in-game event data

Use the TrackEvent() function to track key player actions within the game. The in-game event data plays a crucial role in enabling the Airflux AI model to learn player behavior patterns.

Event Name
When to trigger

Ad Impression

When the ad is shown to the user

Order Completed

When the in-app purchase is completed and the user receives the item (e.g., when a dialog appears confirming the purchase)

Achieve Level

When a stage ends (e.g., Success, Fail, Give-up, Retry)

Spend Credits

When the player spends in-game currency

The TrackEvent() function should be called when a key event is triggered. Refer to the table below for the detailed requirements for the key components.

Name
Type
Description

category

String

Name of the event

Only underscores are permitted as special characters; colons and other special characters are not allowed. If the collected data exceeds the maximum limit of 128 characters, only the initial 128 characters will be saved.

semanticAttributes

Dictionary<string, object>

Semantic attributes of the event

Semantic attribute data collection is limited by type: up to 1024 characters for strings, and 64 bits for integers or floats.

customAttributes

Dictionary<string, object>

Custom attributes of the event

Custom attribute data collection is limited to 2,048 characters; exceeding the limit results in ERROR_MAX_LENGTH_EXCEEDED.

Airflux.TrackEvent(
    // StandardCategory
    category: AirfluxCategory.AD_IMPRESSION,
    // SemanticAttributes
    semanticAttributes: new Dictionary<string, object>()
    {
        { AirfluxAttribute.VALUE, 11 },
        { AirfluxAttribute.TRANSACTION_ID, "8065ef16-162b-4a82-b683-e51aefdda7d5" },
        { AirfluxAttribute.CURRENCY, "USD" }
    },
    // CustomAttributes
    customAttributes: new Dictionary<string, object>()
    {
        { "key", "value" }
    }
);

Sample codes for event

Achieve Level

Track player game progress and how a stage ended.

For example, when a stage ends, call the TrackEvent() function, set the event category to AirfluxCategory.ACHIEVE_LEVEL, and add "stage_type" and "stage_number" to track the stage type and stage number.

Additionally, use "result" to send information on how the stage ended, such as success, fail, giveup, and retry .

Attribute Type
Name
Semantic Attributes Description
Sample Value

Custom Attribute

stage_type

The type of the stage

main: Main stage promotion: Seasonal promotion stage (updated every 3 month)

Custom Attribute

stage_number

The stage number where Success, Fail, Give-up, or Retry occurred.

main: 1, 2, ..., 550 (30 new stages added every month) promotion: 1, 2, ...,100

Custom Attribute

result

The result of the stage

success: Stage completed successfully fail: Stage failed giveup: Stage abandoned retry: Stage retried after failure or exit

Code example

Airflux.TrackEvent(
    // StandardCategory
    category: AirfluxCategory.ACHIEVE_LEVEL, // or "CustomEvent" (CustomCategory)
    // SemanticAttributes
    semanticAttributes: new Dictionary<string, object>(),
    // CustomAttributes
    customAttributes: new Dictionary<string, object>()
    {
        { "stage_type", "main"},
        { "stage_number", 13  },
        { "result", "success" }      
    }
);
Spend Credits

Track in-game currency spending and relevant data, such as in-game currency information, spending amount, and more.

For example, when the player spends in-game currency, such as coins and gems, call the TrackEvent() function, set the event category to AirfluxCategory.SPEND_CREDITS and add "item_type" and "item_amount" to send the in-game currency type and spending amount.

Additionally, use "stage_type" and "stage_number"to to track the stage type and stage number.

Attribute Type
Name
Semantic Attributes Description
Sample Value

Custom Attribute

item_type

The type of the in-game currency spent

coin gem

Custom Attribute

item_amount

The amount of the in-game currency spent

10, 20

Custom Attribute

stage_type

The type of the stage

main: Main stage promotion: Seasonal promotion stage (updated every 3 month)

Custom Attribute

stage_number

The current stage of the player

main: 1, 2, ~ , 550 (30 new stages added every month) promotion: 1, 2, ~ ,100

Code example

Airflux.TrackEvent(
    // StandardCategory
    category: AirfluxCategory.SPEND_CREDITS, // or "CustomEvent" (CustomCategory)
    // SemanticAttributes
    semanticAttributes: new Dictionary<string, object>(),
    // CustomAttributes
    customAttributes: new Dictionary<string, object>()
    {
        { "item_type", "coin" },
        { "item_amount", 100  },
        { "stage_type", "main"},
        { "stage_number", 13 }
    }
);

3. Send player attribute data

In addition to tracking player actions through in-game events, Airflux also requires player attribute data, such as the player’s current level, in-game currency balance, and other contextual information to train the Airflux AI model. Sufficient player attribute data allows Airflux to fine-segment players and perform inferences for maximum LTV and retention.

Use the following functions to track and pass the player attribute data to the SDK.

Player's Level Status

Use Airflux.SetLevel() to pass the player's level status to the Airflux SDK. For accurate model training, the player's level status data must be aggregated to gather sufficient contextual information.

Therefore, it is crucial to call the Airflux.SetLevel() and aggregate the player's level status every time:

  • the player opens the game

  • the player logs in to the game

  • the player's game level is updated

For new players or sign-ups, the starting level should be passed.

// Trigger in the following cases
// - when the player starts the game
// - when the player logs in
// - when the player level is updated
Airflux.SetLevel(5);
Player's Currency Status

Use Airflux.SetHardCurrency() and Airflux.SetSoftCurrency() to pass the player's hard currency (e.g., diamonds) and soft currency (e.g., coins) inventory status to the Airflux SDK.

For accurate model training, the player's currency status data must be aggregated to gather sufficient contextual information.

Therefore, it is crucial to call the Airflux.SetHardCurrency() or Airflux.SetSoftCurrency() and aggregate the player's currency status every time:

  • a player purchased, earned, or spent in-game currency

  • a player starts the game

  • a player logs in to the game

For new players or sign-ups, the game's default currency inventory status should be passed.

// Trigger when hard/soft currency balances change. Input the final balance.
// - Each currency can have up to 100 key-value pairs.
// - The attribute names must satisfy the regex ^[a-zA-Z_][a-zA-Z0-9_]*$.
// - The maximum length of attribute names is 128 characters.
Airflux.SetHardCurrency("diamond", 1000);
Airflux.SetSoftCurrency("gold", 1000);
Airflux.SetSoftCurrency("wood", 1000);
Airflux.SetSoftCurrency("coal", 1000);
Other Player Attribute

Use Airflux.SetInferenceAttribute() to pass the player's attributes other than the level and currency inventory status. Make sure to call the function whenever the attribute is updated.

// Trigger when player attributes change.
// - Attributes can have up to 100 key-value pairs.
// - Keys must satisfy the regex ^[a-zA-Z_][a-zA-Z0-9_]*$.
// - The maximum length of keys is 128 characters.
// - Values type must be string, numeric, or boolean.
// - The maximum length of string values is 1024 characters.
Airflux.SetInferenceAttribute("string", "string");
Airflux.RemoveInferenceAttribute("string");
Airflux.ClearInferenceAttributes();

4. Send User ID

If your game issues a unique User ID for each player upon sign-up or sign-in, it is advised to send the data to Airflux. If your game server does not handle User IDs, a unique identifier can be generated upon sign-in and sent to Airflux. The User ID must be sent before the event data.

// Send the User ID
Airflux.SetUserID("your_internal_user_id");

// Send the event data
Airflux.TrackEvent(
    // ... event related codes ...
);

5. Verify data transmission

Ensure the payload transmitted by the Airflux SDK adheres to the predefined event taxonomy and that the session information, in-game events, and play attribute data are sent to the Airflux server as intended.

How to verify event transmission

Trigger events based on the test scenarios listed below, and check the corresponding events in the [Raw Data]>[App Real-time Log] menu of the Airbridge dashboard. Event data transmitted through the Airflux SDK will be displayed in JSON format. You need to verify that the data type and structure of each field match the predefined format.

Taxonomy-based event and attribute format validation

Check the following items to ensure that the taxonomy definitions match the values configured in the SDK.

Field
Validation Criteria

eventData.goal.category

Verify that the event name exactly matches the string defined in the taxonomy.

semanticAttributes

• All keys must match those defined in the taxonomy. • Value types must match the defined types (string, number, boolean). • For revenue events (ad_impression, order_completed), values must be positive numbers.

originalCurrency

Must be a 3-letter uppercase code defined by ISO-4217 (e.g., USD, KRW)

customAttributes

Key: string / Value: allowed types (string, number, boolean)

Key event validation based on test scenarios

When the following key events are triggered, verify that they are properly logged in the [App Real-time Log] page without omission and that related attributes are accurately included.

Click here to view the events and key attributes that must be sent to Airflux.

Scenario
Key Event

App installed

Install

App launched

Open

Ad viewing completed

Ad Impression

In-app purchase completed

Order Completed

Level achieved

Achieve Level

Currency spent

Spend Credits

In particular, revenue-related events such as Ad Impression and Order Complete are critical for the Airflux model training. Double-check the following points:

  • Ad Impression

    • Confirm the revenue value in eventData.originalValue.

    • Confirm the currency in originalCurrency.

    • Confirm the ad type in customAttributes.adType.

  • Order Completed

    • Confirm the revenue value in eventData.originalValue.

    • Confirm the currency in originalCurrency.

If you are sending User IDs, make sure the externalUserID is properly logged.

Frequently Asked Questions

When a player completes a stage and levels up at the same time, how should I track it?

Use the TrackEvent() function to track the player's action of completing a stage as the Achieve Level event, and use the SetLevel() function to track the player's updated level as the player attribute.

Can I use the Airflux SDK to collect and send game store payment data?

No. The game store payment data must be collected and sent using the client-side SDK.

After restarting the game on iOS, the Airflux SDK stops sending events. How can I fix this?

There are two things you need to check:

  1. If AutoStartTrackingEnabled is set to false , make sure to manually call Airflux.StartTracking() every time the app launches.

  2. Make sure StartTracking() is called after application(_:didFinishLaunchingWithOptions:), the core method in the iOS app lifecycle that is executed once native initialization is complete. Calling StartTracking() too early may result in all events being dropped starting from the second launch.

For Airflux Unity SDK integration, we recommend the following approach:

  1. Create a MonoBehaviour script.

  1. Call Airflux.StartTracking() once within OnApplicationFocus(true).

  • OnApplicationFocus() is called after didBecomeActive, and therefore, the call occurs after native initialization.

  • Because OnApplicationFocus() is triggered every time the app returns to the foreground, make sure to add a flag so that StartTracking() is only called once.

Last updated