The embed API

An embedded piece can talk to the page around it. With the embed API, your page can set off the piece's state transitions, jump it to a state, set its controls and move its playback, and hear back when its state changes or its code sends an event. A product page can make a hero piece react to a button, a form or a checkout, and a piece can tell the page when something happens in it.

It's one small script, embed.js, that wraps the iframe of a piece's player. It works with any embed made from the studio; see Embedding a piece for making one.

Setting it up

1. Embed the piece

   Paste the piece's embed code into your page. It's an iframe whose address starts https://www.vybe.art/e/.

2. Load embed.js

   Add the script anywhere on the page:

   <script src="https://www.vybe.art/embed.js"></script>
   

3. Wrap the iframe

   Pass the iframe to VybeEmbed, and talk to what it returns:

   <script>
     const piece = VybeEmbed(document.querySelector('iframe'));
   
     piece.on('ready', (controls) => console.log('Playing, with controls', controls));
     document.querySelector('#bloom').onclick = () => piece.input('bloom');
     piece.on('state', (name) => console.log('Now in', name));
   </script>
   

VybeEmbed throws if it isn't given an iframe. With several embeds on a page, wrap each one separately. It doesn't matter whether the script runs before or after the player has started: it asks the player, and calls you make before it's ready are held and sent once it is.

Methods

Every method returns the same object, so calls chain: piece.set('speed', 2).play().

Names and values

• Input and state names are 1 to 40 characters: letters, digits, spaces, _, ., : and -. Anything else is ignored.
• set takes a number, true or false, or a string of up to 2,000 characters, such as '#ff7a45' for a colour. The key is the control's key, as controls lists it: its property name, after its folder and a dot when it's in one, such as speed or Camera.distance; for a GLSL piece, the uniform's name. A value set from the page isn't saved with the piece.
• seek moves the piece's timeline, and the time a WebGL 3D or GLSL piece runs on. A Canvas 2D piece's own clock isn't moved, though its timeline is.

Events

controls is a list of { key, label, type }, one for each control the piece shows, where type is 'number', 'boolean', 'text', 'select', 'color' or 'button'.

piece.on('event', (name, detail) => {
  if (name === 'won') showBanner(`You scored ${detail.score}`);
});

The piece's side of that is on The runtime API.

Setting up states for a page

Inputs and states are made in the studio's Motion panel, in the States tab. Add the states, then a transition whose trigger is Page input, and give the input a name: that's the name your page sends with input(). A transition triggered by Piece event fires when the piece's code calls vybe.emit with its name.

Once a piece has a Page input or Piece event transition, the States tab shows an On a page section with the lines of code for that piece's own inputs, ready to copy. See States and interactions.

Examples

A call to action that wakes the piece up when the visitor reaches the form:

const piece = VybeEmbed(document.querySelector('#hero'));
const form = document.querySelector('#signup');

form.addEventListener('focusin', () => piece.input('wake'), { once: true });
form.addEventListener('submit', () => piece.state('celebrate', 1.2));

A colour picker on the page that recolours the piece:

const piece = VybeEmbed(document.querySelector('iframe'));
document.querySelector('#tint').addEventListener('input', (e) => piece.set('tint', e.target.value));

Buttons that scrub to moments of the piece's timeline:

const piece = VybeEmbed(document.querySelector('iframe'));
document.querySelectorAll('[data-at]').forEach((button) => {
  button.addEventListener('click', () => piece.pause().seek(Number(button.dataset.at)));
});

Things to know

• The player pauses while it's scrolled out of view, so it doesn't spend the page's GPU, and plays again when it scrolls back. A piece you paused with pause() plays again if it leaves the view and comes back.
• Only the piece is reachable. The page can move the piece's state machine, controls and playback, and nothing else. The piece hears nothing from your page beyond those messages.
• Hidden controls aren't listed in controls, though set still reaches them by key.
• VR and AR still work in an embed: the embed code allows them, and a visitor on a headset sees Enter VR or Enter AR on the piece.

Related

• Embedding a piece
• States and interactions
• The runtime API
• Limits