Light Plugin — API Reference

Component attributes

The <waymark-light-plugin-button> custom element accepts the following attributes:

partner-id

type: string | required

The Waymark-provided Partner ID for your Light Plugin integration.

React component example:

<WaymarkLightPluginButton partner-id="my-partner-id" />

Web component example:

<waymark-light-plugin-button partner-id="my-partner-id"></waymark-light-plugin-button>

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.

React component example:

<WaymarkLightPluginButton partner-id="my-partner-id" environment="demo" />

Web component example:

<waymark-light-plugin-button
  partner-id="my-partner-id"
  environment="demo"
></waymark-light-plugin-button>

video-id

type: string | optional

The ID of a Waymark video which the user was in the process of editing or had completed and was waiting to finish rendering in order to restore an interrupted session without losing progress.

The Light Plugin does not provide a way to track video IDs, so that implementation detail will be up to you. Anything from saving the ID in local storage to persisting the ID in your database will work depending on your needs.

If you do not track video IDs:

When a user leaves the page before completing their video, they will be able to find it again but it will not be as smooth of an experience
If the user leaves the page while their video is still rendering, they may miss the render completion event and lose the rendered video. Renders can take multiple minutes, so this is a possibility that should be accounted for.

If you provide a video-id attribute, the component will immediately check the video's render status and emit a videoRendered event if the video has finished rendering since the user left the page. Otherwise, it will start listening for render events and notify you when the render completes.

You may also programmatically get/set the current video-id value on the element via a videoID property.

React component example:

const [videoID, setVideoID] = useLocalStorage('waymark-video-id');

return (
  <WaymarkLightPluginButton
    partner-id="my-partner-id"
    video-id={videoID || null}
    onVideoChanged={(e) => {
      const videoData = e.detail;
      if (videoData) {
        // The user started editing a new video
        setVideoID(videoData.id);
      } else {
        // The user was editing a video but stopped
        setVideoID(null);
      }
    }}
    onVideoRendered={(e) => {
      // The video is done rendering, so we can clear the
      // id from local storage
      setVideoID(null);
    }}
  />
);

Web component example:

<waymark-light-plugin-button partner-id="my-partner-id"></waymark-light-plugin-button>
<script>
  const waymarkButton = document.getElementsByTagName('waymark-light-plugin-button')[0];

  const waymarkVideoID = localStorage.getItem('waymark-video-id');
  if (waymarkVideoID) {
    waymarkButton.videoID = waymarkVideoID;
  }

  waymarkButton.addEventListener('videoChanged', (e) => {
    const videoData = e.detail;
    if (videoData) {
      // The user started editing a new video
      localStorage.setItem('waymark-video-id', videoData.id);
    } else {
      // The user stopped editing the video, so remove it from local storage
      localStorage.removeItem('waymark-video-id');
    }
  });
  waymarkButton.addEventListener('videoRendered', (e) => {
    // The video finished rendering, so remove it from local storage
    localStorage.removeItem('waymark-video-id');
  });
</script>

file-input-id

type: string | optional

The ID of an <input type="file"> element on the page which the Light Plugin should directly pass rendered video files to when the user's completed video finishes rendering.

This can help make integration as simple as possible if you already have a file upload button on your site.

When the video finishes rendering, the Light Plugin will automatically download the video file, transfer it to the file input element, and trigger an input and change event on the input to indicate that a file has been passed to it. If your app is configured to handle uploads in this way already, then it should ideally just work.

React component example:

<input type="file" id="file-upload-input" onInput={(e) => {
    const file = event.currentTarget.files[0];

    fetch("/upload-video", {
      method: "POST",
      body: file,
    });
  }}
/>
<WaymarkLightPluginButton
  partner-id="my-partner-id"
  file-input-id="file-upload-input"
/>

TypeScript types

In TypeScript projects, you may use the WaymarkLightPluginButtonElement type for referencing instances of the <waymark-light-plugin-button> element.

React component example:

import {
  WaymarkLightPluginButton,
  type WaymarkLightPluginButtonElement,
} from '@waymark/waymark-sdk/light-plugin-button-react';

function MyComponent() {
  const waymarkPluginButtonRef = useRef<WaymarkLightPluginButtonElement>(null);

  return <WaymarkLightPluginButton ref={waymarkPluginButtonRef} partner-id="my-partner-id" />;
}

Manual Waymark Plugin SDK access

If for some reason you would like to manually access a portion of the Waymark Plugin SDK which is not exposed by the Light Plugin component, you may access the SDK on the component instance's waymark property.

This will give you access to all Plugin API methods. Note that the Light Plugin will always be in uncontrolled auth mode, so you will not have access to any account methods.

import {
  WaymarkLightPluginButton,
  type WaymarkLightPluginButtonElement,
} from '@waymark/waymark-sdk/light-plugin-button-react';

function MyComponent() {
  const waymarkPluginButtonRef = useRef<WaymarkLightPluginButtonElement>(null);

  useEffect(() => {
    const waymark = waymarkPluginButtonRef.current.waymark;
    const videoData = waymark.getVideoData('video-id');
  }, []);

  return <WaymarkLightPluginButton ref={waymarkPluginButtonRef} partner-id="my-partner-id" />;
}

Styling

Themes

The <waymark-light-plugin-button> element comes with 2 built-in themes: a light theme and a dark theme.

Themes can be applied by setting a data-theme attribute on the <waymark-light-plugin-button> element. If no theme is set, it will default to the light theme, which is a black button with white text.

Valid theme values:

light (default)

<waymark-light-plugin-button
  partner-id="my-partner-id"
  data-theme="light"
></waymark-light-plugin-button>

dark

<waymark-light-plugin-button
  partner-id="my-partner-id"
  data-theme="dark"
></waymark-light-plugin-button>

system

If you would like the button's theme to automatically match the user's prefers-color-scheme preference, you can set the theme to "system".

<waymark-light-plugin-button
  partner-id="my-partner-id"
  data-theme="system"
></waymark-light-plugin-button>

Custom styling

The <waymark-light-plugin-button>'s contents are encapsulated in the Shadow DOM, but the core elements can be targeted to apply your own custom styles using the CSS ::part selector.

Beware:

You may alter the appearance of the button in minor ways to make it fit better on your site, but it must remain recognizably branded with Waymark's logo and brand colors.

Styling the button

The <button> element can be targeted in CSS with ::part(button).

waymark-light-plugin-button::part(button) {
  /* Apply a custom smaller font size to the button */
  font-size: 0.8rem;
}

Styling the logo icon in the button

The <svg> logo in the <button> element can be targeted in CSS with ::part(logo).

waymark-light-plugin-button::part(logo) {
  /* Make the logo icon smaller */
  width: 1.5rem;
}

Styling the dialog

The <dialog> element can be targeded in CSS with ::part(dialog).

waymark-light-plugin-button::part(dialog) {
  /* Make the dialog a little smaller */
  width: 70%;
}