purchasely-migrate

Purchasely SDK Migration Guide

You are migrating an existing Purchasely SDK integration. You must edit the user's project and verify each migration phase with the platform build/test commands. Native Android (Kotlin & Java), native iOS (Swift & Objective-C), Flutter, React Native, and Cordova v5.x → v6 are supported (native iOS pins 6.0.0, stable GA; native Android pins 6.0.1, stable GA — Android never had a 6.0.0 tag, the line went rc.1 → rc.2 → rc.3 → 6.0.1; Flutter pins 6.0.0, stable; React Native pins 6.0.0, stable GA; Cordova pins 6.0.0, stable GA).

The goal is a one-prompt upgrade: detect the platform and call-site language, rewrite every v5 API to its v6 form, and leave the project building with no v5-only symbols remaining.

⚠️ The change you must surface first: default running mode is now Observer

This is the single most impactful v6 change and it is silent — the project keeps compiling.

• v5 defaulted to Full mode (Purchasely processes and validates purchases).
• v6 defaults to Observer mode (Purchasely only observes transactions).

If the app relies on Purchasely to handle and validate purchases, you MUST set the running mode to Full explicitly during the init rewrite:

// iOS — Swift
Purchasely.apiKey("API_KEY").runningMode(.full).start { error in }

// Android — Kotlin
Purchasely { context(applicationContext); apiKey("API_KEY"); runningMode(PLYRunningMode.Full); /* … */ onInitialized { error -> } }

// React Native — TypeScript (string options)
await Purchasely.builder('API_KEY').runningMode('full').start()

// Cordova — JavaScript (builder API, or the options object)
await Purchasely.builder('API_KEY').runningMode(Purchasely.RunningMode.full).start()

Determine the project's intended mode before rewriting init: if the v5 code did not pass a running mode (or passed Full / did not pass .paywallObserver), it was running in Full — so the v6 rewrite must add .runningMode(.full) / runningMode(PLYRunningMode.Full) / .runningMode('full') / runningMode: Purchasely.RunningMode.full. Only omit it when the app genuinely runs its own billing and was already in Observer mode. In Observer mode, presentations also no longer auto-close after purchase/restore (v5 Full auto-appended a close_all); if the app relied on auto-close, that is another reason to set Full.