4. Call the Inference API

Configure the Airflux SDK to request an inference decision before displaying an interstitial ad. Based on the AI's response, you can decide whether to proceed with showing the ad. This process allows for smarter, more revenue-optimized ad delivery.

---

1. Set up the API Call and callbacks

Use the Airflux.requestInference() function with the SHOW_INTERSTITIAL_AD method to request a real-time ad decision. To ensure the AI makes an accurate decision, you must provide detailed contextual parameters and implement the appropriate callbacks.

Step 1 : Set Inference Parameters

To make an accurate decision, Airflux requires detailed contextual parameters related to the player state, ad type, and placement. These must be passed into the function via the parameters object using AirfluxParameter.* keys.

Important

All required fields must always be collected, and nullable fields should also be collected whenever available. Failure to provide these values may reduce optimization performance and lead to skewed experimental results.

Name	Description	Type	Required	Sample Value
currency	The currency code for the ad revenue.(ISO 4217)	string	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”	string	Required	“interstitial_ad”
adPlacementID	A unique identifier for the ad placement.	string	Required	“placement_3”
adPlacementType	The type of ad placement. You must use one of the pre-defined strings from the list below. • "static" • "dynamic"	string	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"	string	Nullable (if the placement is dynamic)	“stage_start"
level	The player's or character's current level.	int	Nullable (only if no level system)	10
stage	The stage number where the ad was presented. If not in a game, this should be the last known result.	int	Nullable (if the game has no stages)	10
stageType	The type of stage where the ad was presented. 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"	string	Nullable (if the game has no stages)	"primary_stage"
totalFinishedStage	Number of stages played so far (or play count if the game has no stages)	int	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"	string	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.	map<string, int>	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.	map<string, int>	Nullable (if the ad has no rewards)	{ "coin": 500, "gem": 10 }

Step 2 : Implement the Ad Display Logic

Once the inference request is sent, the SDK will trigger one of the following callbacks. You must implement the appropriate logic in each case to ensure a smooth player experience and stable ad revenue.

Name	Description	What your app should do	Required
onShowAd	Triggered when the API determines the ad must be shown.	Display the interstitial ad.	Required
onSkipAd	Triggered when the API determines the ad must be skipped. Continue gameplay without showing ads.	Skip the ad and continue gameplay seamlessly.	Required
onDefaultAdPolicy	Triggered when the ad serving should not be decided by the Airflux policy. You must implement your internal logic to decide whether to show or skip the ad.	Apply your internal ad policy logic and proceed accordingly.	Required
onFailure	Triggered when the inference request fails. This may happen if: • The player's country is not supported (not in countryAllowlist) • The server returns a 4XX or 5XX error • The request times out after 3 seconds	Use your fallback logic to decide whether to show or skip the ad. Retry is not required.	Required

Timeout and Fallback Recommendation

Failure to handle the inference request properly may lead to degraded play experience and loss of ad revenue. To minimize potential negative effects, it is recommended to set a 3-second (default) timeout and implement onFailure code in case the API call fails. Retry attempts upon function call failure are not required. In this case, your internal ad display logic should be included within the onFailure block.

Code Example

Android: Kotlin

import ai.airflux.Airflux
import ai.airflux.AirfluxInference
import ai.airflux.AirfluxParameter
import android.util.Log

Airflux.requestInference(
    inference = AirfluxInference.SHOW_INTERSTITIAL_AD(
        parameters = mapOf(
            AirfluxParameter.AD_TYPE to "interstitial_ad",
	    AirfluxParameter.AD_PLACEMENT_ID to "placement_3", 
            AirfluxParameter.AD_PLACEMENT_TYPE to "static",
            AirfluxParameter.AD_PLACEMENT_POSITION to "stage_start", 
            AirfluxParameter.STAGE to 10,
            AirfluxParameter.STAGE_TYPE to "primary_stage",
            AirfluxParameter.TOTAL_FINISHED_STAGE to 10, 
            AirfluxParameter.STAGE_RESULT to "success",
            AirfluxParameter.AD_COOLDOWN_SECONDS to mapOf( 
                "rewarded_ad" to 10,
                "interstitial_ad" to 20
            ),
            AirfluxParameter.REWARD_ITEMS to mapOf( 
                "coin" to 500,
                "gem" to 10
            ),
            AirfluxParameter.FORCE_RESPONSE to mapOf( 
                "action" to "showAd",
                "parameters" to mapOf<String, Any>() 
            )
        ),
        onShowAd = {
            // AI determined to show the ad. Implement your logic here.
            Log.d("Airflux", "AI decided to show ad.")
            // Your function to display the interstitial ad
        },
        onSkipAd = {
            // AI determined to skip the ad. Implement your logic here.
            Log.d("Airflux", "AI decided to skip ad.")
            // Your function to continue gameplay without showing ads
        },
        onDefaultAdPolicy = {
            // Implement your internal logic to decide whether to show or skip the ad.
            Log.d("Airflux", "AI returned default policy. Implementing internal logic.")
            // Your function for default ad decision logic
        },
        onFailure = { error ->
            // Inference request failed. Implement your internal logic to handle the error
            // and decide whether to show or skip the ad based on your game's policy.
            Log.e("Airflux", "Inference request failed: ${error.message}. Falling back to default policy.")
            // Your function for default ad decision logic on error
        }
    )
)

Android: Java

Verification

Testing with Force responses

Ensure that your app correctly calls the inference API at each interstitial placement and follows the returned decision reliably.

What to test

1. The inference request includes all required parameters.

2. Exactly one of the decision callbacks is triggered per request.

Testing with Force responses

To simulate various responses during development or QA, you can use the AirfluxParameter.FORCE_RESPONSE parameter in your inference request:

It’s recommended to implement handling for all four cases to ensure consistent ad delivery across various environments and edge cases.

Simulated value	Callback triggered	Purpose	Expected Behavior
“showAd”	onShowAd()	Test ad display flow	Ad is displayed to the player
“skipAd”	onSkipAd()	Test ad skip behavior	Ad is skipped and gameplay resumes
“defaultAdPolicy”	onDefaultAdPolicy()	Test your ad decision logic	Your ad decision logic is executed
“failure”	onFailure(error)	Test fallback handling for failure scenarios	Custom policy determines ad display

[AirfluxParameter.FORCE_RESPONSE]: {
    "action": "showAd",
    "parameters": {}
}

The FORCE_RESPONSE parameter is intended for testing purposes only and must be removed from production builds. If left active, it may cause ads to be always shown or always skipped, regardless of actual inference decisions.

Code Example

Android: Kotlin

AirfluxParameter.FORCE_RESPONSE to mapOf(
    "action" to "showAd",
    "parameters" to mapOf<String, Any>()
)

Android: Java

put(AirfluxParameter.FORCE_RESPONSE, new HashMap<String, Object>() {{
    put("action", "showAd");
    put("parameters", new HashMap<String, Object>());
}});

---

2. Deploy the app

After completing sufficient QA and crash testing, deploy your gaming app. To ensure proper integration with Airflux, make sure the deployment follows the timeline coordinated with the Growth Manager.

Where can I get guidance for the app store review?

Click here for guidance on preparing for the Google Play and App Store reviews.

---

Next steps

Congratulations! If you have completed the steps above, you are all set to optimize your in-game advertising with Airflux. Click here to learn how to receive your optimization results.

---

Frequently Asked Questions

What is the difference between onSkipAd() and onFailure() callbacks?

• The onSkipAd() callback function is triggered when the API call is successful, and the inference result from the Airflux AI model indicates that an ad should not be displayed to enhance the play experience and maximize ad revenue.

• The onFailure() callback function is triggered when the API call fails. This includes situations such as the device's country not being in the allowlist (countryAllowlist), network issues, server errors, or request validation failures, where no response is received.

What is the response time of the API by country?

Airflux aims to deliver reliable service to users worldwide and typically maintains quick response times in most regions. However, minor delays may arise based on the network environment.