Migrating from SDK 5 to 6

Version 6.0 is a major release of the Purchasely SDK. It modernizes the public API around a single, consistent presentation model, replaces the global action interceptor with a granular per‑action API, and clarifies a number of method names.

This page gives you the overview. Detailed, copy‑paste migration steps are available per platform at the bottom of this page.

⚠️ The one change everyone must check: default running mode is now Observer

This is the single most impactful change of v6, and it is silent — your code keeps compiling.

In v5, the SDK defaulted to Full mode (Purchasely handles and validates purchases). In v6, the default is now Observer mode (Purchasely observes transactions but does not process them).

🚧

If your app relies on Purchasely to process purchases and validate receipts, you must now set the running mode explicitly.

Swift

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

Kotlin

// Android
Purchasely.Builder(context).apiKey("API_KEY").runningMode(PLYRunningMode.Full) /* … */ .build().start { error -> }

If you forget, the SDK will compile and run, but it will stop validating transactions. See SDK initialization for full details.

What changed across all native platforms

v6 concentrates the migration around three surfaces. Start with these first, then use the platform guide for the smaller renames and edge cases.

📣

Campaigns and deeplinks are available by default

In v6, deeplinks and campaigns are no longer blocked until you explicitly unlock them. allowDeeplink and allowCampaigns both default to true, so campaign and deeplink paywalls can display as soon as the SDK is configured. If your app needs to wait for onboarding, login, splash loading or a consent step, set them to false during start and flip them back to true when the app is ready.

1. Start now uses a builder

The old positional start(...) calls are replaced by a fluent builder (or the Android Kotlin DSL). This makes defaults visible and keeps platform-specific options in one chain.

The important default is still the running mode: v6 starts in Observer mode unless you explicitly set Full.

   try await Purchasely
       .apiKey("YOUR_API_KEY")
       .appUserId("user_123")
       .runningMode(.full)     // required if Purchasely handles purchases
       .allowDeeplink(true)    // default: true
       .allowCampaigns(true)   // default: true
       .start()

2. Presentation display uses a build → preload → display lifecycle

fetchPresentation(...), presentPresentationForPlacement(...), direct product/plan presentation helpers and platform-specific display overloads move to a single presentation request model.

Use the builder to target a placement, screen or default presentation, then choose whether to preload() before showing or call display() directly. Dismissal now returns a single rich outcome (PLYPresentationOutcome or the platform equivalent) with the presentation, purchase result, plan, close reason and error.

   let presentation = try await PLYPresentationBuilder
       .forPlacementId("ONBOARDING")
       .build()
       .preload()

   presentation.display(from: self)

3. Action interception is per action

The global paywall action interceptor is gone. Register one handler per action and return an explicit result:

This replaces the ambiguous processAction(true/false) pattern and makes observer-mode purchase flows easier to reason about.

   Purchasely.interceptAction(.purchase) { info, params in
       guard let plan = params?.plan else { return .notHandled }

       do {
           try await customPurchase(plan)
           return .success
       } catch {
           return .failed
       }
   }

Platform support

Let the AI plugin help with the migration

The Purchasely AI Plugin ships a dedicated migration skill, purchasely-migrate. It can scan an existing Purchasely integration, identify v5 calls, rewrite the migration hotspots to the v6 builder APIs, and flag anything that still needs a product or billing decision.

Use it for the repetitive parts first: SDK start, presentation display / preload, action interception, deeplink renames and default running mode checks. Then run the platform guide manually for the final review.

   /plugin marketplace add Purchasely/Purchasely-AI-Plugin
   /plugin install purchasely@Purchasely-AI-Plugin
   /purchasely:migrate

Before you start

• Read the default running mode warning above — it applies to every platform.
• v6 keeps a number of v5 methods as deprecated (they still compile but are scheduled for removal in v7). Migrating off them now avoids a second pass later.
• Test your paywalls on a real device / staging build before releasing to production. The native rendering and display pipeline were refactored in v6.

Pick your platform below to get started. 👇