Documentation

SDK initialization

How to start Purchasely SDKs and all necessary parameters

Start

To ensure that Purchasely is ready as soon as possible, we advise starting the SDK immediately when your application launches. Purchasely will initialize in a background thread to ensure that your application launch time and user experience are not affected.

import Purchasely

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    Purchasely
        .apiKey("X-API-KEY")
        .appUserId(nil) // optional if you already know your user id
        .runningMode(.full) // ⚠️ default is now .observer — set .full for Purchasely to handle purchases
        .storekitSettings(.storeKit2) // Set your StoreKit version
        .logLevel(.debug)
        .start { error in
            print(error == nil)
        }
	return true
}
import android.app.Application
import io.purchasely.ext.Purchasely
import io.purchasely.ext.PLYRunningMode
import io.purchasely.google.GoogleStore

class YourApplication: Application() {

    override fun onCreate() {
        super.onCreate()

        // ── Recommended — Kotlin DSL: configures AND starts the SDK in one call ──
        Purchasely {
            context(applicationContext)
            apiKey("X-API-KEY")
            userId(null) // optional if you already know your user id
            stores(listOf(GoogleStore())) // Set the list of stores you want to have
            runningMode(PLYRunningMode.Full) // ⚠️ default is now Observer — set Full for Purchasely to handle purchases
            onInitialized { error ->
                if (error == null) {
                    // Purchasely setup is complete
                }
            }
        }

        // ── Alternative — fluent Builder (same behavior; the only form for Java) ──
        Purchasely.Builder(applicationContext)
            .apiKey("X-API-KEY")
            .userId(null)
            .stores(listOf(GoogleStore()))
            .runningMode(PLYRunningMode.Full)
            .build()
            .start { error ->
                if (error == null) {
                    // Purchasely setup is complete
                }
            }
    }
}

import Purchasely from 'react-native-purchasely';

// Everything is optional except apiKey
// Example with default values
try {
    const configured = await Purchasely.builder('X-API-KEY')
        .stores(['google'])             // default is ['google'], don't forget to add the dependency to the same version
        .storekitVersion('storeKit2')   // 'storeKit2' (default) | 'storeKit1'
        .logLevel('error')              // set to 'debug' in development mode to see logs
        .runningMode('full')            // ⚠️ default is now 'observer' — set 'full' for Purchasely to handle purchases
        .appUserId(null)                // if you know your user id, set it here
        .start();
} catch (e) {
     console.log("Purchasely SDK not configured properly");
}
// Everything is optional except apiKey
// Example with default values
final bool configured = await Purchasely.apiKey('X-API-KEY')
    .stores([PLYStore.google]) // default is Google, don't forget to add the dependency to the same version
    .storekitVersion(PLYStorekitVersion.storeKit2) // storeKit2 (default) | storeKit1
    .logLevel(PLYLogLevel.error) // set to debug in development mode to see logs
    .runningMode(PLYRunningMode.full) // ⚠️ default is now observer — set full for Purchasely to handle purchases
    .appUserId(null) // set a user id if you have one
    .start();

if (!configured) {
        print('Purchasely SDK not configured');
        return;
}
private PurchaselyRuntime.Purchasely _purchasely;

_purchasely = new PurchaselyRuntime.Purchasely("USER_ID",
			false, // true for StoreKit 1, false for StoreKit 2
			LogLevel.Debug,
			RunningMode.Full,
			OnPurchaselyStart,
			OnPurchaselyEvent);
/**
* @params String apiKey
* @params StringArray stores : may be Google, Amazon and Huawei
* @params String userId
* @params Purchasley.LogLevel logLevel
* @params Purchasely.RunningMode runningMode
**/
Purchasely.start(
    'X-API-KEY',
    ['Google'],
    false, // false for StoreKit 2 (recommended), true for StoreKit 1
    null, // user id of user
    Purchasely.LogLevel.DEBUG,
    Purchasely.RunningMode.full,
    (isConfigured) => {},
    (error) => console.error(error)
);

The parameter runningMode allows you to choose between the full mode and the observer mode.

🚧

Major change in v6 — default running mode is now observer

In SDK v5 the default running mode was Full (Purchasely handles and validates purchases).
In SDK v6 the default is observer (Purchasely only observes transactions, without processing them).

This change is silent — your code keeps compiling. If you want Purchasely to handle the
purchase flow and validate receipts, you must now set the mode explicitly:
.runningMode(.full) on iOS, .runningMode(PLYRunningMode.Full) on Android.

See the v6 migration guide for details.

More details on the SDK running modes.

📘

This call is mandatory

Ensure that Purchasely.start() is the first method executed by your application.
This process does not block the main thread, allowing you to call other SDK methods immediately after invoking this method.

The following operations occur during initialization (non-exhaustive list):

  • Fetching your products and plans.
  • Retrieving one-time purchases with StoreKit (Apple) or Play Billing (Google).
  • Retrieving subscriptions and related offers with StoreKit (Apple) or Play Billing (Google).
  • Fetching current and past subscriptions from the Purchasely platform (not executed every time, thanks to a caching system).

If you depend on any of this information at the start, you must wait for the callback to be triggered.

API Key

The API Key serves as a confidential identifier, enabling your application to authenticate with Purchasely. This key permits our SDK to access your plans and confirm purchases. It's crucial to securely store this key within your application and ensure it is never disclosed publicly.

You can find your API Key in the section App settings / Backend & SDK configuration of the Purchasely Console and copy it by clicking on the Copy button.


observer mode

This is now the default running mode in SDK v6. If you want to use Purchasely in observer mode explicitly, set the running mode to observer (.observer on iOS, PLYRunningMode.Observer on Android):

import Purchasely

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    Purchasely
        .apiKey("X-API-KEY")
        .runningMode(.observer)
        .start { error in
            print(error == nil)
        }
	return true
}
import android.app.Application
import io.purchasely.ext.Purchasely
import io.purchasely.ext.PLYRunningMode
import io.purchasely.google.GoogleStore

class YourApplication: Application() {

    override fun onCreate() {
        super.onCreate()

        Purchasely.Builder(applicationContext)
            .apiKey("X-API-KEY")
            .runningMode(PLYRunningMode.Observer)
            .stores(listOf(GoogleStore())) // Set the list of stores you want to have
            .build()
            .start { error ->
               if (error == null) {
               			// Purchasely setup is complete
               }
            }
    }
}

import Purchasely from 'react-native-purchasely';

// Everything is optional except apiKey
// Example with default values
try {
    const configured = await Purchasely.builder('X-API-KEY')
        .stores(['google'])             // default is ['google'], don't forget to add the dependency to the same version
        .storekitVersion('storeKit2')   // 'storeKit2' (default) | 'storeKit1'
        .logLevel('error')              // set to 'debug' in development mode to see logs
        .runningMode('observer')        // select between 'full' and 'observer'
        .appUserId(null)                // if you know your user id, set it here
        .start();
} catch (e) {
     console.log("Purchasely SDK not configured properly");
}
// Everything is optional except apiKey
// Example with default values
final bool configured = await Purchasely.apiKey('X-API-KEY')
    .stores([PLYStore.google]) // default is Google, don't forget to add the dependency to the same version
    .storekitVersion(PLYStorekitVersion.storeKit2) // storeKit2 (default) | storeKit1
    .logLevel(PLYLogLevel.error) // set to debug in development mode to see logs
    .runningMode(PLYRunningMode.observer) // select between full and observer
    .appUserId(null) // set a user id if you have one
    .start();

if (!configured) {
        print('Purchasely SDK not configured');
        return;
}
private PurchaselyRuntime.Purchasely _purchasely;

_purchasely = new PurchaselyRuntime.Purchasely("USER_ID",
			false, // true for StoreKit 1, false for StoreKit 2
			LogLevel.Debug,
			RunningMode.Observer,
			OnPurchaselyStart,
			OnPurchaselyEvent);
/**
* @params String apiKey
* @params StringArray stores : may be Google, Amazon and Huawei
* @params String userId
* @params Purchasley.LogLevel logLevel
* @params Purchasely.RunningMode runningMode
**/
Purchasely.start(
    'X-API-KEY',
    ['Google'],
    false, // false for StoreKit 2 (recommended), true for StoreKit 1
    null, // user id of user
    Purchasely.LogLevel.DEBUG,
    Purchasely.RunningMode.observer,
    (isConfigured) => {},
    (error) => console.error(error)
);

StoreKit version

You must specify which StoreKit version you want to use with Purchasely for iOS devices.
If you choose StoreKit 2 but the iOS version on your user's device is below 15, the Purchasely SDK will automatically use StoreKit 1.
If you are unsure about which version to use, opt for StoreKit 1.

For more information, refer to our StoreKit guide.

Android stores

On Android, you must decide which store you want to use, either:

  • Google Play Store
  • Amazon App Store
  • Huawei App Gallery

You can use multiple at the same time, but the first one available from the list you provide will be used by the SDK.

For example, with listOf(GoogleStore(), AmazonStore()), if Google Play Billing is available on the device, it will be the store used by the SDK.

Each store has its own dependency that you must install. Read our installation guide for more information.

User identification

There are 2 types of users in Purchasely platform

  • connected user
  • anonymous user

You can provide a user id with Purchasely.start() if the user is already signed-in or use Purchasely.userLogin() if the user signs in after your application has started.

You can find more information about users in the dedicated section

Callback on initialization

If you rely on a specific user subscription status, such as eligibility for an introductory offer or current active subscription, wait for the start method callback. At that point, the SDK will have gathered all the necessary information to provide an accurate answer.
This also applies when you want to display a placement with an Audience based on current or past subscription status.

Otherwise, you can display a screen without waiting, as the SDK will automatically update the screen displayed when all necessary information about pricing and offers for your plans have been fetched.

Since SDK v6, the callback returns a single value:

  • error: nil (Swift) / null (Kotlin) when the SDK was initialized successfully and the configuration is correct. When it is non-null, it indicates the specific error that occurred — you can still use the Purchasely SDK.