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 able to create and log into their own Waymark account.

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.

Example:

// 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.

Example:

// 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');

UI Management and Cleanup Methods

Methods which manage the Waymark UI.

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
  • businessURL (string | optional): A business URL which the Waymark AI page will auto-populate into the brand search form and immediately kick off a search for that URL once the page has loaded. If not provided, the user will be able to type their business URL into the seach form themselves.
  • 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.

await waymark.openWaymark({
  businessURL: 'https://mybusiness.com',
});

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.