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.

Unity

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

Collecting and sending the event data specified in the Required event data for Airflux integration to Airflux is essential for using Airflux.

Unity

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

In-game events are essential data for model training. Clearly understand the purpose and timing of collecting each event, and ensure proper implementation for data transmission.

Ad Impression (IAA-related event)

Attention

The in-app ad revenue data must be collected using the client-side SDK through mediation platform integrations and sent to Airflux.

Track ad impressions when ad is shown to the player and collect relevant data, such as ad type, ad revenue, placement, and more.

For example, when ad revenue is generated after an interstitial ad is shown, call the TrackEvent() function, set the event category to AirfluxCategory.AD_IMPRESSION, and add "adType" to customAttributes to send interstitial as a value.

Attribute Type	Name	Semantic Attributes Description	Sample Value
Semantic Attribute	Currency	Currency for ad revenue	USD
Semantic Attribute	Value	Ad revenue amount	1.99
Custom Attribute	adType	The type of the ad	reward: Rewarded ad interstitial: Interstitial ad banner: Banner ad
Custom Attribute	ad_placement	Ad placement	rw_offline: Offline reward ad rw_get_item: Rewarded ad for obtaining items like weapons, skins, etc. rw_get_coin: Rewarded ad for earning coins rw_get_gem: Rewarded ad for earning gems rw_time_skip: Rewarded ad for reducing recovery time int_next_stage: Interstitial ad that is presented when advancing to the next stage bn_next_stage: Banner ad that is presented when advancing to the next stage
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 interstitial or rewarded ads are presented after Success, Fail, Give-up, or Retry. Otherwise, null is collected.	main: 1, 2, ..., 550 (30 new stages added every month) promotion: 1, 2, ...,100
Custom Attribute	reward_item	The reward earned by the player after engaging with a rewarded ad. For other ad types, null is collected.	coin: Number of coins earned gem: Number of gems earned

Code example

// Example: Ad revenue transmission from AdMob
Airflux.TrackEvent(
    category: AirfluxCategory.AD_IMPRESSION,
    semanticAttributes: new Dictionary<string, object>()
    {
        { AirfluxAttribute.VALUE, 0.01 }, // Required: Ad revenue
        { AirfluxAttribute.CURRENCY, "USD" }, // Required: Currency code
        {
            AirfluxAttribute.AD_PARTNERS, new Dictionary<string, object>()
            {
                {
                    "mopub", new Dictionary<string, object>()
                    {
                        { "app_version", "5.18.0" },
                        { "adunit_id", "12345" },
                        { "adunit_name", "12345" },
                        { "adunit_format", "Banner" },
                        { "id", "12345" },
                        { "currency", "USD" },
                        { "publisher_revenue", 12345.123 },
                        { "adgroup_id", "12345" },
                        { "adgroup_name", "12345" },
                        { "adgroup_type", "12345" },
                        { "adgroup_priority", "12345" },
                        { "country", "kr" },
                        { "precision", "publisher_defined" },
                        { "network_name", "12345" },
                        { "network_placement_id", "12345" },
                        { "demand_partner_data", "12345" },
                    }
                }
            }
        },
    },
    customAttributes: new Dictionary<string, object>()
    {
        { "adType", "reward" }, // Ad type (reward, interstitial 등)
        { "ad_placement", "main_banner" }, // Ad placement (SDK 설치 완료 후 ad_context 값에 따른 상세 설명 필요)
        { "stage_type", "Main" }, // Main or promotional stage (Main, Event 등)
        { "stage_number", "1" }, // The stage number where interstitial or rewarded ads are shown after Success, Fail, Give-up, or Retry. Otherwise, null is collected. 
        { "reward_item", new Dictionary<string, object> {{"coin", 10}, {"gem", 20}} } // The reward earned by the player after engaging with a rewarded ad. For other ad types, null is collected.
    }
);

Order Completed (IAP-related event)

Attention

The in-app purchase revenue data must be collected using the client-side SDK and sent to Airflux. There might be a slight gap between the data sent to Airflux and the revenue data provided by vendors.

Track in-app purchases and relevant data such as item information, transaction ID, the purchased amount, the payment currency, and more.

For example, when a dialog is prompted confirming a purchase of an item, call the TrackEvent() function, set the event category to AirfluxCategory.ORDER_COMPLETED, and add AirfluxAttribute.PRODUCT_ID and AirfluxAttribute.PRODUCT_NAME to send information of the purchase item.

The payment currency information (AirfluxAttribute.CURRENCY )and the purchase amount (AirfluxAttribute.VALUE) must be included in the event data for accurate revenue analysis.

Attribute Type	Name	Semantic Attributes Description	Sample Value
Semantic Attribute	Transaction ID	Transaction ID	TXN-20250411-5F3C9A72B1
Semantic Attribute	Currency	Currency for ad revenue	USD
Semantic Attribute	Value	Ad revenue amount	10.99
Semantic Attribute	Product ID	Product ID	1C569KY32P1
Semantic Attribute	Product Name	Product Name	remove_ads: ""Ad Removal"" as a purchase item welcome_pack: Item package for newly acquired players starter_pack: Item package for beginners coin_pack_1: Coin package gem_pack_2: Gem package limited_skin_1: Time-limited skin
Custom Attribute	purchase_route	The source of the purchase	shop: Purchased from the shop popup: Purchased from a pop-up

Code example

Airflux.TrackEvent(
    // StandardCategory
    category: AirfluxCategory.ORDER_COMPLETED, // or "CustomEvent" (CustomCategory)
    // SemanticAttributes
    semanticAttributes: new Dictionary<string, object>()
    {
        { AirfluxAttribute.VALUE, 11 }, // Required: Actual purchase amount
        { AirfluxAttribute.TRANSACTION_ID, "8065ef16-162b-4a82-b683-e51aefdda7d5" }, // Required: Transaction ID
        { AirfluxAttribute.CURRENCY, "USD" }, // Required: Currency code 
        {
            AirfluxAttribute.PRODUCTS, new List<object>()
            {
                new Dictionary<string, object>()
                {
                    { AirfluxAttribute.PRODUCT_ID, "1C569KY32P1" }, // Required, Product ID
                    { AirfluxAttribute.PRODUCT_NAME, "remove_ads" } // Required, Product name (welcome_back, remove_ads, starter_pack ...)
                } 
            }
        }
    },
    // CustomAttributes
    customAttributes: new Dictionary<string, object>()
    {
        { "purchase_route", "shop" } // (Optional) shop / popup
    }

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.

Attention

The player attribute data must be passed to the SDK before the inference API request.

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

Attention

Input the in-game currency balance for Currency . If a player had 500 diamonds and purchased 700 more, Airflux.SetHardCurrency("diamond", 1200) should be triggered.

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.

Unity

Attention

If the User ID is not sent before the event data, the User ID cannot be linked to 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.