Testing and Go Live

AppActor integrations should be tested in real store environments before launch. The SDK layer, your catalog, and the store itself can all be valid independently while the full purchase flow is still broken.

Test in the real store path

iOS should be tested with StoreKit local testing for quick iteration and with Apple sandbox or TestFlight for real account and receipt behavior
Android should be tested with license testers and an internal testing track in Google Play
Flutter and React Native should be tested through the underlying native store paths on each platform, not only through mocked Dart or JavaScript state

Store-backed recipe

Create the fake-safe catalog shape from Catalog Setup: premium, default, monthly, annual.
Configure the app with the platform’s public app SDK key.
Fetch offerings and verify the current offering has packages.
Render package cards using localized store prices.
Purchase monthly and verify hasActiveEntitlement("premium").
Cancel or expire in the sandbox and verify access changes.
Reinstall and test restore or sync behavior.
Test empty offering, missing product, pending purchase, and flaky-network paths.
Confirm the purchase appears in the AppActor dashboard customer or transaction view.
Confirm Apple notification health, Google RTDN health, and outbound webhook delivery if your backend uses webhooks.

Validate the catalog first

Before you debug app code, confirm:

the app is using the expected public pk_... key
the current offering exists
the package slots your paywall reads are actually populated
those packages map to real store products on the target platform
the products unlock the entitlement keys your app checks after purchase

High-value scenarios to test

Run these on every platform you support:

Fresh install, configure, fetch offerings, and render a paywall.
Purchase from the current offering and verify the expected entitlement unlocks.
Re-open the app and confirm customer state restores without duplicate purchase UI.
Reinstall, then validate your restore or sync path.
If your app supports anonymous purchase then login, verify the identity transition explicitly.
Test offline or flaky-network launch behavior if your app depends on cached offerings or offline entitlement decisions.

Recovery flows deserve dedicated testing

Do not treat these as interchangeable:

restorePurchases()
syncPurchases()
explicit queue-drain recovery APIs

Your QA plan should prove that each one is wired to the right user or operational flow.

Pre-release checklist

Before go-live, verify:

the production key and production catalog are selected
the paywall can render when offerings are present
premium access is gated from customer entitlements, not local UI state
cancellation, renewal, or expired-access behavior is visible in the app state you use
support or settings surfaces expose the correct recovery path
Apple App Store Server Notifications are healthy for the iOS app
Google RTDN is healthy for the Android app
outbound webhooks verify X-AppActor-Signature and dedupe by eventId
refund, renewal, cancellation, grace, billing retry, and expiration scenarios have dashboard evidence

Go-live evidence matrix

Use this table as the release gate. A row is not done until the SDK result, dashboard evidence, notification or webhook evidence, and owner are all filled in.

Test action	Expected SDK result	Dashboard evidence	Webhook / RTDN evidence	Owner
Fetch offerings on a fresh install	`offerings.current` exists and contains the package slots your UI reads.	Catalog > Offerings shows `default` as current with `monthly` and `annual` packages mapped.	Not required for this row.	Mobile
Purchase monthly in sandbox	Purchase returns success or refreshed `CustomerInfo`; `hasActiveEntitlement("premium")` is true.	Customers or Transactions shows tester ID, `appUserId`, store transaction ID, product, environment, and active entitlement.	Store notification may arrive later; outbound webhook should receive `subscription.purchased` or `purchase.completed` if configured.	Mobile + Backend
Force a sandbox renewal	Customer info remains active and the expiration or renewal timestamp advances.	Customers > Timeline or Transactions shows renewal event, product, environment, store transaction ID, and latest event timestamp.	Apple notification or Google RTDN is received and processed; outbound webhook receives `subscription.renewed` if configured.	QA
Trigger grace or billing retry	App shows the intended grace, retry, or locked state from customer info.	Customers > Timeline shows billing retry or grace state for the same tester and product.	Store notification or RTDN is processed; outbound webhook receives `subscription.billing_issue` when configured.	QA + Backend
Cancel or expire sandbox subscription	Customer info refresh eventually removes active access or shows the expected grace state.	Customers > Timeline or Transactions shows cancellation or expiration with the latest event timestamp.	Apple notification or Google RTDN is received and processed for the matching app.	QA
Refund or revoke a purchase	Premium access is removed after refresh.	Customers > Timeline or Transactions shows refund, revoke, or voided purchase for the same store transaction ID.	Store notification is processed; outbound webhook receives `subscription.refunded`, `subscription.revoked`, or `purchase.refunded`.	QA + Backend
Reinstall and restore	Restore refreshes the correct customer without duplicating grants.	Customers maps the restored transaction to the expected `appUserId` or anonymous identity.	Not required unless a store notification is emitted.	Mobile
Sign in and sync purchases	`syncPurchases()` refreshes ownership after identity changes without showing a restore prompt.	Customers shows the signed-in `appUserId` and expected transaction ownership.	Not required unless a store notification is emitted.	Mobile
Drain a queued receipt	`drainReceiptQueueAndRefreshCustomer()` posts retryable receipts and returns refreshed customer state.	Transactions or customer timeline shows the queued receipt resolved instead of duplicated.	Webhook fires only after AppActor processes the receipt; retryable failures stay visible.	Mobile + QA
Send Apple test notification	No SDK change required.	Apps > iOS app detail shows Apple webhook state, environment, verified time, test result, and last processed timestamp.	Apple test notification is received and processed for the current URL.	Ops
Send Google RTDN test notification	No SDK change required.	Apps > Android app detail shows current Topic ID, package binding, and processed RTDN health.	Google test notification is received and processed for the current Topic ID and package.	Ops
Deliver outbound webhook	Backend handler returns `2xx` after durable accept.	Webhook delivery detail is delivered, with response code, delivery ID, event ID, and attempt count.	`X-AppActor-Signature` verifies and duplicate `eventId` does not duplicate side effects.	Backend
Force a webhook retry	Temporarily return `500` or timeout once, then recover to `2xx`.	Webhook delivery detail shows failed attempt, retry attempt count, response code or timeout, then delivered status.	Retry uses the same event safely, and idempotency prevents duplicate side effects.	Backend

Use the example apps and tests as support material

Each SDK repo still contains useful reference material:

iOS package UI: Examples/AppActorExample/AppActorExample/Features/Offerings/PackageRow.swift
iOS purchase and restore flows: Examples/AppActorExample/AppActorExample/Features/Offerings
Android offerings UI: app/src/main/java/com/appactor/example/ui/Features/Offerings/OfferingsTab.kt
Flutter package card: example/lib/widgets/package_card.dart
Flutter purchase controls: example/lib/screens/home/home_screen.dart
React Native offerings and purchase section: example/src/App.tsx

Those examples are excellent debugging references, but they are not a substitute for store-backed release testing in your own app.

Sandbox-specific checks

Area	What to prove
iOS StoreKit local	Products resolve and the UI can iterate quickly.
iOS Sandbox / TestFlight	Real sandbox account, receipt validation, restore, pending/Ask to Buy where applicable.
Android internal track	License tester can see products, subscriptions, base plans, and offers.
Pending purchases	App shows pending state and refreshes later instead of unlocking immediately.
Receipt retry	Retryable receipts are not converted into permanent consumable grants early.
Sandbox flag	Purchase info exposes sandbox/test state where the SDK reports it.
Dashboard event feed	Purchase, entitlement, and transaction records match the tester and platform.
Webhook delivery	Your endpoint receives a signed event and handles duplicate `eventId` safely.

Overview

Get Started