Introduction

Version 2.7.0

The Waymark JavaScript Integration SDK allows the Waymark Video Editing UI to be integrated within another site.

The SDK sets up an embedded iFrame within the page that will be used to display the UI. This iFrame is managed by the SDK, and it can be used to show and hide the Video Editor, search for templates by various attributes, and display and update user account information, among other things.

To use the SDK you will need to first set up a partner account with Waymark.

Installation

There are two ways to use the Waymark SDK: as a directly included JavaScript source file via a <script> tag, or as an NPM module imported into your own source code via a bundler such as WebPack or Rollup.

NPM package installation (Recommended Method)

The NPM package is named @waymark/waymark-sdk and may be installed like this:

npm install --save @waymark/waymark-sdk

Waymark automatically builds, tests, and releases new versions of the SDK as we finish functionality. See Versioning for more details.

JavaScript script tag include

The JavaScript file may be found at https://static.waymark.com/sdk/waymark-sdk.X.Y.Z.min.js, where X.Y.Z is the version number. This file is served from Waymark's CDN.

See Usage for details on initializing the Waymark SDK after loading the JavaScript library asynchronously.

Important note: This JavaScript file has several dependencies that are not yet loaded automatically.

Usage

There are two methods for including the Waymark SDK JavaScript code in your JavaScript application.

JavaScript module usage (Recommended)

We provide an npm package that makes it easier to load and use the Waymark SDK as a module. This usage requires using a JavaScript bundler such as WebPack or Rollup.

Import the Waymark SDK module directly in your client-side code.

import Waymark from "@waymark/waymark-sdk";
const waymark = new Waymark("partnerID", options);

See Waymark for details and options for initializing a Waymark integration class instance.

See Testing for using the built-in mock SDK testing harness.

JavaScript script tag usage

Create a function on the browser's window object named onWaymarkInit. This function will be called after the Waymark SDK JavaScript loads and initializes:

window.onWaymarkInit = function() {
    const waymark = new Waymark(partnerID, options);
}

See Waymark for details and options for initializing a Waymark integration class instance.

Authentication

Waymark-managed accounts

For partners that do not need to link their internal user accounts with Waymark's accounts.

For this option no authentication needs to be performed with the SDK. When the UI requires an authenticated account it will provide a means for the user to either create or login a Waymark account directly. These accounts will exist independently from the partner's system and such users will pay for their videos directly.

Single Sign On

For partners that wish to maintain accounts on their end linked transparently to a Waymark account.

Waymark needs to create a Waymark account for individual users that use our system. This account serves as a place to hold draft and completed videos, preferences and configuration, and payment information such as links to the partner's billing account. For partners that wish to maintain accounts on their end linked transparently to a Waymark account, we provide two means to do this via the SDK.

Option 1: JSON Web Token authentication

Waymark also provides a secure authentication option that requires the creation of signed tokens on the partner's servers that are then passed to the browser for authentication with the Waymark SDK.

The Waymark SDK uses a cryptographically signed JSON Web Token (JWT) to create and authenticate accounts that are maintained on the partner's side. The JWT consists of partner identification, the user's account information, and an expiry timestamp. The data is combined into the signed JWT and passed to the SDK to enable a Waymark UI session using the user's account.

NOTE: The JWT needs to be created on the partner's servers to avoid ever passing the Waymark-provided secret key to a user's browser.

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.

Constructing a JSON Web Token

JSON Web Tokens have a 3 part structure, each part Base64URL-encoded, and separated by periods:

  • header
  • payload
  • signature

Like this:

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 other payload information as dictated by the SDK operation you are calling.

A note on JWT timestamps: these are numeric values representing the number of seconds that have elapsed since 1970-01-01T00:00:00Z UTC to the given time, which is IEEE standard 1003.1. This can be either an integer or a floating point number containing fractional seconds.

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

Creating an account

To create an account we need to know the account details you would like us to receive, such as the name, email address, and so on. This information is passed to the Waymark SDK in the form of a signed JWT, using the partner's Waymark-provided API secret key. None of the fields are required but they can enhance some of the experience in the UI.

Use the Waymark.createAccount SDK method to create the new account, passing in a JWT with the account information.

If you provide an external account ID, it can be used during login instead of the Waymark account ID that will be returned from the Waymark.createAccount method.

Example JWT:

    {
        "jti": "ABCD-1234-ABCD-1234",
        "iss": "FEDC-9876-FEDC-9876",
        "aud": "waymark.com",
        "iat": 1606682057.470565,
        "exp": 1606682117.470565,
        "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"
        }
    }
Authenticating an existing account

To authenticate an existing account for a returning user, we need to know the partner ID and the Waymark account ID. This information is passed to the Waymark SDK in the form of a signed JWT, using the partner's Waymark-provided API secret key.

Use the Waymark.loginAccount SDK method to login the account, passing in a JWT with the account information.

Example JWT:

    {
        "jti": "ABCD-1234-ABCD-1234",
        "iss": "FEDC-9876-FEDC-9876",
        "aud": "waymark.com",
        "iat": 1606682057.470565,
        "exp": 1606682117.470565,
        "https://waymark.com/sdk/account": {
            "accountID": "CDEF-4567-CDEF-4567",
        }
    }

Option 2: API key authentication

For partners that want the simplest means of creating and logging in accounts via the SDK, Waymark provides a simple API key that can be used to authenticate the SDK. This key is passed into Waymark.createAccount and Waymark.loginAccount as the authorization token, and the account information is passed in as an additional parameter. No server side encoding or API calls are required to implement this authentication method.

NOTE: This authentication method is inherently insecure. The API key will be present in plain text within the browser application and can be extracted by users with sufficient knowledge. Waymark does not recommend using this authentication method, but it is provided as an easy means to get up and running with an integration.

Initializing the Waymark SDK

To use this authentication method, initialize the Waymark SDK with your API key as one of the options:

    // Via JavaScript `script` tag usage
    const options = {
      apiKey: "..........."
    }
    window.onWaymarkInit = function() {
      const waymark = new Waymark(partnerID, options);
    }

    // Via Javascript module usage
    import Waymark from "@waymark/waymark-sdk";
    const options = {
      apiKey: "..........."
    }
    const waymark = new Waymark('partnerID', options);

After initialization a new account may be created, or an existing account may be logged in.

Creating an account

To create an account we need to know the account details you would like us to receive, such as the name, email address, and so on. This information is passed to the Waymark SDK via the Waymark.createAccount method.

Example:

    // For API key authentication usage, initialize the Waymark SDK with the API key.
    // Then call createAccount() with the account information and wait for the update to complete.
    const waymark = new Waymark(partnerID, {apiKey: "..........."});
    const accountInfo = {
      firstName: "Mabel",
      lastName: "Tierney"
    }
    try {
      const accountID = await waymark.createAccount(accountInfo);
      console.log("Successful account creation. New ID:", accountID);
    } catch(error) {
      console.log(error);
    }
    // Alternative Promise syntax
    waymark.createAccount(accountInfo)
      .then((accountID) => {
        console.log("Successful account creation. New ID:", accountID);
      })
      .catch((error) => {
        console.log("Unsuccessful account creation.", error);
      });
Authenticating an existing account

To authenticate an existing account for a returning user, we need to know the partner ID and the Waymark account ID (or the external ID you provided when creating the account).

Use the Waymark.loginAccount SDK method to login the account, passing in an object with the account information.

Example:

    // For API key authentication usage, initialize the Waymark SDK with the API key.
    // Then call loginAccount() with the account information and wait for the login to complete.
    const waymark = new Waymark(partnerID, {apiKey: "..........."});
    const accountInfo = {
      accountID: "ABCD-1234-ABCD-1234"
    }
    // Or use the externalID that you provided when the account was created:
    const accountInfo = {
      externalID: "1234567890"
    }
    try {
      const await waymark.loginAccount(accountInfo);
      console.log("Successful account login.");
    } catch(error) {
      console.log("Unsuccessful login", error);
    }
    // Alternative Promise syntax
    waymark.loginAccount(accountInfo)
      .then(() => {
        console.log("Successful account login.");
      })
      .catch((error) => {
        console.log("Unsuccessful login", error);
      });

Data Types

Data Types

These data types are used by SDK methods and webhook responses.

Account:

{
  "id": "1234-ABCD-1234-ABCD",
  "externalID": "1234567890ABC",
  "createdAt": "2019-08-08T16:22:38.924635Z",
  "updatedAt": "2020-12-01T18:15:06.501702Z",
  "firstName": "Mabel",
  "lastName": "Tierney",
  "emailAddress": "mtierney@example.com",
  "companyName": "Tierney Auto, Inc.",
  "phone": "248-555-1212",
  "city": "Dearborn",
  "state": "MI"
}

Video Template Collection:

{
  "id": "ABCD-1234-ABCD-1234",
  "createdAt": "2019-08-08T16:22:38.924635Z",
  "updatedAt": "2020-12-01T18:15:06.501702Z",
  "name": "Hot And New",
  "templateCount": 12
}

Video Template:

{
  "id": "1234-BADC-BADC-1234",
  "createdAt": "2019-08-08T16:22:38.924635Z",
  "updatedAt": "2020-12-01T18:15:06.501702Z",
  "name": "GridLines",
  "aspectRatio": "16:9",
  "duration": 30,
  "height": 1080,
  "width": 1920,
  "licensing": "tv",
  "previewVideoURL": "https://d162temrdha55f.cloudfront.net/web_video/renderedvideo/render/84557.mp4?c=1606864506.501702",
  "thumbnailImageURL": "https://socialproof-prod.imgix.net/video_creatives/videotemplatevariant/thumbnail/515_1565888096.png?ixlib=python-3.1.2"
}

Video:

{
  "id": "1234-ABCD-1234-ABCD",
  "createdAt": "2019-08-08T16:22:38.924635Z",
  "updatedAt": "2020-12-01T18:15:06.501702Z",
  "isPurchased": false,
  "name": "A Video About Cars",
  "templateID": "1234-ABCD-1234-ABCD",
  "renders": [
    {
      "renderedAt": null,
      "format": "broadcast",
      "url": "",
      "status": "in_progress"
    },
    {
      "renderedAt": "2020-12-01T18:15:06.501702Z",
      "format": "email",
      "url": "https://x.y.z/12345.mp4",
      "status": "succeeded"
    }
  ]
}

Status values for video renders are:

  • initial: the video rendering process has not been started
  • in_progress: the video is currently rendering
  • succeeded: the video has been successfully rendered
  • failed: the video was not successfully rendered
  • aborted: the video rendering process was stopped manually

Events

The SDK will emit events as certain things happen in the application. These can be subscribed to and processed by the host application to react to the events.

Subscribing

There are two means of subscribing:

  1. Pass a list of callbacks to the Waymark object constructor
  2. Use the on() method to subscribe to a single event

Examples:

Using callbacks:

// The account is logged in via the createAccount() or loginAccount() methods.
const options = {
  callbacks: {
    editorExited: () => {
      console.log("The user exited the editor");
    },
    editorOpened: () => {
      console.log("The editor opened");
    },
    editorOpenFailed: (error) => {
      console.log("The editor failed to open");
    },
    videoCompleted: (video) => {
      console.log("A video was completed:", video);
    },
    videoCreated: (video) => {
      console.log("A video was created:", video);
    },
    videoRendered: (video) => {
      console.log("A video was rendered:", video);
    },
    videoSaved: (video) => {
      console.log("A video was saved:", video);
    }
  },
  [... other options]
};
const waymark = new Waymark('partnerID', options);

Using the on() method:

const waymark = new Waymark('partnerID', options);
waymark.on('videoCreated', (video) => {
  console.log("A video was saved:", video);
});

Events

  • editorExited(): the user has exited the editor
  • editorOpened(): the editor has successfully opened
  • editorOpenFailed(error): the editor failed to open successfully due to an error
  • videoCompleted({VideoObject}): the user has completed a video
  • videoCreated({VideoObject}): the user has created a video and saved it for the first time
  • videoRendered({VideoObject}): a completed video has finished rendering
  • videoSaved({VideoObject}): the user has saved a video (this will also be called on creation)

Versioning

The Waymark SDK follows Semantic Versioning protocols.

Our version numbers are of the form MAJOR.MINOR.PATCH (eg. 1.4.2).

Given a version number MAJOR.MINOR.PATCH, Waymark will increment the:

  1. MAJOR version when we make incompatible API changes,
  2. MINOR version when we add functionality in a backwards compatible manner, and
  3. PATCH version when we make backwards compatible bug fixes.

Waymark recommends pinning the Waymark SDK version that you use in your package.json so that your build system does not automatically pull down major version revisions, since those are not backwards compatible.

Webhooks

You can configure webhook endpoints to be notified about events that happen to accounts tied to your partner account. Webhooks are used for asynchronous events like the completion of a video render.

What are webhooks

Webhooks are HTTP endpoints that you create on your own servers to receive notifications when something happens with your partner account. You can determine what you want the URL to be to receive Waymark webhook events and we will call it with a POST request containing a Waymark event object in JSON form.

When to use webhooks

Webhooks should be used when you need to guarantee that you receive notice of events whether the account in question is currently active in a browser application or not. For example, video rendering can take several minutes depending on the complexity of the video template. If your user edits a video, completes it, and then closes the browser before Waymark has finished the rendering of the new video, you will need a webhook to receive the notification that the render has been completed.

Receiving a webhook event

Webhooks should return a 2XX HTTP status code as soon as the event is successfully received. If Waymark attempts a webhook request and the response code is anything other than a 2XX status (including redirects or other 3XX status codes), we will attempt the repeat the request after a short timeout. After repeated failures we will mark the event as failed and stop trying to send it to your webhook endpoint.

If your webhook endpoint fails repeatedly, Waymark may disable it after a period of time.

Event handling

Duplicates

On occasion, an event may be sent to a webhook more than once. Please structure your handling code such that repeated events will be ignored. This can be accomplished by logging the webhook event ID and not processing events that have already been seen.

Ordering

Waymark does not guarantee that webhooks will arrive in any particular order.

Security

Making sure that only Waymark can call your webhook endpoints is important to protect your users' information.

Webhook verification

Waymark can sign each webhook event using your API webhook secret to allow you to confirm that it is a valid request. Signing of webhook requests is optional but recommended.

If you wish to have webhook events signed, please contact your Waymark account representative.

HTTPS

Using HTTPS on your webhook endpoints will prevent others from snooping the webhook event data.

Events

Each event payload consists of a header section that contains information about the event itself and the account that generated the event, and a data section that contains the actual event data.

Unsigned Events

Unsigned events are posted as a JSON string and will have a content type of application/json:

{
   "header": {<the header section data object>},
   "data": {<the individual event data as described for each event>}
}

Header

  • eventID: (string) - The unique ID of the event.
  • eventType: (string) - The type of event as noted below.
  • eventTimestamp: (string) - A UTC timestamp.
  • accountID: (string) - The account ID associated with the event.
  • externalID: (string) - If you have provided an external ID to associate with an account then we will include it here.
{
  "eventID": "1234-ABCD-1234-ABCD",
  "eventType": "video.rendered",
  "eventTimestamp": "2019-08-08T16:22:38.924635Z",
  "accountID": "1234-ABCD-1234-ABCD",
  "externalID": "<partner provided ID>"
}

Event types

Video Completed

Event type: video.completed

This webhook event will be sent whenever a video is completed (purchased) by an account. The data will consist of a video object.

{
  "id": "1234-ABCD-1234-ABCD",
  "createdAt": "2019-08-08T16:22:38.924635Z",
  "updatedAt": "2020-12-01T18:15:06.501702Z",
  "isPurchased": true,
  "name": "A Video About Cars",
  "templateID": "1234-ABCD-1234-ABCD",
  "renders": []
}

While the SDK will also send this event, the webhook should be considered more reliable as it does not require the user to be actively using a Waymark UI session to receive it.

Video Rendered

Event type: video.rendered

This webhook event will be sent whenever a video completed by an account has finished rendering. The data will consist of a video object.

Of note is the behavior of multiple renders. Waymark will render a new video in both email and TV broadcast quality formats. You may receive multiple render events because each of these renders may complete at different times. When this happens both renders will be present, each with a potentially different status.

{
  "id": "1234-ABCD-1234-ABCD",
  "createdAt": "2019-08-08T16:22:38.924635Z",
  "updatedAt": "2020-12-01T18:15:06.501702Z",
  "isPurchased": true,
  "name": "A Video About Cars",
  "templateID": "1234-ABCD-1234-ABCD",
  "renders": [
    {
      "renderedAt": "2019-08-08T16:22:38.924635Z",
      "format": "broadcast",
      "url": "https://x.y.z/12345.mov",
      "status": "succeeded"
    },
    {
      "renderedAt": "2019-08-08T16:22:38.924635Z",
      "format": "email",
      "url": "https://x.y.z/12345.mp4",
      "status": "in_progress"
    }
  ]
}

Status values for video renders are:

  • initial: the video rendering process has not been started
  • in_progress: the video is currently rendering
  • succeeded: the video has been successfully rendered
  • failed: the video was not successfully rendered
  • aborted: the video rendering process was stopped manually

While the SDK will also send this event, the webhook should be considered more reliable as it does not require the user to be actively using a Waymark UI session to receive it.

Account Created

Event type: account.created

This webhook event will be sent whenever a new account is created for a user associated with your partner account. The data will consist of an account object.

{
  "id": "1234-ABCD-1234-ABCD",
  "firstName": "Mabel",
  "lastName": "Tierney",
  "emailAddress": "mtierney@example.com",
  "companyName": "Tierney Auto, Inc.",
  "phone": "248-555-1212",
  "city": "Dearborn",
  "state": "MI"
}

Generally this event will only be of interest to partners that enable Waymark account creation via the Waymark UI.

Signed Events

Signed events will be posted as a JSON Web Token (JWT) that is signed using your Waymark-provided secret key and will have a content type of application/jwt.

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

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

The payload will contain the webhook event and will have this structure:

    {
        "jti": "unique ID for this JWT",
        "iss": "waymark.com",
        "iat": issued-at timestamp,
        "exp": expiration timestamp,
        "https://waymark.com/webhook/event": {
          // This will be the unsigned event as described above
        }
    }

Testing

Mock Test Harness

The SDK includes a standalone mock version of the SDK that can be used to test your host application without a live connection. This test harness does not require a connection to the Waymark application, nor does it require a valid partner ID.

Initializing a Mock SDK Instance

The test harness is invoked like a live instance but importing the class as a named export and using the TestModeWaymark class instead:

    import { TestModeWaymark } from "@waymark/waymark-sdk";
    const waymark = new TestModeWaymark('fakePartnerID', options);
JWT Authentication

The test harness uses a JWT key of test-secret. The TestModeWaymark.createAccount and TestModeWaymark.loginAccount methods will expect that the JWT parameter is signed with this key. The partnerID that is used to initialize the TestModeWaymark object will also be used to validate the JWTs.

We use the jsrsasign JavaScript package for client-side testing purposes.

    const privateKey = "test-secret";
    const partnerID = "fakePartnerID";
    const accountData = {
        "firstName": "Mabel",
        "lastName": "Tierney",
        "emailAddress": "mtierney@example.com",
        "companyName": "Tierney Auto, Inc.",
        "phone": "248-555-1212",
        "city": "Dearborn",
        "state": "MI",
        "externalID": "ABC123"
    };

    import { TestModeWaymark } from "@waymark/waymark-sdk";
    const waymark = new TestModeWaymark(partnerID, options);

    // Header
    const header = { alg: 'HS256', typ: 'JWT' };

    // Payload
    const payload = {
      jti: uuidv4(),
      iss: partnerID,
      aud: "waymark.com",
      // Create integer dates using jsrsasign
      iat: KJUR.jws.IntDate.get("now"),
      exp: KJUR.jws.IntDate.get("now + 1hour"),
      "https://waymark.com/sdk/account": accountData,
    };

    // Sign JWT with our secret using jsrsasign. This should be done on the
    // server but is shown here to demonstrate using the test harness.
    const signedJWT = KJUR.jws.JWS.sign(
      "HS256",
      JSON.stringify(header),
      JSON.stringify(payload),
      privateKey,
    );

    await waymarkInstance.createAccount(signedJWT);

NOTE: This authentication method is inherently insecure and is shown for demonstration purposes only. The API key will be present in plain text within the browser application and can be extracted by users with sufficient knowledge. Waymark does not recommend using this authentication method, but it is provided as an easy means to get up and running with an integration. See Authentication for more details.

The details of the account passed in via TestModeWaymark.createAccount will be returned if the TestModeWaymark.getAccountInfo method is called.

Opening The Mock Application

Calling any SDK method that shows the application (such as openEditorForTemplate()) will create an iframe with a test application. This application will show basic controls that will mimic the operation of the real application.

    try {
      // Open the editor with the provided variant ID
      await waymark.openEditorForTemplate(variantID);

      console.log('Successfully opened editor!');
    } catch (error) {
      console.error(error);
    }
Error Testing

Many of the SDK calls may be forced to provide an error response for testing purposes.

Event Behavior

The test harness tool will send one videoRendered event 4 seconds after purchase and a second event 5 seconds after purchase. Each event will contain 2 render records and in the first event one render record will still be in_progress.

Example Application

Waymark has published an example developer tool React application that uses the test harness at stikdev/waymark-sdk-tool.

Changelog

2.7.0 (2021-08-26)

Docs

  • Add a page for Events and perform some minor cleanup (4792109)

New

  • Add the videoSaved event (9e2f56a)

2.6.0 (2021-06-11)

Chore

  • Fix CircleCI not installing the local SDK version correctly (bced8de)

Docs

  • Update docs to reflect that duration on template objects is a number, not a string (bcfaee5)
  • Update documentation to include isPurchased flag on videos (189282a)

New

  • Add support for filter param on getTemplatesForCollection (d8fde55)

2.5.0 (2021-05-13)

Update

  • remove requirement for email address in account creation. (622beda)

2.4.0 (2021-04-22)

Docs

  • Add some link targets for publishing deep links into the documentation. (9f4dd0c)

New

  • Add an option for instrumenting the SDK with debug logging. (3c568fb)

2.3.0 (2021-04-16)

New

  • add customizable background color to editor options. (b8e5a0a)

2.2.0 (2021-04-02)

Chore

  • Add end-to-end test for purchasing with the complete video modal (589b171)

Update

  • add externalID to baseAccountInfoProperties. (2bb63db)

2.1.0 (2021-03-26)

Update

  • Add support for configuring editor complete confirmation modal (668d5aa)

2.0.0 (2021-03-24)

Breaking

  • add waymark-sdk-tool to circleci config and delete tool. (7a88d25)

Chore

  • Upgrade to husky 5, add commitlint (9b4266c)

Update

  • PR cleanup. (66b4d66)
  • test editor options menu. (fe2ec29)
  • test unsaved changes modal. (5a08027)
  • write test for example site navigation. (c1b0cb6)
  • write test for full purchase flow. (08c52af)
  • write test to ensure account info persists. (204f8f2)

1.15.0 (2021-03-23)

Docs

  • Add more links to documentation and other cleanup (eb299b4)

Update

1.14.0 (2021-03-22)

Docs

  • Fix documentation for personalization.isDefault (778898f)
  • Publish changelog as part of the documentation. (a4214fc)

Update

  • switch local host environment to https. (5d6fc22)

1.13.0 (2021-03-19)

Update

  • Add support for panelButtons.shouldUseAdvancedDropdown option (4bb45f0)

1.12.0 (2021-03-17)

Docs

  • Clarify where the template ID in openEditorForTemplate comes from. (a2c870d)
  • Correct video render data type for in_progress renders. (581785e)
  • loginAccount now resolves with the Account information. (0ce0384)

Fix

  • increase getCollections test wait time. (ae06507)

Update

  • add hideSaveButton editor option. (1e3254f)

1.11.3 (2021-03-11)

Fix

  • allow for empty state values in createAccount payload. (702778e)

1.11.2 (2021-03-11)

Fix

  • Enable opening the renderer in full screen from inside the iframe (7ea49bf)

1.11.1 (2021-03-10)

Fix

  • Fix problem with detecting logged-in account. (e599afd)

1.11.0 (2021-03-09)

Docs

  • Update Account data type documentation. (b267ac5)

Update

  • Logout existing accounts when cleaning up the SDK. (e8a23c3)

1.10.0 (2021-03-05)

Update

  • Add ExistingLoginError to SDK error classes. (0ad6209)

1.9.2 (2021-03-05)

Fix

  • Replace test harness video URLs with real videos (3d381d9)

1.9.1 (2021-03-05)

Fix

  • Clean up FrameCommunicator when SDK.cleanup is called. (c76002d)
  • Log out existing user when createAccount or loginAccount is called. (e23828e)
  • Send token with createAccount and loginAccount (b8b1a4e)

1.9.0 (2021-03-04)

Update

  • pass partnerID into createAccount and login calls. (ec3f809)

1.8.2 (2021-03-04)

Fix

  • Inject iframe styling for responsiveness upon element creation. (e113d9f)

1.8.1 (2021-03-04)

Fix

  • Add partner ID to initial SDK URL (4affa6d)

1.8.0 (2021-03-04)

New

  • Add validator support and documentation for unsavedChangesConfirmation (baf1075)

1.7.0 (2021-03-02)

Update

  • add customHost field to Waymark options. (8981e1d)
  • combine customHost and environment options. (bb1a07c)
  • ensure host is null for TestModeWaymark instances. (a0f010a)

1.6.0 (2021-02-26)

Docs

  • Add editor.personalization to documentation (fa20aef)

Update

  • change 'is_default' to 'isDefault' (4548f8c)

1.5.1 (2021-02-25)

Build

  • Do not run the documentation deploy if semantic-release didn't create a new version. (db14461)

Docs

  • Update the webhook documentation with content types. (08920ca)

Fix

  • Build the documentation with the proper version number. (74bef6a)

1.5.0 (2021-02-24)

Update

  • Remove videoName editor label (b4d7230)

1.4.1 (2021-02-23)

Build

  • Run the documentation generation from within semantic release. (2efafe3)

Docs

  • Incorporate the new version number in the documentation. (752f9d5)

Fix

  • Update the release version for the scripts to use even if there is no release. (19d8383)

1.4.1-beta.1 (2021-02-22)

Build

  • Run the documentation generation from within semantic release. (2efafe3)

Docs

  • Incorporate the new version number in the documentation. (752f9d5)

Fix

  • Update the release version for the scripts to use even if there is no release. (19d8383)

1.4.0 (2021-02-22)

Chore

  • Update date formats in documentation and unit tests. (eba773a)

Docs

  • Remove some internal functions from the public documentation and change the order. (6918d01)

New

  • Add the video render status to videoRendered events and video.rendered webhooks. (b646d61)

1.3.0 (2021-02-18)

Build

  • Add Prettier JavaScript formatting at commit time (e509419)
  • Use fully specified repository entry in package.json (356c646)

Chore

  • Add unit tests for FrameTranslator (f21b70f)

Docs

  • Add signed webhook documentation section and update date formats in examples (871b173)
  • Added "Testing" section (cf8ce76)
  • Update webhook signature documentation (401320a)

Update

  • Add FrameTranslator (a2a736d)
  • Build and release documentation with npm module. (5d500df)
  • Export custom error classes so they can be used in the child frame (b76808d)
  • Make iframe src use 'mode=embed' query param (37209a2)
  • Replace penpal event callback methods with sendEvent (98eb45b)
  • toggle iframe visibility in test harness. (f55c5c0)

1.2.4 (2021-02-08)

Fix

  • Make npm package access public. (d4e6e18)

1.2.3 (2021-02-08)

Fix

  • Only commit changed assets for semantic release (a8ec8b5)

1.2.2 (2021-02-08)

Fix

  • Correct use of assets in semantic-release git plugin (2c1e42b)

1.2.1 (2021-02-08)

Fix

  • Change build order for npm publish (1181e1a)

1.2.0 (2021-02-08)

Build

  • Add circleci build script (77ee3c9)
  • Add test:release and rename npm test commands from 'tests:' to 'test:' (b561142)
  • Add TestCafe and TestCafe linter plugin (b495167)
  • Ensure latest SDK is installed for developer tool during tests (3bc06a5)
  • Install canvas npm package for running Jest DOM tests (d4452ec)
  • Make circleci aware of test results (9109c48)
  • Release and documentation build and deploy scripts (cdefba5)
  • Run the proper release tests (e867071)
  • Skip developer tool tests for now (b5b6740)
  • Start background HTTP server for end-to-end tests (b5aa54a)

Chore

  • Add coverage to gitignore (93c779e)
  • Add unit tests covering a majority of the SDK as it currently exists (651a6ab)
  • Add npm run tests:release for automated SDK tests (160f7d7)
  • Add ability to destroy embedded iframe in developer tool (027fcda)
  • Add CSS selector targeting to developer tool (15a25ff)
  • Add end-to-end tests for opening the test harness editor (affc0fa)
  • Add hide/show performance stats button (c28f309)
  • Add visual status for initialized SDK in developer tool (129e9a8)
  • Don't load the GPU task app until it's called for. (c507d92)
  • getCollections and getTemplatesForCollections test harness tests (e205243)
  • Increase collection tests wait for response (cba401f)
  • Move the frame to the top of the page for easier use. (e8ec518)
  • Rename General end-to-end tests to Editor (eee2d6c)

Docs

  • Add notes to example automated test (a9e9cc5)

Fix

  • Add YAML converter to rollup config. (0103271)

New

  • Add cleanup functionality to SDK instances (18b35e6)
  • Environment configurations. (4950383)

Update

  • Minor validation cleanup, add initial unit tests for SDK constructor (83bc89f)
  • Various fixes and improvements to the SDK from unit test fallout (efcf47c)

1.2.0 (2021-02-08)

Build

  • Add circleci build script (77ee3c9)
  • Add test:release and rename npm test commands from 'tests:' to 'test:' (b561142)
  • Add TestCafe and TestCafe linter plugin (b495167)
  • Ensure latest SDK is installed for developer tool during tests (3bc06a5)
  • Install canvas npm package for running Jest DOM tests (d4452ec)
  • Make circleci aware of test results (9109c48)
  • Release and documentation build and deploy scripts (cdefba5)
  • Run the proper release tests (e867071)
  • Skip developer tool tests for now (b5b6740)
  • Start background HTTP server for end-to-end tests (b5aa54a)

chore

  • add coverage to gitignore (93c779e)
  • Add unit tests covering a majority of the SDK as it currently exists (651a6ab)

Chore

  • Add npm run tests:release for automated SDK tests (160f7d7)
  • Add ability to destroy embedded iframe in developer tool (027fcda)
  • Add CSS selector targeting to developer tool (15a25ff)
  • Add end-to-end tests for opening the test harness editor (affc0fa)
  • Add hide/show performance stats button (c28f309)
  • Add visual status for initialized SDK in developer tool (129e9a8)
  • Don't load the GPU task app until it's called for. (c507d92)
  • getCollections and getTemplatesForCollections test harness tests (e205243)
  • Increase collection tests wait for response (cba401f)
  • Move the frame to the top of the page for easier use. (e8ec518)
  • Rename General end-to-end tests to Editor (eee2d6c)

Docs

  • Add notes to example automated test (a9e9cc5)

Fix

  • Add YAML converter to rollup config. (0103271)

New

  • Add cleanup functionality to SDK instances (18b35e6)
  • environment configurations. (4950383)

update

  • minor validation cleanup, add initial unit tests for SDK constructor (83bc89f)
  • Various fixes and improvements to the SDK from unit test fallout (efcf47c)

1.1.0 (2021-02-03)

Build

  • Add a developer test harness tool (df1e875)
  • add autoExternal and transform-runtime to Rollup (7359245)
  • Check licenses for Waymark SDK compatibility (resolves: CU-hgv6g2) (6a1a8b7)
  • Exclude documentation and package*.json from npm module. (accf634)
  • move package files to sdk subdirectory (d0a8d0f)
  • Remove duplicate .gitignore and ignore .eslintcache (63f9450)
  • Update package-lock.json for a rebase after move (2930ded)

Docs

  • Add data type docs and editor.personalization.is_default option. (c0ceea1)
  • Add new editor events to documentation and make validation methods private (102127e)

Fix

  • Allow automated tests to maniplate the iframe (be1ba5c)
  • Carry event name changes through to test harness HTML (84e72b5)
  • ensure errors bubble up through penpal correctly (4a48499)

New

  • implement onWaymarkInit hook. (b6b82dd)

Update

  • Add full coverage for basic param validation (8cab12e)
  • Add pixiJS to developer tool packages (6a92d21)
  • add test harness support for getAccountInfo, updateAccountInfo, getVideos, openSavedVideos, and close (ff68c65)
  • Normalize the event naming scheme (5ccd4e5)

1.0.0 (2021-01-13)

Build

  • adds rollup and semantic versioning configuration (91bf1d2)

New

SDK Documentation

The Waymark SDK is used within a browser application to provide access to the Waymark UI.

Waymark

The Waymark integration class.

new Waymark(partnerID: string, options: Object?)
Parameters
partnerID (string) The Waymark-provided partner ID
options (Object? = {}) Optional parameters
Name Description
options.apiKey string? Required only if using the insecure API key authentication method
options.callbacks Object? An optional object containing callback functions keyed by the name of the Waymark event. These callbacks can also be added using Waymark.on
options.domElement DOMElement? An optional DOM element on the page that will serve as the container for the Waymark UI. If not provided then an element will be appended to the end of the document the first time a UI method is called.
options.environment (string | Object)? An environment (host) name or custom environment object with a defined host. Valid environment names are "demo", "prod", and "local", default is "demo". Custom environment object should be structured as { host: ' https://localhost:8080 ' }.
options.editor Object? Optional editor configuration.
options.editor.backgroundColor string? Valid CSS color that will be applied behind the editor's video player and editing panel.
options.editor.hideSaveButton boolean (default false) if the 'SAVE' button should be hidden in the editor. In this case, the video is automatically saved on purchase.
options.editor.orientation string (default left) "left" will place the video player on the left and the editor form on the right; "right" will reverse this orientation.
options.editor.panelButtons Object? Optional configuration for the editor's panel buttons.
options.editor.panelButtons.shouldUseAdvancedDropdown boolean (default false) Whether the editor's panel buttons should be placed in an "Advanced Options" dropdown at the bottom of the editor form.
options.editor.personalization Object? Optional configuration for the editor's personalization flow.
options.editor.personalization.isDefault boolean (default false) "true" will open the editor with the personalization flow opened. "false" will open the editor in the default form view. This option only applies to openEditorForTemplate calls.
options.editor.labels Object? Override labels within the editor.
options.editor.labels.exitEditor string (default "Exit") The "Exit" button label.
options.editor.labels.completeVideo string (default "Buy") The "Buy" button label.
options.editor.labels.completeVideoConfirmation Object? Configuration for an optional confirmation modal that will pop up when the user clicks the complete button.
options.editor.labels.completeVideoConfirmation.body string (default "By finalizing this video, you confirm that you own the rights to all of its content.") The body text of the confirmation modal.
options.editor.labels.completeVideoConfirmation.confirmButton string (default "Confirm") The label for the modal's confirmation button which will proceed to complete the video.
options.editor.labels.completeVideoConfirmation.cancelButton string (default "Cancel") The label for the modal's cancel button which will close the modal.
options.editor.labels.completeVideoConfirmation.shouldShow boolean (default false) Whether the editor should show a confirmation modal when the user clicks the complete button.
options.editor.labels.completeVideoConfirmation.title string (default "Finalize Video") The title to display at the top of the confirmation modal.
options.editor.labels.unsavedChangesConfirmation Object? Configuration for the confirmation modal that will pop up if the user attempts to close the editor with unsaved changes.
options.editor.labels.unsavedChangesConfirmation.body string (default "Your video has unsaved edits. Are you sure you want to leave?") The body text of the confirmation modal.
options.editor.labels.unsavedChangesConfirmation.confirmButton string (default "Exit editor") The label for the confirmation button which will proceed to close the editor without saving.
options.editor.labels.unsavedChangesConfirmation.cancelButton string (default "Cancel") The label for the cancel button to close the confirmation modal.
options.editor.labels.unsavedChangesConfirmation.shouldShow boolean (default true) Whether the editor should show a confirmation modal if the user attempts to close the editor with unsaved changes.
options.editor.labels.unsavedChangesConfirmation.title string (default "Exit Editor") The title to display at the top of the confirmation modal.
options.isDebug boolean (default false) Enables extra debugging console logs.
Throws
  • InvalidParameterError: Thrown if:
    • A partner ID was not provided.
    • options.editor is incorrectly configured.
    • Invalid events are provided in options.callbacks.
    • Operation payloads are incorrect (number instead of string, etc.) or incomplete.
    • Invalid environment key.
Example
// The account is logged in via the createAccount() or loginAccount() methods.
const options = {
  callbacks: {
    editorExited: () => {
      console.log("The user exited the editor");
    },
    editorOpened: () => {
      console.log("The editor opened");
    },
    editorOpenFailed: (error) => {
      console.log("The editor failed to open");
    },
    videoCompleted: (video) => {
      console.log("A video was completed:", video);
    },
    videoCreated: (video) => {
      console.log("A video was created:", video);
    },
    videoRendered: (video) => {
      console.log("A video was rendered:", video);
    },
    videoSaved: (video) => {
      console.log("A video was saved:", video);
    }
  },
  editor: {
    orientation: "right",
    labels: {
      exitEditor: "Cancel",
      completeVideo: "N
  ",xx
}
  },
  environment: "prod",
}
const waymark = new Waymark('partnerID', options);
Static Members
init()
Instance Members
getCollections()
getTemplatesForCollection(collectionID, filter)
createAccount(accountInfo)
loginAccount(accountInfo)
logoutAccount()
getAccountInfo()
updateAccountInfo(newAccountInfo, data)
getVideos()
openEditorForVideo(videoID)
openEditorForTemplate(templateID)
openSavedVideos()
close()
cleanup()
on(event, callback)
off(event, callback)

TestModeWaymark

Test version of the Waymark class where SDK methods are extended to return mocked values for testing.

new TestModeWaymark()

Extends Waymark

Instance Members
getCollections(shouldFail)
getConnectionDomain()

SDK Errors

These JavaScript errors may be generated by several of the SDK methods.

SDK Errors
Static Members
new AccountMustBeAuthenticatedError(params)
new BrowserCompatibilityError(params)
new ExistingLoginError(params)
new InvalidAPIKeyError(params)
new InvalidAccountError(accountID, params)
new AccountAlreadyExistsError(accountID, params)
new AccountDoesNotExistError(accountID, params)
new InvalidJWTError(params)
new InvalidParameterError(params)