Unity

Use Cursor, Claude Code, or another AI to help you integrate the Unity SDK.

Repository

Here, you will find the Appstack Unity SDK repository and the OpenUPM package page. Please use the latest available version of the SDK.

Quickstart

Use this path when you only need the minimum production integration:

Add https://package.openupm.com as a scoped registry for com.appstack, then add com.appstack.unity-sdk from the Unity Package Manager.
Install EDM4U so the Android native dependency resolves automatically, and set the minimum iOS version to 15.0.
Copy the Production API key from SDK in Appstack, for each platform you ship.
Open Edit → Project Settings → Appstack, select Create Appstack Settings, and paste the keys — or call AppstackSDK.Configure(...) once at startup instead.
Send standard events such as EventType.LOGIN, EventType.SIGN_UP, EventType.PURCHASE, and EventType.SUBSCRIBE.
Confirm events appear in the Appstack SDK page before enabling downstream integrations.

using System.Collections.Generic;
using Appstack;

#if UNITY_IOS && !UNITY_EDITOR
    string apiKey = "your-ios-production-api-key";
#elif UNITY_ANDROID && !UNITY_EDITOR
    string apiKey = "your-android-production-api-key";
#else
    string apiKey = "your-api-key"; // Editor or fallback
#endif

AppstackSDK.Configure(apiKey);

AppstackSDK.SendEvent(EventType.PURCHASE, parameters: new Dictionary<string, object>
{
    { "revenue", 29.99 },
    { "currency", "USD" }
});

Requirements

iOS

iOS version: 15.0+
Target minimum iOS Version in Player → iOS must be 15.0 or newer.

Android

Minimum API level: 21 (Android 5.0).
Target API level: 34+
Java: 17+
Native dependency: EDM4U (recommended) or the manual Gradle setup.

General

Unity: 6 (6000.0) or newer.

Initial setup

Installation

OpenUPM (recommended)

Add https://package.openupm.com as a scoped registry for com.appstack.
In Unity, open Window → Package Manager.
Select + → Add package by name and enter com.appstack.unity-sdk.

See the OpenUPM getting-started guide for scoped-registry instructions, or edit Packages/manifest.json directly:

{
  "scopedRegistries": [
    {
      "name": "package.openupm.com",
      "url": "https://package.openupm.com",
      "scopes": ["com.appstack"]
    }
  ],
  "dependencies": {
    "com.appstack.unity-sdk": "1.2.0"
  }
}

Use the current version from the OpenUPM package page.iOS Configuration

Open Edit → Project Settings → Player → iOS.
Set Target minimum iOS Version to 15.0 or newer.
Build the iOS player normally.

Note: Appstack resolves its iOS dependency automatically during the Unity build and embeds the framework in the application. No manual Xcode framework or Apple system-framework configuration is required.Android ConfigurationThe Unity package contains the Appstack C# and JNI bridge code, but it does not bundle the native Appstack Android SDK. Choose one of the following before building for Android.Option 1 (recommended): EDM4UInstall External Dependency Manager for Unity (EDM4U). Appstack’s Android dependency declaration is then discovered and resolved automatically. The Appstack Unity package does not install EDM4U for you. If automatic resolution is disabled, run Assets → External Dependency Manager → Android Resolver → Resolve.Option 2: manual Gradle configurationAdd the following repository and dependency to the Gradle templates used by your Unity project:

repositories {
    mavenCentral()
}

dependencies {
    implementation "tech.appstack.android-sdk:appstack-android-sdk:1.7.0"
}

The dependency must be available to the unityLibrary module that compiles Android plugins.Minification: no manual R8 or ProGuard configuration is required. Appstack adds its bridge keep rules to the generated Android project automatically, and the native SDK provides its own consumer rules. You do not need to enable Unity’s Custom Proguard File setting for Appstack.

Initialization

Follow these steps to get the API key:

In Appstack, from the side menu, select SDK and ensure you are selecting the correct application.
Select the Production environment.
Copy the API key.

Repeat for each platform you ship, and for the Development environment if you want separate keys for development builds.Automatic initialization (no code)Open Edit → Project Settings → Appstack, select Create Appstack Settings, and enter the development and production API keys for each platform. Appstack initializes before the first scene loads, without requiring a GameObject or startup script.

Auto Initialize — turn auto-initialization on or off.
Environment — Automatic uses the development key for Unity Development Builds and the production key for other builds. Development and Production pin every build to that environment.
Allow Production Fallback — lets a development build use its production key when no development key is configured. Off by default. Production builds never fall back to a development key.
Log Level — 0=DEBUG, 1=INFO, 2=WARN, 3=ERROR.
Enable iOS / Enable Android — enable each platform independently, each with its own Development API Key and Production API Key.
Enable Apple Ads Attribution — enables Apple Ads attribution as part of iOS auto-initialization.

Only the current build target is validated: an iOS build does not require Android keys. A build fails only when auto-initialization and its current target platform are enabled but no key can be resolved for that build, so the app never ships with Appstack unexpectedly disabled.

Creating settings opts the project into auto-initialization. Installing the package alone creates no settings and changes no runtime behavior.

Manual initializationLeave the settings asset absent, or turn off Auto Initialize, when a consent flow, a custom bootstrap order, or remotely supplied configuration must come first. Call Configure once during application startup and before any other SDK method:

using System.Collections.Generic;
using Appstack;
using UnityEngine;

public sealed class AppstackInitializer : MonoBehaviour
{
    [SerializeField] private string iosApiKey;
    [SerializeField] private string androidApiKey;

    private void Start()
    {
#if UNITY_IOS && !UNITY_EDITOR
        string apiKey = iosApiKey;
#elif UNITY_ANDROID && !UNITY_EDITOR
        string apiKey = androidApiKey;
#else
        string apiKey = "your-api-key";
#endif

        AppstackSDK.Configure(apiKey);

#if UNITY_IOS && !UNITY_EDITOR
        AppstackSDK.EnableAppleAdsAttribution();
#endif

        AppstackSDK.SendEvent(
            EventType.PURCHASE,
            parameters: new Dictionary<string, object>
            {
                { "revenue", 29.99 },
                { "currency", "USD" }
            });
    }
}

The first successful automatic or manual configuration wins. Repeating the same configuration is a silent no-op; a conflicting repeat is ignored with a warning that does not expose either API key. A failed configuration attempt does not lock the wrapper and can be retried.

Configuration parameters

Initializes the SDK with your API key. Call it once during application startup, before any other SDK method.Parameters:

apiKey Your platform-specific API key from the Appstack dashboard.
logLevel Optional log level: 0=DEBUG, 1=INFO, 2=WARN, 3=ERROR (default: 1). iOS has no dedicated warning level, so WARN behaves like ERROR there.
customerUserId Optional customer user ID.

Example:

AppstackSDK.Configure("your-api-key-here");

// With all parameters
AppstackSDK.Configure(
    apiKey: "your-api-key-here",
    logLevel: 0,                 // DEBUG
    customerUserId: "user-123"
);

You can check whether the SDK ended up disabled (for example after an invalid API key):

if (AppstackSDK.IsSdkDisabled())
    Debug.LogWarning("Appstack SDK is disabled – check your API key.");

Customer user ID

The customer user ID is your own identifier for the signed-in user. Appstack attaches it to events so server-to-server events — which identify the user by this ID rather than by the install — can be joined back to the install that produced them.Pass it to Configure when you already know it at startup. More often a login reveals it afterwards, so set it whenever it becomes known:

AppstackSDK.SetCustomerUserId("user-123"); // on login

Callable at any time, before or after Configure, as often as you like. The last call wins, and it applies to every event sent from then on, including ones the native SDK has buffered but not yet flushed.
The call does not send anything by itself: make sure at least one event follows, or no mapping is ever formed.
Calling Configure again to change the ID does not work — a repeat Configure is a no-op and its customerUserId is ignored.

Sending events

Track user actions and revenue from your scripts:

// Track events without parameters
AppstackSDK.SendEvent(EventType.SIGN_UP);
AppstackSDK.SendEvent(EventType.LEVEL_COMPLETE);

// Track events with parameters (including revenue)
AppstackSDK.SendEvent(EventType.PURCHASE, parameters: new Dictionary<string, object>
{
    { "revenue", 29.99 },
    { "currency", "USD" }
});
AppstackSDK.SendEvent(EventType.SUBSCRIBE, parameters: new Dictionary<string, object>
{
    { "revenue", 9.99 },
    { "plan", "monthly" }
});

// Custom events
AppstackSDK.SendEvent(
    EventType.CUSTOM,
    eventName: "user_attributes",
    parameters: new Dictionary<string, object>
    {
        { "email", "test@example.com" },
        { "name", "John Doe" },
        { "phone_number", "+33060000000" },
        { "date_of_birth", "2026-02-01" }
    });

Available EventType valuesIt is recommended to use standard events for a smoother experience.

EventType.INSTALL is tracked automatically by the native SDKs on first launch. Do not send it manually — SendEvent(EventType.INSTALL) is a no-op.

EventType.LOGIN/ EventType.SIGN_UP/ EventType.REGISTER Authentication
EventType.PURCHASE/ EventType.ADD_TO_CART/ EventType.ADD_TO_WISHLIST/ EventType.INITIATE_CHECKOUT/ EventType.START_TRIAL/ EventType.SUBSCRIBE Monetization
EventType.LEVEL_START/ EventType.LEVEL_COMPLETE Game progression
EventType.TUTORIAL_COMPLETE/ EventType.SEARCH/ EventType.VIEW_ITEM/ EventType.VIEW_CONTENT/ EventType.SHARE Engagement
EventType.CUSTOM For application-specific events

Tracks standard and custom events with optional parameters:

eventType - Event type from the EventType enum (required).
eventName - Event name required for CUSTOM events; ignored for standard events.
parameters - Optional dictionary of parameters (e.g. { "revenue", 29.99 }, { "currency", "USD" }).

Event parameters may contain strings, Booleans, finite numeric values, nulls, nested string-keyed dictionaries, and arrays. Unsupported objects and non-finite numbers such as NaN or infinity throw an ArgumentException before the event is sent.Enhanced app campaigns

When running enhanced app campaigns (EACs), it is highly recommended to send multiple parameters with the in-app event to improve matching quality.

For any event that represents revenue, we recommend sending:

revenue or price (number).
currency(string, e.g. EUR, USD).

AppstackSDK.SendEvent(EventType.PURCHASE, parameters: new Dictionary<string, object>
{
    { "revenue", 4.99 },
    { "currency", "EUR" }
});

To improve matching quality on Meta, send events including the following parameters if you can fulfill them. Appstack automatically encrypts these matching parameters before using them for attribution matching.

email.
name (first + last name in the same field).
phone_number — also accepted as phone or phoneNumber.
date_of_birth (recommended format: YYYY-MM-DD) — also accepted as birthdate, birthday, or dateOfBirth.
gender.

Appstack ID and attribution params

After configuration, you can read the Appstack user ID and the attribution parameters, so you can forward them to any partner SDK that accepts attribution data.

string appstackId = AppstackSDK.GetAppstackId();

AppstackSDK.GetAttributionParams(
    onSuccess: parameters =>
    {
        foreach (var kv in parameters)
            Debug.Log($"Attribution: {kv.Key} = {kv.Value}");
    },
    onError: error => Debug.LogError($"Attribution error: {error}")
);

GetAppstackId() — Appstack user identifier when a partner expects $appstackId or similar.
GetAttributionParams(onSuccess, onError) — Attribution payload (campaign, media source, click IDs, device identifiers where available) to forward to partners.

Callbacks are delivered on the synchronization context captured when GetAttributionParams is called, when one is available. Calling it from Unity’s main thread lets the callbacks safely update Unity objects.

Development setup

Environment-based configuration

With auto-initialization, keep Environment on Automatic: Unity Development Builds use the development key and other builds use the production key. For manual initialization, resolve the key yourself:

#if UNITY_IOS && !UNITY_EDITOR
    string apiKey = Debug.isDebugBuild ? "ios-development-key" : "ios-production-key";
#elif UNITY_ANDROID && !UNITY_EDITOR
    string apiKey = Debug.isDebugBuild ? "android-development-key" : "android-production-key";
#else
    string apiKey = "your-api-key"; // Editor or fallback
#endif

AppstackSDK.Configure(apiKey, logLevel: Debug.isDebugBuild ? 0 : 1);

Editor and unsupported platforms

In the Unity Editor and on non-iOS/Android platforms, SDK methods are no-ops or return safe defaults: GetAppstackId() returns null and IsSdkDisabled() returns true. These platforms do not call native code, so verify your integration on a device or in a store build.

Platform-specific considerations

iOS

Apple Ads attribution:

Requires iOS 15.0+ and an App Store or TestFlight installation.
Attribution data appears within 24-48 hours.
User consent may be required for detailed attribution.
Simulator and ordinary development installs do not represent the production attribution flow.

#if UNITY_IOS && !UNITY_EDITOR
AppstackSDK.EnableAppleAdsAttribution();
#endif

With auto-initialization, enable Enable Apple Ads Attribution in Edit → Project Settings → Appstack instead of calling the method yourself.

Android

Play Store Attribution

Install referrer data collected automatically.
Attribution available immediately for Play Store installs.
Works with Android 5.0+ (API level 21).

Security and privacy

Never commit API keys to version control. The password fields in Project Settings → Appstack mask keys visually only: values stay plaintext in the settings asset and in version control.
Unity includes the entire Resources asset in player builds, so every configured key — including development keys and keys for the other mobile platform — may be present in a production player. Treat them as application ingestion credentials, not administrative secrets.
Use separate production and development keys.
Do not put personally identifiable information in event names.
Only send matching parameters such as email, name, phone_number, and date_of_birth when your app has the right consent and compliance basis. Appstack automatically encrypts these fields before using them for attribution matching.
Prefer standard event types for common flows so event mapping remains consistent across Appstack and ad integrations.

Limitations

Attribution timing

iOS: Apple Ads attribution data appears within 24-48 hours after install.
Android: Install referrer data available immediately for Play Store installs.
Attribution only available for apps installed from official stores.

Platform constraints

Unity: 6 (6000.0) or newer.
iOS: requires iOS 15.0+.
Android: minimum API level 21, target API level 34+, Java 17+.
Android builds require EDM4U or the manual Gradle dependency; the package does not bundle the native Android SDK.
SDK methods are no-ops in the Editor and on non-iOS/Android platforms.

Event tracking

Event names are case-sensitive and standardized.
For revenue events, always pass a revenue (or price) and a currency parameter.
The SDK must be configured — automatically or manually — before any tracking call.
SendEvent(EventType.INSTALL) is ignored; install is tracked automatically.
EnableAppleAdsAttribution() only applies on iOS and is a no-op on Android.
Custom events require an eventName; unsupported parameter values throw an ArgumentException before the event is sent.
Network connectivity required for event transmission (events are queued offline).

Troubleshooting

Configuration fails

Confirm the API key was copied from the correct app and environment in Appstack.
Confirm AppstackSDK.Configure(...) runs once at startup before any other SDK method, or that auto-initialization settings exist with a key for the current target and environment.
Check AppstackSDK.IsSdkDisabled() and the Unity Console with logLevel: 0 (DEBUG).
Remember that a repeat Configure is ignored, so a second call cannot change the API key, log level, or customer user ID.

Events do not appear

Confirm the build runs on a device: SDK methods are no-ops in the Editor.
Confirm configuration completed before the first SendEvent(...) call.
Confirm the device has network connectivity.
Check that revenue events include a numeric revenue or price value and a valid currency.
Allow a few minutes for events to appear in the dashboard.

iOS build cannot find `AppstackSDK`

Delete the generated Xcode project and export it again from Unity.
Check the Unity Console for postprocessing errors.
Confirm the generated Xcode project lists the AppstackSDK package product on both the UnityFramework and application targets.
Confirm the build machine can reach GitHub to resolve Swift packages.

Gradle cannot resolve the Appstack Android SDK

Run Assets → External Dependency Manager → Android Resolver → Resolve again.
Confirm Maven Central is available in the generated Gradle repositories.
Confirm the build uses Java 17 or newer.
Inspect the Unity Console and Gradle output for the original resolution error.

A build fails with an Appstack configuration error

Auto-initialization is enabled for the current target platform but no key resolves for that build. Add the missing key in Edit → Project Settings → Appstack, disable that platform, or turn off Auto Initialize.
For a development build with only a production key, either add a development key or enable Allow Production Fallback.

Apple Ads

To start using the Apple Ads integration, click here to see the correct SDK documentation.

Verification checklist

com.appstack.unity-sdk is installed from OpenUPM at a current version.
Project meets Unity 6+, iOS 15.0+, Android API level 21+ / target 34+, and Java 17+ requirements.
Target minimum iOS Version is set to 15.0 or newer.
EDM4U is installed and resolved, or the manual Gradle dependency is configured for the unityLibrary module.
Platform-specific API keys are configured for iOS and Android.
Production API keys are used in production builds; development keys only in development builds.
The SDK is configured exactly once — through auto-initialization settings or a single Configure(...) at startup.
iOS-only Apple Ads calls are guarded with #if UNITY_IOS && !UNITY_EDITOR, or enabled through the settings asset.
EventType.INSTALL is not sent manually.
Login, signup, purchase, subscription, and other key app events use standard event types where possible.
Revenue events include revenue or price and currency.
Custom events use EventType.CUSTOM with a descriptive eventName.
The customer user ID is set once it becomes known, with at least one event following.
Appstack ID and attribution params are available before wiring partner integrations.
Events are visible in the Appstack SDK page before launch.

Support

For questions or issues:

Check the GitHub Repository.
Contact our support team at support@appstack.tech
Open an issue in the repository.

Use Cursor, Claude Code, or another AI to validate your existing Appstack Unity SDK integration.

Open in Cursor

Getting started

Mobile SDKs

Integrations

Products

API reference

Repository

Quickstart

Requirements

iOS

Android

General

Initial setup

Appstack ID and attribution params

Development setup

Environment-based configuration

Editor and unsupported platforms

Platform-specific considerations

iOS

Android

Security and privacy

Limitations

Attribution timing

Platform constraints

Event tracking

Troubleshooting

Configuration fails

Events do not appear

iOS build cannot find `AppstackSDK`

Gradle cannot resolve the Appstack Android SDK

A build fails with an Appstack configuration error

Apple Ads

Verification checklist

Support

​Repository

​Quickstart

​Requirements

​iOS

​Android

​General

​Initial setup

​Appstack ID and attribution params

​Development setup

​Environment-based configuration

​Editor and unsupported platforms

​Platform-specific considerations

​iOS

​Android

​Security and privacy

​Limitations

​Attribution timing

​Platform constraints

​Event tracking

​Troubleshooting

​Configuration fails

​Events do not appear

​iOS build cannot find AppstackSDK

​Gradle cannot resolve the Appstack Android SDK

​A build fails with an Appstack configuration error

​Apple Ads

​Verification checklist

​Support

Repository

Quickstart

Requirements

iOS

Android

General

Initial setup

Appstack ID and attribution params

Development setup

Environment-based configuration

Editor and unsupported platforms

Platform-specific considerations

iOS

Android

Security and privacy

Limitations

Attribution timing

Platform constraints

Event tracking

Troubleshooting

Configuration fails

Events do not appear

iOS build cannot find `AppstackSDK`

Gradle cannot resolve the Appstack Android SDK

A build fails with an Appstack configuration error

Apple Ads

Verification checklist

Support