Waymark SDK v3 migration guide

waymark-sdk-v3-migration.md

The upcoming 3.0.0 release of @waymark/waymark-sdk shifts the focus of our APIs away from the old template browser -> editor flow in favor of our new Waymark AI flow.

This version is not officially released yet, but can be installed with npm i @waymark/waymark-sdk@beta. Note although this is a beta build, API changes should be stable and bugs should be mostly eliminated at this point; a mainline release is coming very soon.

New Additions

• waymark.openWaymark() - Opens the Waymark AI flow
• New events: waymarkOpened and waymarkOpenFailed

Deprecations

Removes the following methods:

• waymark.getCollections()
• waymark.getTemplatesForCollection()
• waymark.openEditorForTemplate()

Removes the following editor config options:

• options.editor.backgroundColor (we are implementing this on our end in our custom Spectrum Reach theme)
• options.editor.hideSaveButton
• options.editor.orientation
• options.editor.panelButtons
• options.editor.labels.exitEditor
• options.editor.labels.completeVideo
• options.editor.labels.unsavedChangesConfirmation

All of this code in v2.8.0...

const collections = await waymark.getCollections();

const templates = await waymark.getTemplatesForCollection(collections[0].id);

waymark.openEditorForTemplate(templates[0].id);

Can simply be replaced with the following...

waymark.openWaymark();

From the Waymark AI view, the user is able to search for their business, generate a video, save it, and open that video in the editor without requiring any actions outside of the iframe.

You can still directly open existing saved videos in the editor via the waymark.openEditorForVideo() method as before.

Necessary changes to the Spectrum Reach Ad Portal

Note that this is based on assumptions about how the Spectrum Reach Ad Portal works, so it may not be a 1:1 exact reflection of how the migration will need to be done.

• Make the "Watch The Magic" button simply call waymark.openWaymark()
  • You can pass an options object to the openWaymark() method to provide an initial business name and city to search on, just as openEditorForTemplate() worked before:

  waymark.openWaymark({ businessName: "Waymark", businessCity: "Detroit" });

  • Note that in the near future, we will be moving to deprecate business name + city-based search in favor of a URL-based search. The transition should be as simple as just replacing the businessName and businessCity options with a businessURL option (or something similar)
• Remove all UI related to browsing and manually opening a template in the Waymark editor (ie, the "see more examples" button and "choose your template" view)
• In order to close the Waymark AI view and go back to a previous step, you must provide your own button in the Ad Portal UI which calls waymark.close()