Finished Migrating — What's Next?
Finishing your SDK integration is a milestone — but it's not the finish line.
Completing development does not mean your app is immediately live in production. Before your migrated behavior reaches real stores, it goes through validation and a controlled rollout that is conducted by Nuvemshop. This page explains exactly what to do once your integration with the SDK is ready, and what happens after that.
The short version
You validate your app on a test store, remove the legacy-script dependency for the behavior you migrated, and get it homologated.
Once homologated, Nuvemshop activates the SDK behavior in production gradually (canary) — it is not switched on for every store at once, and it is not something you trigger store by store.
The three script scenarios
Today, an app's storefront/checkout script can be in one of three states. Knowing which one you're in tells you what's left to do:
| Scenario | What it means | What to do |
|---|---|---|
| Legacy script | The classic script that runs directly on the page using document, window, jQuery, or DOM manipulation. | Migrate it. Start with the Migration Guide . |
| Transition script | A partially migrated app: some behavior already runs through the SDK, but a legacy script still handles the rest (or is kept as a fallback). | Finish moving the remaining behavior to the SDK and remove the legacy dependency for anything already migrated. |
| Nube SDK script | Fully migrated. All behavior runs inside the SDK's Web Worker; no legacy script is needed. | Validate, homologate, and wait for the canary rollout (steps below). |
Don't run the same behavior twice
If you were maintaining a legacy or transition script, the moment a behavior is migrated to the SDK you must remove that behavior from the legacy script. Otherwise the same logic runs twice — leading to duplicated UI, conflicting events, or double-counted actions. The "Uses Nube SDK" flag is what tells the platform a script is an SDK script.
Steps after integrating with the SDK
Once your code is ready, follow these steps in order before asking for production activation:
1. Validate on a test store with the SDK flag
Request the SDK tag/flag for your test store so you can run your app in the new model in a self-service way — without waiting for the rollout to reach you.
👉 Request the SDK tag for your test store via the form
Validate the full behavior on all themes (storefront and checkout). Use the NubeSDK DevTools to confirm your app is registered and behaving as expected.
2. Remove the legacy-script dependency for the migrated behavior
For every behavior you moved to the SDK, remove it from the legacy/transition script (see the three scenarios above). The goal is that the migrated behavior is served only by the SDK script.
3. Open or update your homologation request
Submit your app for homologation — or, if your app already went through homologation before, update the existing request.
If your app was previously submitted and sent back for adjustments, the homologation team leaves your request on stand-by for the changes — you don't start a new request from scratch. Return through the same channel with the SDK adjustments applied, and the team revalidates.
4. Homologation validates the SDK
The homologation team verifies that the app is correctly built with the SDK. The homologation process itself doesn't change — the only addition is the check that your app uses the SDK.
5. Nuvemshop conducts the production rollout (canary)
Once your app is homologated, Nuvemshop enables the SDK behavior in production. This is gradual and monitored — see below.
How the production rollout works
Activation is gradual, monitored, and controlled by Nuvemshop
After homologation, Nuvemshop rolls out the SDK behavior in canary: it is enabled for a small set of stores first, monitored, and then progressively expanded.
The rollout is driven by risk criteria, monitoring, and rollback on our side. You don't enable it store by store, and you don't need to coordinate each store manually.
The progressive rollout is part of how all stores are being moved to the SDK model. For the broader timeline and deadlines, see the adoption notice in the Applications overview .
For the first cases and for critical apps, our team may follow a migration more closely. That closer accompaniment is not the standard process for every partner — the production flow is designed to scale through risk criteria, monitoring, canary, and rollback, rather than through individual manual coordination per app.
Before you request production activation
Use this checklist to confirm you're ready:
- App validated on a test store with the SDK flag, across all themes (storefront and checkout)
- "Uses Nube SDK" flag enabled on the script
- Legacy/transition script no longer runs any behavior already migrated to the SDK
- Production bundle uploaded and development mode disabled (see Getting Started → Deploy )
- Homologation request opened or updated, with the SDK adjustments applied
Once homologation approves your app, there's nothing more to switch on — Nuvemshop takes it from there with the canary rollout.
Useful resources
- Migration Guide — Convert legacy code to the SDK
- Getting Started — Build, test, and deploy your app
- DevTools — Inspect apps, events, and state on your test store
- Homologation overview — How homologation works
- Homologation requirements — The SDK requirement
- Applications overview — NubeSDK adoption — Deadlines and what changes
Need help? Contact api@tiendanube.com / api@nuvemshop.com.br .
Help us improve NubeSDK
Found an issue or have a suggestion? Let us know on GitHub.