Quickstart

This guide shows the shortest path to a working AppActor integration. It assumes you are wiring a mobile app that will fetch offerings from AppActor, render its own paywall, purchase a package, and gate access from customer entitlements.

Skim this page first if you want the whole path. For production, finish Project and Store Setup, Catalog Setup, and Server Notifications before you ship.

Prerequisites

Before you begin, you should have:

an AppActor project with iOS and/or Android apps added
a public app SDK key such as pk_YOUR_PUBLIC_APP_KEY
store products configured in App Store Connect or Google Play Console
entitlements, offerings, and package slots configured in AppActor
a supported client app: iOS, Android, Flutter, or React Native
a plan for rendering your own paywall UI from offerings and packages
Apple App Store Server Notifications or Google RTDN connected before production launch

The setup order

Follow this order when you are building the first real integration:

Create the AppActor project and platform apps.
Connect Apple or Google store credentials.
Create the catalog: entitlement, store products, offering, and package slots.
Install and configure the SDK with the public app key.
Fetch offerings, render your paywall, purchase a package, and check entitlements.
Before launch, verify Apple notifications, Google RTDN, and outbound webhooks if your backend uses them.

Get started

Create the project, apps, and catalog

Do this in the AppActor dashboard before debugging SDK code:

create one project for the product
add an iOS app with the Bundle ID and/or an Android app with the package name
connect store credentials
create an entitlement such as premium
connect store products and attach them to premium
create a current offering such as default
add packages such as monthly and annual

Continue with Project and Store Setup and Catalog Setup when you need the dashboard checklist.

Install the SDK

Pick your platform and add the matching SDK.

dependencies: [
    .package(url: "https://github.com/appactor/appactor-ios.git", from: "0.1.8")
]

dependencies {
    implementation("com.appactor:appactor-android:2.3.7")
}

dependencies:
  appactor_flutter: ^0.0.16

npm install appactor-react-native

Configure AppActor

Initialize AppActor as early as possible in your app bootstrap.

await AppActor.configure(apiKey: "pk_YOUR_PUBLIC_APP_KEY")

lifecycleScope.launch {
    AppActor.shared.configure(
        context = applicationContext,
        apiKey = "pk_YOUR_PUBLIC_APP_KEY",
    )
}

await AppActor.instance.configure(
  AppActorPlatformKeys(
    ios: 'pk_YOUR_IOS_PUBLIC_APP_KEY',
    android: 'pk_YOUR_ANDROID_PUBLIC_APP_KEY',
  ),
  appUserId: 'user_123',
);

await AppActor.instance.configure(
  new AppActorPlatformKeys(
    'pk_YOUR_IOS_PUBLIC_APP_KEY',
    'pk_YOUR_ANDROID_PUBLIC_APP_KEY'
  ),
  {
    appUserId: 'user_123',
  }
);

Fetch offerings and render your paywall

Offerings are the catalog surface you use to build a paywall in your own UI.

let offerings = try await AppActor.shared.offerings()
let current = offerings.current

lifecycleScope.launch {
    val offerings = AppActor.shared.offerings()
    val current = offerings.current
}

final offerings = await AppActor.instance.getOfferings();
final current = offerings.current;

const offerings = await AppActor.instance.getOfferings();
const current = offerings.current;

Purchase a package

Once the user chooses a package, pass it into the platform purchase API.

guard let package = current?.monthly else { return }
let result = try await AppActor.shared.purchase(package: package)

lifecycleScope.launch {
    val packageToBuy = current?.monthly ?: error("No monthly package")
    val result = AppActor.shared.purchase(activity, packageToBuy)
}

final packageToBuy = current?.monthly;
if (packageToBuy == null) return;

final result = await AppActor.instance.purchasePackage(
  packageToBuy,
  placement: 'onboarding_paywall',
);

const monthly = current?.monthly;
if (!monthly) return;

const result = await AppActor.instance.purchasePackage(monthly, {
  placement: 'onboarding_paywall',
});

Verify access from customer info

Gate premium access from customer info and entitlements, not from UI state alone.

let info = try await AppActor.shared.getCustomerInfo()
let isPremium = info.hasActiveEntitlement("premium")

lifecycleScope.launch {
    val info = AppActor.shared.getCustomerInfo()
    val isPremium = info.hasActiveEntitlement("premium")
}

final info = await AppActor.instance.getCustomerInfo();
final isPremium = info.hasActiveEntitlement('premium');

const info = await AppActor.instance.getCustomerInfo();
const isPremium = info.hasActiveEntitlement('premium');

Important integration notes

AppActor does not render paywalls for you; your app owns the final purchase UI.
AppActor does not expose a cross-platform getProducts() method. Fetch offerings and render packages.
configure() is not a cosmetic init. It establishes or restores identity, warms purchase state, and synchronizes important SDK context.
syncPurchases() is not the same thing as restorePurchases() or explicit receipt queue drain APIs. Read Purchases and Sync before wiring account recovery.
Use a stable appUserId if your product has accounts. That gives you a cleaner restore and re-install story than relying on anonymous identities.
On Android, most direct SDK calls are suspend APIs, so call them from a coroutine or lifecycle-aware scope.

Go deeper

Products and Packages

Understand the catalog model before you write paywall UI.

Server Notifications

Connect Apple and Google store events before production launch.

Displaying Products

Build package cards with localized price, metadata, and safe fallbacks.

Making Purchases

Handle success, cancelled, pending, and retryable receipt outcomes.

Trusted Entitlements

Decide when verification is strong enough to unlock sensitive access.

Need deeper platform setup? Continue with the dedicated guides:

Overview

Get Started

Testing and Go Live

Features

Remote Config

Experiments

Platform Resources

AI-Ready

Prerequisites

The setup order

Get started

Important integration notes

Go deeper

Products and Packages

Server Notifications

Displaying Products

Making Purchases

Trusted Entitlements

​Prerequisites

​The setup order

​Get started

​Important integration notes

​Go deeper

Products and Packages

Server Notifications

Displaying Products

Making Purchases

Trusted Entitlements

Prerequisites

The setup order

Get started

Important integration notes

Go deeper