What should I consider before switching from Classic to the course builder?
The considerations for moving an existing Embed builder integration from Classic to the course builder, including course type matching, your existing Classic content, and feature toggles.
If you already have the builder embeddable running in your product, switching to the course builder is a single configuration change: set options.legacy to false on the same endpoint you already call. The planning sits around that change rather than in it, because the course builder opens only courses built for it, and Classic opens only Classic courses.
What actually changes in your integration?
One flag. options.legacy selects which builder loads: omit it or set it to true for Classic, set it to false for the course builder.
Everything else stays where it is:
- The endpoint. Both builders load through the same builder embeddable with
action: "edit". - Issuance and auth. You generate a signed URL per user per page load exactly as you do now.
- User and tenant context.
identifierandclientIdentifierwork the same way. - Theming.
themeIdapplies to the embeddable in both. - Events. The embeddable emits
session:ready,session:error,session:expired,course:updated, andback.
Why does the course type have to match the builder?
Every course is either a Classic course or a course builder course, and the builder you load has to match the course you pass it. The course builder requires a course that is not Classic. Classic requires a Classic course.
When the two do not match, issuance rejects the request and no session is created. Player (view) embeds do not apply this gate, so a course that will not open in a given builder can still play for learners.
The practical implication is that your product needs to know which type a course is before it opens the builder. If you hold a single "edit this course" route today, it now needs to branch: Classic courses go to Classic, course builder courses go to the course builder.
If you omit courseId with legacy set to false, a blank course builder course is created for you when the session opens. That is the simplest way to give people a "create new course" entry point without pre-creating anything through the API.
What happens to your existing Classic courses?
Classic courses stay Classic and continue to open in Classic. Turning the course builder on for new content does not change or move existing content.
A course lives in the builder it was made in. You cannot currently move an existing Classic course into the course builder, and duplicating one gives you another Classic course rather than a way across. A migration mechanism is being worked on.
Plan for a period where both builders run side by side in your product, with Classic courses routed to Classic and new courses routed to the course builder.
Which features do you want to expose?
The course builder gives you toggles for the creation features your users see. Decide these deliberately, because several are on by default.
| Option | Default | What it controls |
|---|---|---|
ai | true | AI-powered features in the builder |
googleDrive | true | Google Drive import |
oneDrive | true | OneDrive import |
feedback | true | Course feedback screen |
publishing | false | Publish controls |
narrations | false | AI narrations |
translations | false | Translation features |
loom | false | Loom video recording |
options.back controls the back button, with event (emits the back event for you to handle), hidden, or native.
Two of these are worth extra thought. publishing determines whether your users control publishing or whether your platform does it for them, which is a product decision rather than a configuration one. ai and narrations draw on usage allowances, so turn them on knowing how your users will consume them.
How should you test the switch?
- Open the live demo in the developer docs and use the header toggle, which applies the same
legacyflag. This shows you the course builder without touching your own configuration. - Set
legacytofalsein a non-production tenant and open a course builder course end to end, including save and publish if you are exposing publishing. - Confirm your mismatch handling by passing a Classic
courseIdwithlegacyset tofalseand checking your integration handles the issuance rejection cleanly. - Listen for
session:errorand make sure it surfaces somewhere your team will see it.
Frequently asked questions
Can I run Classic and the course builder at the same time?
Yes. legacy is set per session, so your product can open Classic for one course and the course builder for another.
Do I need a new API key or a new endpoint?
No. Both builders load through the same embeddable and the same issuance flow.
What happens if I pass a Classic course to the course builder?
Issuance rejects the request and the session is not created. The same applies in reverse when a course builder course is passed to Classic.
Can I open the course builder without an existing course?
Yes. Omit courseId with legacy set to false and a blank course is created when the session opens.