Waymark Plugin — API Reference

This page contains documentation for all APIs available on the Waymark Class.

Waymark Class Constructor

The Waymark class constructor accepts 2 parameters:

• partnerID (string): Your Waymark-provided partner ID string
• options (Object): Optional configuration options

const waymark = new Waymark('partnerID', options);

Options

The following options can be provided in the Waymark constructor's options object:

environment

type: string | default "prod"

The name of the Waymark environment to use. Supported environment names are:

• "prod"
• "demo"

It is recommended to use the "demo" environment for development and testing, reserving "prod" for when your integration is ready to go live.

const waymark = new Waymark('partner-id', {
  environment: 'demo',
});

domElement

type: HTMLElement | optional

The target DOM element on the page which the Waymark UI iframe should be displayed in. If not provided, a <div> element will be appended to the end of the document body when the Waymark class is instantiated.

const waymark = new Waymark('partner-id', {
  domElement: document.getElementById('waymark-root'),
});

authMode

type: "jwt" | "uncontrolled" | default "jwt"

Defines how user authentication should be handled by the SDK.

Uncontrolled Mode

Uncontrolled mode means that all account management responsibilities will be contained within the Waymark UI; users will be presented with a login modal which they can use to create and log into their own Waymark account which they will manage themselves.

This can make integration easier, but comes with tradeoffs:

• You will not be able to provide a fully controlled white-labeled experience within your own product.
• You will have limited access to or control over the user's Waymark account info; all account methods will be disabled and will throw an error if called in uncontrolled mode.

JWT Mode

JWT mode means that you will be responsible for managing the following:

• Creating the user's Waymark account with the Waymark.createAccount method
• Storing the user's Waymark account ID in your database so they can be logged back into the account on subsequent visits
• Logging into the user's account via Waymark.loginAccount

The Waymark.createAccount and Waymark.loginAccount methods require account data to be encoded as a JSON Web Token (JWT) signed with a Waymark-provided secret key.

The other account methods, Waymark.logoutAccount, Waymark.getAccountInfo, and Waymark.updateAccountInfo, can also be used in JWT mode, but they but do not require any data to be encoded as a JWT.

You can learn more about JSON Web Tokens at https://jwt.io. Please also explore the numerous token creation SDKs for a wide selection of programming environments. Using a JWT SDK can greatly reduce your implementation time.

JSON Web Tokens have a 3 part structure, each part Base64URL-encoded and separated by periods, like so: "header.payload.signature"

The header will contain the algorithm and the type, typically "HS256" and "JWT", respectively:

{
  "alg": "HS256",
  "type": "JWT"
}

The payload will contain the information that you are signing and sending, and should have this structure:

{
  "jti": "unique ID for this JWT",
  "iss": "your Waymark partner ID",
  "aud": "waymark.com",
  "iat": issued-at timestamp,
  "exp": expiration timestamp,
  "...": ...
}

Where the elements are:

• jti: a unique ID for the JWT that will not collide with the ID of any other JWTs you send
• iss: the issuer (you), which is the Waymark-assigned partner ID we have given you
• aud: the audience (us), which is always "waymark.com"
• iat: the numeric timestamp indicating when this JWT was created
• exp: the numeric timestamp indicating when this JWT will expire: we recommend using a short timeout, 1 minute or so, and creating the JWT just before it is used.
• And then any additional payload information as dictated by the SDK operation you are calling.

The signature is created by concatenating the Base64URL-encoded header and payload, separated by a period, and then encoded using the Waymark-provided secret key.

This allows us to verify that you created the payload and that it hasn't been tampered with (or created wholesale by someone else).

editor

type: Object | optional

A configuration object which allows you to customize some aspects of how the Waymark editor is presented.

editor.labels.completeVideoConfirmation: An object which provides configuration options for an optional confirmation prompt modal that will pop up when a user clicks to complete their video in the Waymark editor.

const waymark = new Waymark('partner-id', {
  editor: {
    labels: {
      completeVideoConfirmation: {
        shouldShow: true,
        title: 'Finalize Video',
        body: 'By finalizing this video, you confirm that you own the rights to all of its content.',
        confirmButton: 'Confirm',
        cancelButton: 'Cancel',
      },
    },
  },
});

callbacks

type: Object | optional

An optional object of Waymark Plugin event callbacks, where the keys are event names and the values are callback functions which will be run when that event is emitted These callbacks can also be registered using Waymark.on.

isDebug

type: boolean | default false

Enables extra debugging console logs, useful for development.

const waymark = new Waymark('partner-id', {
  isDebug: true,
});

Account Methods

Methods used to manage the user's account.

createAccount

Creates a new Waymark account for a user and logs into it. An account is required in order for users to be able to interact with the app. If the user already has an account, you may log into it with Waymark.loginAccount.

If the user is already logged into an account when this is called, the SDK will automatically attempt to log the user out and then retry.

Parameters:

• createAccountToken (string): A signed JWT string with the following payload shape:

{
  "jti": "unique ID for this JWT",
  "iss": "your Waymark partner ID",
  "aud": "waymark.com",
  "iat": issued-at timestamp,
  "exp": expiration timestamp,
  "https://waymark.com/sdk/account": {
    "firstName": "Mabel",
    "lastName": "Tierney",
    "emailAddress": "mtierney@example.com",
    "companyName": "Tierney Auto, Inc.",
    "phone": "248-555-1212",
    "city": "Dearborn",
    "state": "MI",
    "externalID": "ABC123"
  }
}

All of these fields are optional, so you are not required to provide all of this information to "https://waymark.com/sdk/account" if you can't or do not want to.

The externalID field allows you to provide your own custom ID which you will be able to log into the account with if you would prefer that over using the Waymark account ID. If not provided in the payload, you will need to use the Waymark account ID.

Returns:

The Waymark.createAccount method returns a Promise which resolves to a string for the created Waymark account's ID.

If you are not using your own external ID, you will need to store this ID in order to be able to log the user back into their account with Waymark.loginAccount.

// It is highly recommended to do JWT signing on the backend to avoid exposing your Waymark Partner secret key.
const createAccountToken = KJUR.jws.JWS.sign(
  'HS256',
  JSON.stringify({
    alg: 'HS256',
    typ: 'JWT',
  }),
  JSON.stringify({
    jti: uuidv4(),
    iss: partnerID,
    aud: 'waymark.com',
    iat: KJUR.jws.IntDate.get('now'),
    exp: KJUR.jws.IntDate.get('now + 1hour'),
    'https://waymark.com/sdk/account': {
      firstName: 'Grace',
      lastName: 'Hopper',
      emailAddress: 'graceh@hopper.com',
      companyName: 'COBOL',
    },
  }),
  process.env.WAYMARK_PARTNER_SECRET_KEY,
);
const createdWaymarkAccountID = await waymark.createAccount(createAccountToken);

loginAccount

Logs the user into their existing Waymark account. You must create an account with Waymark.createAccount first if the user does not have an account already.

If the user is already logged into an account when this is called, the SDK will automatically attempt to log the user out and then retry.

Parameters:

• loginAccountToken (string): A signed JWT string with the following payload shape:

{
  "jti": "unique ID for this JWT",
  "iss": "your Waymark partner ID",
  "aud": "waymark.com",
  "iat": issued-at timestamp,
  "exp": expiration timestamp,
  "https://waymark.com/sdk/account": {
    "accountID": "waymark-account-id",
    "externalID": "your-external-id"
  }
}

You only need to provide one of accountID or externalID in the "https://waymark.com/sdk/account" payload.

• accountID is the user's Waymark account ID which is returned by Waymark.createAccount.
• externalID is the custom ID which you provided to Waymark.createAccount, if you prefer to use your own ID instead of using Waymark's. If you did not provide an external ID when creating an account, you will need to use accountID.

Returns:

The Waymark.loginAccount method returns a Promise which resolves to an Account object with details about the logged-in account.

// It is highly recommended to do JWT signing on the backend to avoid exposing your Waymark Partner secret key.
const loginAccountToken = KJUR.jws.JWS.sign(
  'HS256',
  JSON.stringify({
    alg: 'HS256',
    typ: 'JWT',
  }),
  JSON.stringify({
    jti: uuidv4(),
    iss: partnerID,
    aud: 'waymark.com',
    iat: KJUR.jws.IntDate.get('now'),
    exp: KJUR.jws.IntDate.get('now + 1hour'),
    'https://waymark.com/sdk/account': {
      externalID: request.user.guid,
    },
  }),
  process.env.WAYMARK_PARTNER_SECRET_KEY,
);
const accountDetails = await waymark.loginAccount(loginAccountToken);

logoutAccount

Logs the user out of their Waymark account.

Returns:

A Promise which resolves when the user has been successfully logged out.

await waymark.logoutAccount();

getAccountInfo

Fetches the account information for the current logged-in account. If no account is logged in, an error will be thrown.

Returns:

A Promise which resolves to an Account object with details about the logged-in account.

const accountDetails = await waymark.getAccountInfo();

updateAccountInfo

Updates Waymark's stored information for the current logged-in account. If no account is logged in, an error will be thrown.

Parameters:

• newAccountInfo (UpdatableAccountInfo): An object with any account info that you wish to update. Only fields which you provide values for will be updated. Note that this data does not need to be encoded as a JWT.

Returns:

A Promise which resolves to an Account object with the updated account details.

const updatedDetails = await waymark.updateAccountInfo({
  lastName: 'NewLastName',
  emailAddress: 'new@email.com',
});

Video Data Methods

Methods used to access information about that videos that the user has saved in their account.

getVideos

Fetches an array of all videos saved on the logged-in user's account.

Returns:

A Promise which resolves to an array of Video objects representing each video saved on the user's account.

If the user is not logged in, the array will be empty.

const videos = await waymark.getVideos();

getVideoData

Fetches the data for a single video by its ID.

Returns:

A Promise which resolves to a single Video object for the video matching the given ID.

If a video does not exist with that ID or the video does not belong to the logged-in user, the method will return null.

const videoData = await waymark.getVideoData('my-video-id');

Background Action Methods

Methods to start and track the progress of background actions. See Background Actions for more in-depth details on what background actions are and how to integrate them into your application.

startTopicSearch

Starts a topic search that will run in the background. The created topic will be saved to the logged-in account and may be re-used in later sessions.

An account must have been authenticated with Waymark.loginAccount or Waymark.createAccount in this session first or this method will throw an error.

Parameters:

• sourceUrl (string): A URL for a website whose content will be used as the source for a new topic.

Returns:

A Promise which resolves to an object with the following shape:

{
  /**
   * Unique ID representing the topic that has been created and will be populated with content
   * found at the provided source URL.
   */
  topicId: string;
  /**
   * Unique ID for this search request.
   */
  requestId: string;
}

// Create a new topic and populate it with content found on waymark.com
// This search will run in the background.
const { topicId } = await waymark.startTopicSearch('https://waymark.com');

subscribeToTopicSearchStatusUpdates

Subscribes to topic search status updates for a given topic ID returned from Waymark.startTopicSearch.

Parameters:

• topicId (string): The Topic ID returned from a Waymark.startTopicSearch call.
• callback ((statusUpdate: TopicSearchStatusUpdatePayload) => void): A callback which will be invoked when the topic search's status updates with a TopicSearchStatusUpdatePayload object.

Returns:

A cleanup callback which will unsubscribe from status updates.

const { topicId } = await waymark.startTopicSearch('https://waymark.com');
const unsubscribe = waymark.subscribeToTopicSearchStatusUpdates(topicId, ({ status, error }) => {
  switch (status) {
    case 'PROCESSING':
      // Perform an action when the topic search has started running
      break;
    case 'COMPLETE':
      // Perform an action when the topic search has completed
      break;
    case 'FAILED':
      // Perform an action if the topic search fails
      console.error(`The topic search failed with code ${error.code} and message ${error.message}`);
      break;
  }
});

startVideoGeneration

Starts a new AI video generation process that will run in the background. The created video will be saved to the logged-in account and may be accessed again in later sessions.

An account must have been authenticated with Waymark.loginAccount or Waymark.createAccount in this session first or this method will throw an error.

Parameters:

• videoGenerationParams (Object): An object with parameters describing the desired output for the video generation.
  • topicId (string): The ID of the topic that should be the subject of this video, returned from a prior Waymark.startTopicSearch call.
  • aspectRatio ("16:9" | "4:5"): The desired aspect ratio of the generated video.
  • duration (5 | 15 | 30): The desired duration of the generated video.
  • videoInstructions (string | optional): Optional additional instructions to include in the AI prompt for the video generation.
  • language (string | default "en-US"): Optional language code to influence the language and voiceover accent used in the generated video. Defaults to American English ("en-US") unless otherwise specified. See supported languages below for a full list of officially supported language codes.

Returns:

A Promise which resolves to an object with the following shape:

{
  /**
   * Unique ID for this generation request. This can be used to
   * preview the resulting generated video within the Waymark AI flow.
   */
  requestId: string;
  /**
   * Unique ID for the video saved to the logged-in account.
   * This can be used to open the generated video in the Waymark
   * editor once the generation has completed.
   */
  videoId: string;
  /**
   * The ID of the topic that the video is being generated for.
   * This should match the `topicId` parameter that was provided.
   */
  topicId: string;
}

// Make a 16:9, 30 second video about Waymark
const { topicId } = await waymark.startTopicSearch('https://waymark.com');
const { requestId } = await waymark.startVideoGeneration({
  topicId,
  aspectRatio: '16:9',
  duration: 30,
  language: 'en-US',
});

subscribeToVideoGenerationStatusUpdates

Subscribes to video generation status updates for a given request ID returned from Waymark.startVideoGeneration.

Parameters:

• generationRequestId (string): The request ID returned from a Waymark.startVideoGeneration call.
• callback ((statusUpdate: VideoGenerationStatusUpdatePayload) => void): A callback which will be invoked when the video generation's status updates with a VideoGenerationStatusUpdatePayload object.

Returns:

A cleanup callback which will unsubscribe from status updates.

const { requestId } = await waymark.startVideoGeneration(videoGenParams);
const unsubscribe = waymark.subscribeToVideoGenerationStatusUpdates(
  requestId,
  ({ status, error }) => {
    switch (status) {
      case 'PROCESSING':
        // Perform an action when the generation has started running
        break;
      case 'COMPLETE':
        // Perform an action when the generation has completed
        break;
      case 'FAILED':
        // Perform an action if the generation fails
        console.error(
          `The topic search failed with code ${error.code} and message ${error.message}`,
        );
        break;
    }
  },
);

UI Management and Cleanup Methods

Methods which manage the Waymark UI.

mount

Attaches the Waymark embed iframe to a given HTML element on the page. This may be necessary if you create a long-running Waymark instance which persists between views in a single-page application and need to mount the Waymark embed iframe on an element which was not available when the Waymark instance was first created.

Parameters:

• domElement (HTMLElement): The element that the Waymark embed iframe should be appended to as a child.
• isHidden (boolean | default false): Whether the iframe should be initially hidden with display: none when mounted. The iframe will automatically un-hide itself if you call a method to open a Waymark UI view (ie, Waymark.openWaymark, Waymark.openEditorForVideo)

Returns:

The Waymark.mount method returns a Promise which resolves when the iframe has successfully mounted and reconnected.

// Mount the Waymark instance's embed iframe on an element with id #waymark-embed-container
// and then call `waymark.openWaymark()` to open the Waymark AI page.
const waymarkEmbedContainer = document.getElementById('waymark-embed-container');
await waymark.mount(waymarkEmbedContainer);
waymark.openWaymark();

openWaymark

Opens the Waymark AI page in the plugin SDK's embedded iframe, with some portions of the UI modified for an improved embedded experience.

The user may then proceed through the flow to generate a video and open it in the editor.

Parameters:

• options (Object | optional): An optional options object
  • sourceUrl (string | optional): If provided, the Waymark AI flow will open on the initial search view with this URL auto-populated and will automatically immediately kick off a topic search. If not provided, the user will be able to type their URL into the seach form themselves.
  • topicId (string | optional): The ID for a topic created with a Waymark.startTopicSearch call. If provided, the Waymark AI flow will open on the video generation prompt input step with the given topic pre-selected.
  • generationRequestId (string | optional): The ID for a video generation request created with a Waymark.startVideoGeneration call. If provided, the Waymark AI flow will open on the final step to show a video preview of the generated video and allow the user to proceed to open it in the editor.
  • timeout (number | optional): The number of milliseconds to wait for the page to open before rejecting the returned promise.

Returns:

A Promise which resolves when the Waymark AI page has opened, or rejects if an error occurs or it takes longer than the duration provided in the timeout option.

// Open on blank search form
await waymark.openWaymark();
// Open with "https://mybusiness.com" pre-populated into search form and the search starting automatically
await waymark.openWaymark({
  sourceUrl: 'https://mybusiness.com',
});
// Open on video generation prompt form with a previously created topic pre-selected to use for the generation
await waymark.openWaymark({
  topicId: myTopicId,
});
// Open on final step to see a video preview of a previously created video generation
await waymark.openWaymark({
  generationRequestId: myRequestId,
});

openEditorForVideo

Opens a video in the Waymark Video Editor UI for an existing video saved on the user's account.

Parameters:

• videoID (string): The ID of the video to open
• options (Object | optional): An optional options object
  • timeout (number | optional): The number of milliseconds to wait for the page to open before rejecting the returned promise.

Returns:

A Promise which resolves when the editor page has opened, or rejects if an error occurs or it takes longer than the duration provided in the timeout option.

If a video does not exist for the given ID or the video does not belong to the logged-in user, this method will reject with an error.

await waymark.openEditorForVideo('my-video-id');

close

Closes whatever Waymark UI page is currently open and hides the Plugin SDK's embedded iframe. This will still keep the Plugin loaded in the background and the user will remain logged in if you need to do anything else.

If you wish to fully end the session and clean up all resources, use Waymark.cleanup instead.

Returns:

A Promise which resolves when the UI has closed.

await waymark.close();

cleanup

Closes the Waymark UI if it is open, logs the user out if the SDK is in JWT Mode, disconnects and destroys the iframe, and unregisters all event listeners.

It is recommended that you run this when you no longer need the Waymark plugin to help free up resources, for instance after closing the page which the Plugin is embedded on.

Returns:

A Promise which resolves when the UI has closed and all resources have been cleaned up.

useEffect(() => {
  // Clean up Waymark resources when this React component unmounts
  return () => waymark.cleanup();
}, []);

Event methods

Methods used to subscribe to and unsubscribe from client-side events emitted by the Waymark Plugin. See the client-side events page for details on all available events.

on

Adds an event listener for a Plugin event.

Params:

• eventName (string): The name of the event to add a listener for.
• callback (function): A callback function to run when the listener is emitted.

Returns:

A callback which will remove the event listener.

const unsubscribe = waymark.on('waymarkOpened', () => {
  console.log('The Waymark AI view has opened successfully');
});
// Calling the returned unsubscribe callback will remove
// the event listener
unsubscribe();

off

Removes an event listener.

Params:

• eventName (string): The name of the event to unsubscribe from
• callback (function): The callback to remove. Reference matters, so make sure this is the same function instance that you passed to Waymark.on.