Migrating from SDK 4.X to 5.X
This page provides an overview on everything you need to know to migrate from SDK v4 to v5
Version 5.0 is a major update of the Purchasely SDK as it introduces support for the new Screen Composer, which provides an intuitive and flexible way to design custom screens for your app.
Here is everything you need to know about the upgrade from SDK v4.X to v5.
What are the main differences between the Paywall Builder and the Screen Composer?
The legacy Paywall Builder was mainly meant to create paywalls. It was based on a system of Templates and was limited regarding the customization capabilities. Here is a summary of the capabilities
| Paywall Builder (legacy) | Screen Composer (new) | |
|---|---|---|
| Type | Template based => less flexible | Components based => much more flexible and new components will be regularly added. |
| Type of Screens | Mainly paywalls limited for other types of Screens. No surveys | Any type of Screens including Surveys. |
| Flexibility to add and remove components | ❌ | ✅ Simply drag & drop them from the library of components into your Screen |
| Change layout | ❌ | ✅ Change the layout any time even after configuring the components |
| Reorder components | ❌ | ✅ Drag & drop components within the Screen structure to change their order |
| Adjust margin and padding | ❌ | ✅ Adjust the padding & margin of every surface, component or text element |
| Text elements within a component | Limited to 2 only a title and a subtitle are available | Flexible Text elements can be added or removed |
| Rich text within a text element | ❌ | Compatible with markdown Italic, Bold, Strikethrough and links |
| Copy & past of components from one Screen to the other | ❌ | ✅ Right click on an individual component to copy it or on a surface to copy all the components it contains. Then simply paste it into another Screen or surface |
Is the SDK v5 able to display my existing Paywalls built with the legacy Paywall Builder?
YES.
The SDK v5 is fully compatible with Paywalls built using the Legacy Paywall Builder and can display them.
=> This means you do not need to migrate or replicate your legacy Paywalls in the Screen Composer, they will still be displayed properly.
- You can continue building Paywalls with the legacy Screen Builder until its official deprecation which will happen on March 30th 2025.
- Paywalls built with the Screen Builder will remain modifiable even after its deprecation, but from April 1st 2025 onwards, it will not be possible to create new Paywalls with the legacy Paywall Builder.
- Given the additional capabilities brought by the Screen Composer, we strongly encourage you to start using it ASAP. We are sure you will just love it.
Not convinced yet?
Take the short Product Tour to get an overview of the possibilities offered by the new Screen Composer
Check thoroughly your legacy Screens during the QA phase
The major modification brought to the SDK v5 concerns the native rendering engine embedded in the SDK.
When integrating the new version of the SDK we invite you to be vigilant to how your legacy Paywalls get displayed, by checking them on a Staging / Test Flight / Firebase Tester app before releasing it into production.
In case you notice any glitch (which should not happen), reach out to the Customer Success team so that we can fix it quickly!
What is the changelog of the version 5?
A few methods have been deprecated or renamed but the upgrade from v4.X to v5 does not require many code changes on the app side. Just a matter of a couple hours of work for the developers.
The details of the changelog are accessible here: https://docs.purchasely.com/changelog/500
How to display new Screens built with the Screen Composer for users who have not updated their app? (SDK version < 5.0)
You can't, as the v4.X of the SDK does not render new Screens built with the Screen Composer properly.
BUT, we've thought of you and made your life easy by implementing a fallback feature 🤩!
-
When creating a Screen with the Screen composer, you can associate it with a Fallback Screen (compatible with older versions of the SDK 4.X)
-
If an old version of your app integrating a version of the SDK which is not compatible with the new Gen Screen (SDK version < v5), it will automatically fall-back on the associated Screen, which means that the Screen will be properly rendered.
Benefit for you: you do not need to create complex audiences to target new Screens only for latest versions of your app: the Screen rendered by the SDK will always display properly.
Updated 1 day ago