Unity v0.x → v1.0 Migration Guide

Airflux Unity SDK v1.0 introduces a redesigned API surface and updated data taxonomy for more accurate event/context aggregation and inference decisions. This guide explains how to migrate an existing Unity v0.x (including v0.1) integration to v1.0 safely.

Deprecated: Unity v0.x is a legacy integration. New integrations should use the Airflux Integration (Unity) guide.

---

Important notes before you migrate

Attention: Breaking change Airflux Unity SDK v1.0 is not backward-compatible with v0.x.

• You must update your code to the new APIs and taxonomy.

• You must not keep v0.x and v1.0 installed in the same Unity project.

Attention: Data reset When upgrading to v1.0, existing on-device Airflux data (stored context, counters, and any pending SDK data) should be treated as reset. Plan your QA and roll-out assuming a clean slate for v1.0 devices.

Migration checklist

• Remove Airflux Unity SDK v0.x from the project

• Import Airflux Unity SDK v1.0 and reconfigure Airflux Settings

• Remove legacy session tracking calls (NotifyAppForeground/NotifyAppBackground)

• Replace v0.x APIs with v1.0 APIs (SetUser, SetContext, RequestInference)

• Update event taxonomy (especially stage and ad impression tracking)

• Verify logs, event payloads, and inference callback handling

• Run QA on Android & iOS builds and deploy

---

1. Update the SDK package

1.1 Remove Airflux Unity SDK v0.x

1. In your Unity project, delete the existing Airflux v0.x SDK files (for example, the old Assets/Airflux folder and any related plugin files).

2. Confirm there is no remaining v0.x assembly or duplicated Airflux code in:

   • Assets/Plugins/Android

   • Assets/Plugins/iOS

   • Assets/ (any legacy Airflux folders)

Attention Importing v1.0 without fully removing v0.x can cause compilation conflicts and duplicated classes.

1.2 Install Airflux Unity SDK v1.0

1. Download the latest Airflux Unity SDK v1.0 .unitypackage. (link)

2. Import it via Assets → Import Package → Custom Package…

3. After import, open Airflux → Airflux Settings and configure:

   • App Name (required)

   • App Token (required)

   • SDK Enabled / Auto Start Tracking Enabled (optional, depending on consent flow)

   • Allow Every Country Enabled / Country Allowlist (optional but strongly recommended to confirm)

   • Log Level (recommend debug during QA)

   • Session Timeout (default 300 seconds)

These options are available in the v1.0 initialization settings.

---

2. Remove legacy session tracking (v0.x → v1.0)

In Unity v0.x, you typically implemented session tracking manually by calling NotifyAppForeground() / NotifyAppBackground() on app lifecycle callbacks.

In v1.0, the SDK automatically tracks app lifecycle events, so you do not need this manual wiring.

What to change

Before (v0.x)

using UnityEngine;

public class AirfluxBehaviour : MonoBehaviour
{
    void OnApplicationPause(bool pauseStatus)
    {
        if (pauseStatus)
        {
            Airflux.NotifyAppBackground();
        }
        else
        {
            Airflux.NotifyAppForeground();
        }
    }
}

After (v1.0) Remove the NotifyAppForeground/NotifyAppBackground calls entirely.

using UnityEngine;

public class AirfluxBehaviour : MonoBehaviour
{
    void OnApplicationPause(bool pauseStatus)
    {
        // No manual Airflux session tracking required in v1.0
    }
}

---

3. Migrate player attribute APIs (User & Context)

v1.0 consolidates “player attribute data” into:

• User: Airflux.SetUser(...)

• Context: Airflux.SetContext(...)

(These values are transmitted when you track an event or request an inference—set them before calling inference or tracking key events.)

3.1 API mapping (v0.x → v1.0)

What you were doing	v0.x API	v1.0 API
Set User ID	SetUserID(id)	SetUser(AirfluxUser.ID, id)
Clear User ID	ClearUserID()	ClearUser(AirfluxUser.ID)
Set Level	SetLevel(level)	SetContext(AirfluxContext.LEVEL, level)
Set Hard Currency	SetHardCurrency(name, balance)	SetContext(AirfluxContext.HARD_CURRENCY, name, balance)
Set Soft Currency	SetSoftCurrency(name, balance)	SetContext(AirfluxContext.SOFT_CURRENCY, name, balance)
Set “inference attributes” / custom state	SetInferenceAttribute(key, value)	SetContext(AirfluxContext.ATTRIBUTE, key, value)

Attention In v1.0, “inference attributes” are modeled as a context category (AirfluxContext.ATTRIBUTE). If you used SetInferenceAttribute(...) in v0.x for things like battlePass, migrate them to SetContext(AirfluxContext.ATTRIBUTE, ...).

3.2 Example: User ID

Before (v0.x)

Airflux.SetUserID("your_user_id");

After (v1.0)

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

3.3 Example: Level & Currency

After (v1.0)

// Level
Airflux.SetContext(AirfluxContext.LEVEL, 10);

// Currency
Airflux.SetContext(AirfluxContext.HARD_CURRENCY, "gem", 500);
Airflux.SetContext(AirfluxContext.SOFT_CURRENCY, "gold", 54000);

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

---

4. Update event tracking (taxonomy changes)

The TrackEvent(category, semanticAttributes, customAttributes) signature remains conceptually the same, but what you put into semantic vs custom attributes—and which events you should send—has changed in v1.0.

Below are the most important migration points.

Important: It is essential to consult the Airflux Integration (Unity) section regarding all required fields.

4.1 Ad Impression: move adType and key fields into semantic attributes

In v0.x, adType was sent as a custom attribute (e.g., customAttributes.adType).

In v1.0, AD_TYPE, AD_PLACEMENT_*, STAGE_*, etc. are tracked as semantic attributes using AirfluxAttribute.*.

After (v1.0) example

Airflux.TrackEvent(
    category: AirfluxCategory.AD_IMPRESSION,
    semanticAttributes: new Dictionary<string, object>
    {
        { AirfluxAttribute.VALUE, 0.025 },
        { AirfluxAttribute.CURRENCY, "USD" },

        // moved into semantic attributes in v1.0
        { AirfluxAttribute.AD_TYPE, "rewarded_ad" },              // or "interstitial_ad"
        { AirfluxAttribute.AD_PLACEMENT_ID, "stage_clear_reward" },

        // collect if available
        { AirfluxAttribute.STAGE_TYPE, "primary_stage" },
        { AirfluxAttribute.STAGE, 15 },
    }
);

Attention: Allowed values changed v1.0 requires pre-defined strings for many fields (e.g., adType, stageType, stageResult). Make sure your old values are mapped to the v1.0 allowed set.

4.2 Stage tracking: replace “stage end via ACHIEVE_LEVEL” with START_STAGE / FINISH_STAGE

In v0.x, some integrations used ACHIEVE_LEVEL to represent stage completion (with stage info and result). In v1.0, stage progression is tracked explicitly with:

• START_STAGE

• FINISH_STAGE

And ACHIEVE_LEVEL is used for actual level progression (if your game has a level system).

After (v1.0) examples

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

// Stage finish
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" } // success/fail/giveup/retry/draw/exhausted
    }
);

4.3 Spend Credits: use CREDIT_* fields

v1.0 standardizes currency spending into SPEND_CREDITS with semantic attributes:

Airflux.TrackEvent(
    category: AirfluxCategory.SPEND_CREDITS,
    semanticAttributes: new Dictionary<string, object>
    {
        { AirfluxAttribute.CREDIT_CLASS, "hard" },    // "hard" or "soft"
        { AirfluxAttribute.CREDIT_TYPE, "coin" },
        { AirfluxAttribute.CREDIT_SPENT, 10 },
        { AirfluxAttribute.CREDIT_CURRENT, 990 },

        // stage info if available
        { AirfluxAttribute.STAGE_TYPE, "primary_stage" },
        { AirfluxAttribute.STAGE, 10 }
    }
);

4.4 Order Completed: send product list and purchase route

v1.0 expects PRODUCTS as a list, along with TRANSACTION_ID, VALUE, CURRENCY, and PURCHASE_ROUTE.

Airflux.TrackEvent(
    category: AirfluxCategory.ORDER_COMPLETED,
    semanticAttributes: new Dictionary<string, object>
    {
        { AirfluxAttribute.TRANSACTION_ID, "TXN-20250411-0001" },
        { AirfluxAttribute.VALUE, 4.99 },
        { AirfluxAttribute.CURRENCY, "USD" },
        {
            AirfluxAttribute.PRODUCTS, new List<object>
            {
                new Dictionary<string, object>
                {
                    { AirfluxAttribute.PRODUCT_ID, "welcome_pack" },
                    { AirfluxAttribute.PRODUCT_NAME, "Welcome Pack" }
                }
            }
        },
        { AirfluxAttribute.PURCHASE_ROUTE, "shop" } // shop/popup/other
    }
);

---

5. Migrate the Inference API call (Interstitial decision)

5.1 What changed

v0.x

• You set placement context via setInferenceAttributes()

• You called InferenceShowAdInterstitial(onShowAd, onSkipAd, onFailure)

v1.0

• You call Airflux.RequestInference(...) with AirfluxInference.SHOW_INTERSTITIAL_AD(...)

• You pass inference-time parameters via AirfluxParameter.*

• You must implement four callbacks:

  • onShowAd

  • onSkipAd

  • onDefaultAdPolicy

  • onFailure

Important v1.0 requires you to include all required inference parameters, and include nullable parameters whenever available.

5.2 v1.0 example (recommended pattern)

public void TryShowInterstitial()
{
    var parameters = new Dictionary<string, object>
    {
        // Required
        { AirfluxParameter.AD_TYPE, "interstitial_ad" },
        { AirfluxParameter.AD_PLACEMENT_ID, "end_of_stage_ad" },
        { AirfluxParameter.AD_PLACEMENT_TYPE, "static" },

        // Nullable (collect if available)
        { AirfluxParameter.AD_PLACEMENT_POSITION, "stage_end" },
        { AirfluxParameter.STAGE_TYPE, "primary_stage" },
        { AirfluxParameter.STAGE, 15 },
        { AirfluxParameter.STAGE_RESULT, "success" },
        { AirfluxParameter.TOTAL_FINISHED_STAGE, 42 },
        { AirfluxParameter.LEVEL, 10 }
    };

    Airflux.RequestInference(
        AirfluxInference.SHOW_INTERSTITIAL_AD(
            parameters: parameters,
            onShowAd: () =>
            {
                // AI decided to show the interstitial ad.
                ShowInterstitial();
            },
            onSkipAd: () =>
            {
                // AI decided to skip the ad.
                ContinueGameplay();
            },
            onDefaultAdPolicy: () =>
            {
                // AI requests your internal policy decision.
                ApplyMyDefaultAdPolicy();
            },
            onFailure: (error) =>
            {
                // Inference request failed (country allowlist, timeout, 4xx/5xx, etc.).
                // Apply your fallback policy. Retry is not required.
                ApplyMyDefaultAdPolicy();
            }
        )
    );
}

5.3 Testing inference responses (QA only)

v0.x simulated responses via contexts.inferenceAttributes.forceInferenceResponse.

v1.0 uses AirfluxParameter.FORCE_RESPONSE with one of:

• "showAd"

• "skipAd"

• "defaultAdPolicy"

• "failure"

Example:

parameters[AirfluxParameter.FORCE_RESPONSE] = new Dictionary<string, object>
{
    { "action", "showAd" },
    { "parameters", new Dictionary<string, object>() }
};

Attention Force response parameters must be removed before production builds.

---

6. Verify your migration

6.1 Check logs in Unity

• Set Log Level = debug during QA to see detailed Airflux logs.

6.2 Verify event & inference payloads

At minimum, verify:

1. Required events are being tracked (AD_IMPRESSION, START_STAGE/FINISH_STAGE, ORDER_COMPLETED if applicable, etc.).

2. Inference requests include required parameters and trigger exactly one callback per request.

---

Frequently Asked Questions

Do I still need ADID (IDFA/GAID) for Airflux?

• In Unity v0.x, Airflux required ADID collection.

• In Unity v1.0, Airflux does not collect ADID.

What’s the difference between onSkipAd() and onFailure()?

• onSkipAd() means the inference request succeeded and the model decided to skip the ad.

• onFailure() means the inference request failed (e.g., allowlist not matched, timeout, network/server error) and you should apply your fallback policy.