Unity - Adapty SDK installation & configuration
- Adapty SDK v3.x+ (current)
- Adapty SDK up to v2.x (legacy)
Adapty SDK includes two key modules for seamless integration into your mobile app:
- Core Adapty: This essential SDK module is required for Adapty to function properly in your app.
- AdaptyUI: This optional module is needed if you use the Adapty Paywall Builder, a user-friendly, no-code tool for easily creating cross-platform paywalls. These paywalls are built with a visual constructor right in our dashboard, run natively on the device, and require minimal effort to create high-performing designs.
Install Adapty SDKs
To install the Adapty SDKs:
-
Download the
adapty-unity-plugin-*.unitypackage
from GitHub and import it into your project.
-
Download the
adapty-ui-unity-plugin-*.unitypackage
from GitHub and import it into your project.
-
Download and import the External Dependency Manager plugin.
-
The SDK uses the "External Dependency Manager" plugin to handle iOS Cocoapods dependencies and Android gradle dependencies. After the installation, you may need to invoke the dependency manager:
Assets -> External Dependency Manager -> Android Resolver -> Force Resolve
and
Assets -> External Dependency Manager -> iOS Resolver -> Install Cocoapods
-
When building your Unity project for iOS, you would get
Unity-iPhone.xcworkspace
file, which you have to open instead ofUnity-iPhone.xcodeproj
, otherwise, Cocoapods dependencies won't be used.
Configure Adapty SDK
To configure the Adapty SDK for Unity, start by initializing the Adapty Unity Plugin and then using it as described in the guidance below. Additionally, ensure to set up your logging system to receive errors and other important information from Adapty.
-
Activate you Adapty SDK. You only need to activate it once, typically early in your app's lifecycle.
C#using UnityEngine;
using AdaptySDK;
public class AdaptyListener : MonoBehaviour, AdaptyEventListener {
void Start() {
DontDestroyOnLoad(this.gameObject);
Adapty.SetEventListener(this);
var builder = new AdaptyConfiguration.Builder("YOUR_API_TOKEN")
.SetCustomerUserId(null)
.SetObserverMode(false)
.SetServerCluster(AdaptyServerCluster.Default)
.SetIPAddressCollectionDisabled(false)
.SetIDFACollectionDisabled(false);
.SetActivateUI(true)
.SetAdaptyUIMediaCache(
100 * 1024 * 1024, // MemoryStorageTotalCostLimit 100MB
null, // MemoryStorageCountLimit
100 * 1024 * 1024 // DiskStorageSizeLimit 100MB
);
Adapty.Activate(builder.Build(), (error) => {
if (error != null) {
// handle the error
return;
}
});
}
public void OnLoadLatestProfile(Adapty.Profile profile) {
// handle updated profile data
}
}
}Parameter Presence Description YOUR_API_TOKEN required The key you can find in the Public SDK key field of your app settings in Adapty: App settings-> General tab -> API keys subsection withLogLevel optional Adapty logs errors and other crucial information to provide insight into your app's functionality. There are the following available levels: - error: Only errors will be logged.
- warn: Errors and messages from the SDK that do not cause critical errors, but are worth paying attention to will be logged.
- info: Errors, warnings, and serious information messages, such as those that log the lifecycle of various modules will be logged.
- verbose: Any additional information that may be useful during debugging, such as function calls, API queries, etc. will be logged.
withObserverMode optional A boolean value controlling Observer mode. Turn it on if you handle purchases and subscription status yourself and use Adapty for sending subscription events and analytics.
The default value is
false
.🚧 When running in Observer mode, Adapty SDK won't close any transactions, so make sure you're handling it.
withCustomerUserId optional An identifier of the user in your system. We send it in subscription and analytical events, to attribute events to the right profile. You can also find customers by customerUserId
in the Profiles and Segments menu.withIdfaCollectionDisabled optional Set to
true
to disable IDFA collection and sharing.For more details on IDFA collection, refer to the Analytics integration section.
withIpAddressCollectionDisabled optional Set to
true
to disable user IP address collection and sharing.The default value is
false
. -
Create a script to listen to Adapty events. Name it
AdaptyListener
in your scene. We suggest using theDontDestroyOnLoad
method for this object to ensure it persists throughout the application's lifespan.Adapty uses
AdaptySDK
namespace. At the top of your script files that use the Adapty SDK, you may addC#using AdaptySDK;
-
Subscribe to Adapty events:
C#using UnityEngine;
using AdaptySDK;
public class AdaptyListener : MonoBehaviour, AdaptyEventListener {
void Start() {
DontDestroyOnLoad(this.gameObject);
Adapty.SetEventListener(this);
var builder = new AdaptyConfiguration.Builder("YOUR_API_TOKEN")
.SetCustomerUserId(null)
.SetObserverMode(false)
.SetServerCluster(AdaptyServerCluster.Default)
.SetIPAddressCollectionDisabled(false)
.SetIDFACollectionDisabled(false);
.SetActivateUI(true)
.SetAdaptyUIMediaCache(
100 * 1024 * 1024, // MemoryStorageTotalCostLimit 100MB
null, // MemoryStorageCountLimit
100 * 1024 * 1024 // DiskStorageSizeLimit 100MB
);
Adapty.Activate(builder.Build(), (error) => {
if (error != null) {
// handle the error
return;
}
});
}
public void OnLoadLatestProfile(Adapty.Profile profile) {
// handle updated profile data
}
}
} -
We recommend adjusting the Script Execution Order to place the AdaptyListener before Default Time. This ensures that Adapty initializes as early as possible.
Please keep in mind that for paywalls and products to be displayed in your mobile application, and for analytics to work, you need to display the paywalls and, if you're using paywalls not created with the Paywall Builder, handle the purchase process within your app.
Add Kotlin Plugin to your project
If you're using the Paywall Builder, make sure to add the Kotlin Plugin.
Skipping this step can cause your mobile app to crash when the paywall is displayed.
-
In Player Settings, ensure that the Custom Launcher Gradle Template and Custom Base Gradle Template options are selected.
-
Add the following line to
/Assets/Plugins/Android/launcherTemplate.gradle
:apply plugin: 'com.android.application'
apply plugin: 'kotlin-android'
apply from: 'setupSymbols.gradle'
apply from: '../shared/keepUnitySymbols.gradle' -
Add the following line to
/Assets/Plugins/Android/baseProjectTemplate.gradle
:plugins {
// If you are changing the Android Gradle Plugin version, make sure it is compatible with the Gradle version preinstalled with Unity
// See which Gradle version is preinstalled with Unity here https://docs.unity3d.com/Manual/android-gradle-overview.html
// See official Gradle and Android Gradle Plugin compatibility table here https://developer.android.com/studio/releases/gradle-plugin#updating-gradle
// To specify a custom Gradle version in Unity, go do "Preferences > External Tools", uncheck "Gradle Installed with Unity (recommended)" and specify a path to a custom Gradle version
id 'com.android.application' version '8.3.0' apply false
id 'com.android.library' version '8.3.0' apply false
id 'org.jetbrains.kotlin.android' version '1.8.0' apply false
**BUILD_SCRIPT_DEPS**
}
Adapty comprises two crucial SDKs for seamless integration into your mobile app:
- Core AdaptySDK: This is a fundamental, mandatory SDK necessary for the proper functioning of Adapty within your app.
- AdaptyUI SDK: This optional SDK becomes necessary if you use the Adapty Paywall builder: a user-friendly, no-code tool for easily creating cross-platform paywalls. These paywalls are built in a visual constructor right in our dashboard, run entirely natively on the device, and require minimal effort from you to create something that performs well.
Please consult the compatibility table below to choose the correct pair of Adapty SDK and AdaptyUI SDK.
AdaptySDK-Unity version | AdaptyUI-Unity version |
---|---|
2.7.1 | 2.0.1 |
2.9.0 | not compatible |
Go through release checklist before releasing your app
Before releasing your application, make sure to carefully review the Release Checklist thoroughly. This checklist ensures that you've completed all necessary steps and provides criteria for evaluating the success of your integration.
Install Adapty SDKs
To install the Adapty SDKs:
-
Download the
adapty-unity-plugin-*.unitypackage
from GitHub and import it into your project.
-
Download the
adapty-ui-unity-plugin-*.unitypackage
from GitHub and import it into your project.
-
Download and import the External Dependency Manager plugin.
-
The SDK uses the "External Dependency Manager" plugin to handle iOS Cocoapods dependencies and Android gradle dependencies. After the installation, you may need to invoke the dependency manager:
Assets -> External Dependency Manager -> Android Resolver -> Force Resolve
and
Assets -> External Dependency Manager -> iOS Resolver -> Install Cocoapods
-
When building your Unity project for iOS, you would get
Unity-iPhone.xcworkspace
file, which you have to open instead ofUnity-iPhone.xcodeproj
, otherwise, Cocoapods dependencies won't be used.
Configure Adapty SDK
To configure the Adapty SDK for Unity, start by initializing the Adapty Unity Plugin and then using it as described in the guidance below. Additionally, ensure to set up your logging system to receive errors and other important information from Adapty.
Activate Adapty SDK
You only need to activate the Adapty SDK once, typically early in your app's lifecycle.
using AdaptySDK;
var builder = new AdaptyConfiguration.Builder("YOUR_API_TOKEN")
.SetCustomerUserId(null)
.SetObserverMode(false)
.SetServerCluster(AdaptyServerCluster.Default)
.SetIPAddressCollectionDisabled(false)
.SetIDFACollectionDisabled(false);
.SetActivateUI(true)
.SetAdaptyUIMediaCache(
100 * 1024 * 1024, // MemoryStorageTotalCostLimit 100MB
null, // MemoryStorageCountLimit
100 * 1024 * 1024 // DiskStorageSizeLimit 100MB
);
Adapty.Activate(builder.Build(), (error) => {
if (error != null) {
// handle the error
return;
}
});
Parameter | Presence | Description |
---|---|---|
YOUR_API_TOKEN | required | The key you can find in the Public SDK key field of your app settings in Adapty: App settings-> General tab -> API keys subsection |
withLogLevel | optional | Adapty logs errors and other crucial information to provide insight into your app's functionality. There are the following available levels:
|
withObserverMode | optional | A boolean value controlling Observer mode. Turn it on if you handle purchases and subscription status yourself and use Adapty for sending subscription events and analytics. The default value is 🚧 When running in Observer mode, Adapty SDK won't close any transactions, so make sure you're handling it. |
withCustomerUserId | optional | An identifier of the user in your system. We send it in subscription and analytical events, to attribute events to the right profile. You can also find customers by customerUserId in the Profiles and Segments menu. |
withIdfaCollectionDisabled | optional | Set to The default value is For more details on IDFA collection, refer to the Analytics integration section. |
withIpAddressCollectionDisabled | optional | Set to The default value is |
Use Adapty Unity Plugin
- Create a script to listen to Adapty events. Name it
AdaptyListener
in your scene. We suggest using theDontDestroyOnLoad
method for this object to ensure it persists throughout the application's lifespan.
Adapty uses AdaptySDK
namespace. At the top of your script files that use the Adapty SDK, you may add
using AdaptySDK;
- Subscribe to Adapty events:
using UnityEngine;
using AdaptySDK;
public class AdaptyListener : MonoBehaviour, AdaptyEventListener {
void Start() {
DontDestroyOnLoad(this.gameObject);
Adapty.SetEventListener(this);
}
public void OnLoadLatestProfile(Adapty.Profile profile) {
// handle updated profile data
}
}
Please keep in mind that for paywalls and products to be displayed in your mobile application, and for analytics to work, you need to display the paywalls and, if you're using paywalls not created with the Paywall Builder, handle the purchase process within your app.
Set up the logging system
Adapty logs errors and other important information to help you understand what is going on. There are three levels available:
error | Only errors will be logged. |
---|---|
warn | Errors and messages from the SDK that do not cause critical errors, but are worth paying attention to will be logged. |
info | Errors, warnings, and serious information messages, such as those that log the lifecycle of various modules will be logged. |
verbose | Any additional information that may be useful during debugging, such as function calls, API queries, etc. will be logged. |
You can call SetLogLevel()
method in your app before configuring Adapty.