3. Send in-game event data

To enable optimal ad display and model training, it is crucial to send sufficient in-game event and player attribute data to Airflux. This guide details the core principles and implementation steps for data collection using the Airflux SDK.

---

Understanding Data Collection

Airflux collects data through three primary methods to make the most optimal ad display decisions.

Each type of data is collected at a different time and for a different purpose, so you must provide all three to maximize the performance of the AI model.

1. In-game event data

   Records user actions such as ORDER_COMPLETED and ACHIEVE_LEVEL.

2. Player Attribute Data

   Records the player's current status, such as their level or currency balance.

3. Inference Parameters

   Records contextual information at the time of an ad request, such as adType or adPlacementId.

---

1. Send in-game event data

Use the Airflux.TrackEvent() function to record key player actions within your game. The collected event data plays a crucial role in enabling the Airflux AI model to learn player behavior patterns and make optimal decisions.

Detailed Event Guide with Code Examples

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

Ad Impression

Track this event immediately after an in-app ad is shown to the user. Collect relevant data such as ad type, revenue, and placement details.

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

Name	Description	Required	Sample Value
value	The amount of ad revenue.	Required	1.99
currency	The currency code for the ad revenue (ISO 4217).	Required	“USD”
adType	The type of ad. You must use one of the pre-defined strings from the list below. • "interstitial_ad" • "rewarded_ad" • “other”	Required	“interstitial_ad”
adPlacementID	A unique identifier for the ad placement.	Required	“placement_3”
adPlacementType	The type of ad placement. You must use one of the pre-defined strings from the list below. • "static" • "dynamic"	Required	“static”
adPlacementPosition	The position of the ad placement within the game. You must use one of the pre-defined strings from the list below • "stage_start" • "stage_middle" • "stage_end" • "non_stage"	Nullable (if the placement is dynamic)	“stage_start”
level	The player's or character's current level.	Nullable (only if no level system)	10
stage	The stage number the user has played. If not in a game, this should be the last known result.	Nullable (if the game has no stages)	10
stageType	The type of stage where the user has played. If not in a game, this should be the last known result. You must use one of the pre-defined strings from the list below. • "primary_stage" • "secondary_stage" • "extra_stage"	Nullable (if the game has no stages)	"primary_stage"
totalFinishedStage	The total number of stages a player has finished. For games without stages, this should be the total play count.	Nullable (if the information is not available)	10
stageResult	The result of the most recently completed stage.If the ad placement occurs at the end of a stage or game, this should reflect the result of that stage. If the placement is in the middle of a stage/game or the user is not currently in gameplay, provide the result of the last finished stage. You must use one of the pre-defined strings from the list below. • "success" • "fail" • "giveup" • "retry" • "draw" • "exhausted"	Nullable (if the game has no stages)	"success"
adCooldownSeconds	When a cooldown is applied to an ad placement, this key-value map shows the trigger and duration of the cooldown. The key is omitted when no cooldown is applied. • interstitial_ad : Cooldown calculated from the last interstitial ad • rewarded_ad : Cooldown calculated from the last rewarded ad. • app_open : Cooldown calculated from the app open event • install : Cooldown calculated from the app install event. • other : Cooldown calculated from other events Example: If {"rewarded_ad": 120} is included, it means a 2-minute cooldown is applied from the last rewarded ad.	Nullable (if no cooldown is applied)	{"rewarded_ad":10,"interstitial_ad": 20}
rewardItems	A key-value map of items rewarded to the player. Only for rewarded ads; otherwise, null.	Nullable (if the ad has no rewards)	{"coin": 500, "gem": 10}

Code Example

Unity: C#

Airflux.TrackEvent(
    category: AirfluxCategory.AD_IMPRESSION,
    semanticAttributes: new Dictionary<string, object>
    {
        { AirfluxAttribute.VALUE, 1.99 },
        { AirfluxAttribute.CURRENCY, "USD" },
        { AirfluxAttribute.AD_TYPE, "interstitial_ad" },
        { AirfluxAttribute.AD_PLACEMENT_ID, "placement_3" },
        { AirfluxAttribute.AD_PLACEMENT_TYPE, "static" },
        { AirfluxAttribute.AD_PLACEMENT_POSITION, "stage_start" },
        { AirfluxAttribute.LEVEL, 10 },
        { AirfluxAttribute.STAGE_TYPE, "primary_stage" },
        { AirfluxAttribute.STAGE, 10 },
        { AirfluxAttribute.TOTAL_FINISHED_STAGE, 10 },
        { AirfluxAttribute.STAGE_RESULT, "success" },
        {
            AirfluxAttribute.AD_COOLDOWN_SECONDS, new Dictionary<string, object>
            {
                { "rewarded_ad", 10 },
                { "interstitial_ad", 20 }
            }
        },
        {
            AirfluxAttribute.REWARD_ITEMS, new Dictionary<string, object>
            {
                { "coin", 500 },
                { "gem", 10 }
            }
        }
     }
);

Order Completed

Track this event when an in-app purchase is completed. Collect data such as transaction ID, purchase amount, currency, and product information.

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.

Name	Description	Required	Sample Value
transactionID	A unique identifier for the transaction.	Required	TXN-20250411-5F3C9A72B1
value	The purchase amount.	Required	1.99
currency	The currency code for the purchase amount.	Required	"USD"
products	A list of the purchased products.	Required	[]
products[X].productID	The unique identifier of the purchased product.	Required	1C569KY32P1
products[X].productName	The name of the purchased product.	Required	"welcome_pack"
purchaseRoute	The purchase path. You must use one of the pre-defined strings from the list below. • "shop" • "popup" • "other"	Required	"shop"

Code Example

Unity: C#

Airflux.TrackEvent(
    category: AirfluxCategory.ORDER_COMPLETED,
    semanticAttributes: new Dictionary<string, object>
    {
        { AirfluxAttribute.TRANSACTION_ID, "TXN-20250411-5F3C9A72B1" },
        { AirfluxAttribute.VALUE, 1.99 },
        { AirfluxAttribute.CURRENCY, "USD" },
        {
            AirfluxAttribute.PRODUCTS, new List<object>
            {
                new Dictionary<string, object>
                {
                    { AirfluxAttribute.PRODUCT_ID, "1C569KY32P1" },
                    { AirfluxAttribute.PRODUCT_NAME, "welcome_pack" }
                }
            }
        },
        { AirfluxAttribute.PURCHASE_ROUTE, "shop" }
    }
);

logMessageText.GetComponent<TMP_Text>().text = "Order Completed Event Tracked";

Start Stage

Track this event when a stage or a game session begins.

Name	Description	Required	Sample Value
stageType	The type of stage where the user has played. You must use one of the pre-defined strings from the list below. • "primary_stage" • "secondary_stage" • "extra_stage"	Nullable (if the game has no stages)	"primary_stage"
stage	The stage number the user has played	Nullable (if the game has no stages)	10

Code Example

Unity: C#

Airflux.TrackEvent(
    category: AirfluxCategory.START_STAGE,
    semanticAttributes: new Dictionary<string, object>
    {
	{ AirfluxAttribute.STAGE_TYPE, "primary_stage" },
        { AirfluxAttribute.STAGE, 10 }
    }
);

Finish Stage

Track this event when a stage or game ends.

Name	Description	Required	Sample Value
stageType	The type of stage where the user has played. You must use one of the pre-defined strings from the list below. • "primary_stage" • "secondary_stage" • "extra_stage"	Nullable (if the game has no stages)	"primary_stage"
stage	The stage number the user has played	Nullable (if the game has no stages)	10
totalFinishedStage	The total number of stages a player has finished. For games without stages, this should be the total play count.	Nullable (if the game has no stages)	10
stageResult	The result of the most recently completed stage. If the ad placement occurs at the end of a stage or game, this should reflect the result of that stage. If the placement is in the middle of a stage/game or the user is not currently in gameplay, provide the result of the last finished stage. You must use one of the pre-defined strings from the list below. • "success" • "fail" • "giveup" • "retry" • "draw" • "exhausted"	Nullable (if the game has no stages)	"success"

Code Example

Unity: C#

Airflux.TrackEvent(
    category: AirfluxCategory.FINISH_STAGE,
    semanticAttributes: new Dictionary<string, object>
    {
        { AirfluxAttribute.STAGE_TYPE, "primary_stage" },
        { AirfluxAttribute.STAGE, 10 },
        { AirfluxAttribute.TOTAL_FINISHED_STAGE, 10 },
        { AirfluxAttribute.STAGE_RESULT, "success" }
    }
);

Achieve Level

Track this event when a player's or character's level changes, including when it decreases. This event can be omitted for games without a level system.

Name	Description	Required	Sample Value
level	The player's or character's current level.	Nullable (only if no level system)	10

Code Example

Unity: C#

Airflux.TrackEvent(
    category: AirfluxCategory.ACHIEVE_LEVEL,
    semanticAttributes: new Dictionary<string, object>
    {
        { AirfluxAttribute.LEVEL, 10 }
    }
);

Verification

Using the App Real-Time Log

Trigger events based on your test scenarios and check the corresponding logs in the [Raw Data] > [App Real-time Log] menu. The event data will be displayed in JSON format, allowing you to confirm that the data type and structure of each field match the predefined format.

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)

---

2. Send player attribute data

Player attribute data provides a crucial snapshot of a player's status at a given time. This data is used to fine-tune player segmentation and personalize ad experiences. There are two primary functions for sending this data: Airflux.SetUser() and Airflux.SetContext().

Player attribute data is only transmitted to the server when an event is tracked or an inference API is called. Ensure this data is set before making any inference API requests.

Send User ID

Send the player's unique User ID when they sign up or sign in. This ensures all subsequent events and attributes are properly linked to that user. The User ID must be sent before the event data.

Send User ID

When to trigger

• When a player signs up or signs in.

Name	Description	Example
ID	The player’s unique User ID	"your_internal_user_id"

If the User ID is not sent before the event data, the User ID cannot be linked to the event data.

Code Examples

Unity: C#

Airflux.SetUser(AirfluxUser.ID, "your_internal_user_id");

Send Contextual Data

Airflux.SetContext() is used to pass player attributes that are not tied to a specific event. This is crucial for providing the AI model with a complete snapshot of the player's status, such as their current level or currency balance at app launch.

Level Attributes

When to trigger

• When the game app opens

• When the player logs in

Name	Description	Example	Skip Case
Level	The player's or character's current level.	10	If the game has no levels

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

Code Example

Unity: C#

Airflux.SetContext(AirfluxContext.LEVEL, 10);

Stage Attributes

When to Trigger

• When the game app opens.

• When a player logs in.

Name	Description	Example	Skip Case
START_STAGE	The last stage the player started.	10	If the game has no stages
FINISH_STAGE	The last stage the player finished.	10	If the game has no stages
TOTAL_FINISHED_STAGE	The total number of stages a player has finished. For games without stages, this should be the total play count.	10	If information is not available

Code Example

Unity: C#

Airflux.SetContext(AirfluxContext.START_STAGE, 10);
Airflux.SetContext(AirfluxContext.FINISH_STAGE, 10);
Airflux.SetContext(AirfluxContext.TOTAL_FINISHED_STAGE, 10);

Other Attributes

When to Trigger

When other custom game attributes are updated.

Note

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

Name	Description	Example	Skip Case
Attribute	A key-value map for other custom attributes and game information.	"battlePass", "premium”	If not needed

Code Examples

Unity: C#

Airflux.SetContext(AirfluxContext.ATTRIBUTE, "battlePass", "premium");

---

Frequently Asked Questions

How should I use the category, semanticAttributes, and customAttributes parameters for event data collection?

Name	Type	Description
category	String	The event's unique name (e.g., AD_IMPRESSION). 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.

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, the Airflux SDK stops sending events. How can I fix this?

The Airflux SDK automatically tracks app lifecycle events, so you do not need to manually call StartTracking(). This issue typically occurs if the SDK is disabled, either by:

1. Setting SDK Enabled in the SDK initialization options.

2. Calling the Airflux.DisableSDK() function during runtime.

When the SDK is disabled, both event tracking and inference requests are halted. To resolve this, you must explicitly call Airflux.EnableSDK() to re-activate the SDK's features.