Waymark Plugin — Client-side Events

The Waymark Plugin emits a variety of client-side events which you may subscribe to to keep track of changes to the Plugin's state.

Subscribing to events

Events can be subscribed to in 3 different ways:

1. Events can be subscribed to with the Waymark.on method.

   waymark.on('waymarkOpened', () => {
     console.log('The Waymark AI view has opened successfully');
   });

2. Events are also emitted globally on the document where each event's name follows the format "waymark:<eventName>".

   document.addEventListener('waymark:waymarkOpened', () => {
     console.log('The Waymark AI view has opened successfully');
   });

3. Events can also be subscribed to by passing callbacks to the callbacks option in the Waymark constructor.

   const waymark = new Waymark('my-partner-id', {
     callbacks: {
       waymarkOpened: () => {
         console.log('The Waymark AI view has opened successfully');
       },
     },
   });

Event list

The Plugin may emit the following events:

waymarkOpened

type: CustomEvent<undefined>

Emitted when the Waymark AI view has successfully opened.

This will happen when:

• The Waymark AI view has opened after a Waymark.openWaymark call.
• The user has clicked the "Exit" button in the editor to return to the Waymark AI view.
  • Note that this is not applicable if the editor was directly opened via Waymark.openEditorForVideo.

waymarkOpenFailed

type: CustomEvent<Error>

Emitted when an error occurred while attempting to open the Waymark AI view with a Waymark.openWaymark call.

The event detail will be an Error object with details about the error which occurred.

A generic error event will be emitted along with this event as well.

editorExited

type: CustomEvent<undefined>

Emitted when the user exits the Waymark Editor, either by clicking the "Exit" button to close the editor or by finishing their video.

If the user clicked the "Exit" button:

• If the Editor was opened from the Waymark AI view, the Plugin will return back to the Waymark AI view again and a waymarkOpened event will also be emitted.
• If the Editor was opened directly via Waymark.openEditorForVideo, this means the user has ended their editing session and you should handle that accordingly, likely by calling Waymark.close().

If the user finished their video:

• This event will be emitted once, after the videoCompleted event. If the user finished several videos together, it is emitted once after all of their videoCompleted events. See Finishing several videos together.

editorOpened

type: CustomEvent<VideoData>

Emitted when the Waymark Editor has successfully opened for a video.

The event detail will be a VideoData object with details about the video which was opened in the editor.

This event will be emitted both when the Editor was opened directly via waymark.openEditorForVideo, or if the user opens a video in the Editor from the Waymark AI view.

editorOpenFailed

type: CustomEvent<Error>

Emitted when an error has occurred while attempting to open the Waymark Editor.

The event detail will be an Error object with details about the error which occurred.

This event will be emitted both if an error occurs when attempting to directly open the Editor via waymark.openEditorForVideo, or if an error occurs when the user tries to open a video in the Editor from the Waymark AI view.

A generic error event will be emitted along with this event as well.

videoCreated

type: CustomEvent<VideoData>

Emitted when the user saves a new video to their account.

The event detail will be a VideoData object with details about the video which was created.

This event will be emitted when the user clicks the "Edit & Continue" button in the Waymark AI flow to save a new video to their account and open it in the Editor.

videoSaved

Event type: CustomEvent<VideoData>

Emitted when Waymark saves changes to the user's video.

The event detail will be a VideoData object with details about the video which was saved.

This event will be emitted in the following scenarios:

• When a video is saved for the first time, alongside the videoCreated event

This event is not emitted when Waymark auto-saves changes in the editor, or when the user exits or finishes the video. To find out when a video is finished, listen for the videoCompleted event.

videoCompleted

type: CustomEvent<VideoData>

Emitted when a user has finished their video. Waymark will start rendering the video at this point.

The user finishes a video by clicking the "Next" button in the editor. If Variations are available for the video, the user can then choose "Just render this video", or generate other formats and finish several videos together. When several videos are finished together, one videoCompleted event is emitted for each video. See Finishing several videos together.

The event detail will be a VideoData object with details about the video which was completed.

Note that if a user re-opens a video which they have already completed and finishes it again without making any changes, Waymark will not kick off a new render.

videoRendered

type: CustomEvent<VideoData>

Emitted when a video belonging to the user's account finishes rendering.

The event detail will be a VideoData object with details about the video which rendered.

Waymark usually renders each completed video in more than one render format (email and broadcast_quality), and each render finishes at its own time, so you will usually receive more than one videoRendered event for a video. The event detail always includes every render for the video, each with its current status. An event is also emitted when a render fails, with a failed render status.

This event is only emitted while the Plugin is loaded on the page. If the user leaves the page, or you call Waymark.cleanup(), before rendering finishes, you won't receive it. Use webhooks if you need to know about every render.

error

Event type: CustomEvent<Error>

Emitted when any error occurs in the Plugin.

The event detail will be an Error object with details about the error which occurred.

Finishing several videos together

With Variations, a user can finish several versions of a video at once: the video they made, plus versions of it in other aspect ratios and durations. See How it works for what the user does.

Each video is completed and rendered individually. The other versions are created by Waymark rather than by the user, so you won't receive videoCreated or editorOpened events for them: the first event you receive for each of them is videoCompleted.

When the user finishes several videos together, the Plugin emits:

Every video finished together has the same pack value, so you can group them by pack.id, and use pack.size to know how many videos to expect. pack.index tells you each video's position in the pack, with the original video first.

A video finished on its own, including when the user picks only one video to finish, has the same events as before and a pack of null.