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.

In-game event data
Records user actions such as ORDER_COMPLETED and ACHIEVE_LEVEL.
Player Attribute Data
Records the player's current status, such as their level or currency balance.
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 stage number 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

iOS: Swift

import Airflux

Airflux.trackEvent(
    category: AirfluxCategory.AD_IMPRESSION,
    semanticAttributes: [
        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: [
            "rewarded_ad": 10,
            "interstitial_ad": 20
        ],
        AirfluxAttribute.REWARD_ITEMS: [
            "coin": 500,
            "gem": 10
        ]
    ]
)

iOS: Objective-C

#import <Airflux/Airflux.h>

[Airflux trackEventWithCategory:AirfluxCategory.AD_IMPRESSION semanticAttributes:@{
    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: @{
        @"rewarded_ad": @(10),
        @"interstitial_ad": @(20)
    },
    AirfluxAttribute.REWARD_ITEMS: @{
        @"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

iOS: Swift

import Airflux

Airflux.trackEvent(
    category: AirfluxCategory.ORDER_COMPLETED,
    semanticAttributes: [
        AirfluxAttribute.TRANSACTION_ID: "TXN-20250411-5F3C9A72B1",
        AirfluxAttribute.VALUE: 1.99,
        AirfluxAttribute.CURRENCY: "USD",
        AirfluxAttribute.PRODUCTS: [
            [
                AirfluxAttribute.PRODUCT_ID: "1C569KY32P1",
                AirfluxAttribute.PRODUCT_NAME: "welcome_pack"
            ]
        ],
        AirfluxAttribute.PURCHASE_ROUTE: "shop"
    ]
)

iOS: Objective-C

#import <Airflux/Airflux.h>

[Airflux trackEventWithCategory:AirfluxCategory.ORDER_COMPLETED semanticAttributes:@{
    AirfluxAttribute.TRANSACTION_ID: @"TXN-20250411-5F3C9A72B1",
    AirfluxAttribute.VALUE: @(1.99),
    AirfluxAttribute.CURRENCY: @"USD",
    AirfluxAttribute.PRODUCTS: @[
        @{
            AirfluxAttribute.PRODUCT_ID: @"1C569KY32P1",
            AirfluxAttribute.PRODUCT_NAME: @"welcome_pack"
        }
    ],
    AirfluxAttribute.PURCHASE_ROUTE: @"shop"
}];

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

iOS: Swift

import Airflux

Airflux.trackEvent(
    category: AirfluxCategory.START_STAGE,
    semanticAttributes: [
        AirfluxAttribute.STAGE_TYPE: "primary_stage",
        AirfluxAttribute.STAGE: 10
    ]
)

iOS: Objective-C

#import <Airflux/Airflux.h>

[Airflux trackEventWithCategory:AirfluxCategory.START_STAGE semanticAttributes:@{
    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

iOS: Swift

import Airflux

Airflux.trackEvent(
    category: AirfluxCategory.FINISH_STAGE,
    semanticAttributes: [
        AirfluxAttribute.STAGE_TYPE: "primary_stage",
        AirfluxAttribute.STAGE: 10,
        AirfluxAttribute.TOTAL_FINISHED_STAGE: 10,
        AirfluxAttribute.STAGE_RESULT: "success"
    ]
)

iOS: Objective-C

#import <Airflux/Airflux.h>

[Airflux trackEventWithCategory:AirfluxCategory.FINISH_STAGE semanticAttributes:@{
    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

iOS: Swift

import Airflux

Airflux.trackEvent(
    category: AirfluxCategory.ACHIEVE_LEVEL,
    semanticAttributes: [
        AirfluxAttribute.LEVEL: 10
    ]
)

iOS: Objective-C

#import <Airflux/Airflux.h>

[Airflux trackEventWithCategory:AirfluxCategory.ACHIEVE_LEVEL semanticAttributes:@{
    AirfluxAttribute.LEVEL: @(10)
}];

Spend Credits

Track this event when a player spends in-game currency. This event can be omitted for games without a currency system.

Name

Description

Required

Sample Value

creditClass

The class of the currency spent. You must use either "hard" (paid currency) or "soft" (free currency).

Nullable (if the game has no in-game currency)

"hard"

creditType

The type of currency spent (e.g., "coin", "gem").

Nullable (if the game has no in-game currency)

"coin"

creditSpent

The amount of currency spent.

Nullable (if the game has no in-game currency)

creditCurrent

The amount of currency remaining after the spend.

Nullable (if the game has no in-game currency)

990

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"

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)

Code Example

iOS: Swift

import Airflux

Airflux.trackEvent(
    category: AirfluxCategory.SPEND_CREDITS,
    semanticAttributes: [
        AirfluxAttribute.CREDIT_CLASS: "hard",
        AirfluxAttribute.CREDIT_TYPE: "coin",
        AirfluxAttribute.CREDIT_SPENT: 10,
        AirfluxAttribute.CREDIT_CURRENT: 990,
        AirfluxAttribute.STAGE_TYPE: "primary_stage",
        AirfluxAttribute.STAGE: 10
    ]
)

iOS: Objective-C

#import <Airflux/Airflux.h>

[Airflux trackEventWithCategory:AirfluxCategory.SPEND_CREDITS semanticAttributes:@{
    AirfluxAttribute.CREDIT_CLASS: @"hard",
    AirfluxAttribute.CREDIT_TYPE: @"coin",
    AirfluxAttribute.CREDIT_SPENT: @(10),
    AirfluxAttribute.CREDIT_CURRENT: @(990),
    AirfluxAttribute.STAGE_TYPE: @"primary_stage",
    AirfluxAttribute.STAGE: @(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

iOS: Swift

import Airflux

// Call when a player signs in
Airflux.setUser(AirfluxUser.ID, value: "your_internal_user_id")

iOS: Objective-C

#import <Airflux/Airflux.h>

[Airflux setUser:AirfluxUser.ID value:@"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

iOS: Swift

import Airflux

Airflux.setContext(AirfluxContext.LEVEL, value: 10)

iOS: Objective-C

#import <Airflux/Airflux.h>

[Airflux setContext:AirfluxContext.LEVEL value:@(10)];

Currency Attributes

When to trigger

When the game app opens.
When a player logs in.
When a player's currency balance changes.

Note

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

Name

Description

Example

Skip Case

HARD_CURRENCY

A key-value map of hard currency types and their current balances.

"gem", 500

If the game has no in-game currency

SOFT_CURRENCY

A key-value map of soft currency types and their current balances.

"coin", 1000

If the game has no in-game currency

Code Example

iOS: Swift

import Airflux

Airflux.setContext(AirfluxContext.HARD_CURRENCY, key: "gem", value: 500)
Airflux.setContext(AirfluxContext.SOFT_CURRENCY, key: "coin", value: 1000)

iOS: Objective-C

#import <Airflux/Airflux.h>

[Airflux setContext:AirfluxContext.HARD_CURRENCY key:@"gem" value:@(500)];
[Airflux setContext:AirfluxContext.SOFT_CURRENCY key:@"coin" value:@(1000)];

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

iOS: Swift

import Airflux

Airflux.setContext(AirfluxContext.START_STAGE, value: 10)
Airflux.setContext(AirfluxContext.FINISH_STAGE, value: 10)
Airflux.setContext(AirfluxContext.TOTAL_FINISHED_STAGE, value: 10)

iOS: Objective-C

#import <Airflux/Airflux.h>

[Airflux setContext:AirfluxContext.START_STAGE value:@(10)];
[Airflux setContext:AirfluxContext.FINISH_STAGE value:@(10)];
[Airflux setContext:AirfluxContext.TOTAL_FINISHED_STAGE value:@(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

iOS: Swift

import Airflux

Airflux.setContext(AirfluxContext.ATTRIBUTE, key: "battlePass", value: "premium")

iOS: Objective-C

#import <Airflux/Airflux.h>

[Airflux setContext:AirfluxContext.ATTRIBUTE key:@"battlePass" value:@"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?

Airflux Native SDK v1.0 Guide: The Airflux Native 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:

Setting setSDKEnabled(false) in the SDK initialization options.
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.

Previous2. Install the Airflux SDK Next4. Call the Inference API

Last updated 1 hour ago