LATEST AWESOMNESS

Embedding Guide

NOTE: This guide is currently outdated - new documentation will be available within the next few days.

In this guide, we’ll show you how to embed your animation into an HTML page and how you can choose to control it with JavaScript.

There are several ways to embed animation in your own HTML page. They are:

  • Embedding using IFRAME
  • Embedding directly into your page using both CANVAS tag(s) and SCRIPT tags inside of your page

Embedding using IFRAME gives you a ready-to-go player version, so you just copy-paste the code in your page and you’re done! Using CANVAS requires you to write at least one line of JavaScript code.

In each case you also have several ways to configure your animation. You may combine them or use them separately, as you wish.

If you want just to ‘tune up’ the Player’s behavior, i.e. enable auto-play or loop, jump to a specific time and start playing, pause at specified time, or change the scene zoom factor—we provide you with URL parameters, so you don’t need to write additional JavaScript code.

If you want more control over the playing process of the animation/scene, like to jump in time several times, or to customize the Player’s controls with your theme, or even to provide more custom interactivity to your user, then you have the power of JavaScript at your fingertips, since the Animatron Player has a very nice and friendly API.

IFRAME

Use IFRAME if you don’t need any special customizations. This is the simplest way—just grab your code from the Publish dialog box and insert it into your HTML:

Publish button

New project dialog

So normally, embed code looks like:

<iframe src="https://player.animatron.com/go?4998090d48b10fe0a5a44b80983e25f1-v1.1&w=550&h=450" width="550" height="450" frameborder="0"></iframe>

And that’s it, if you just want the Player on your page!

When you’re done, as mentioned above, you have the option to tune up the Player using URL parameters. Just add them to the end of snapshot URL like this:

<iframe src="https://player.animatron.com/go?4998090d48b10fe0a5a44b80983e25f1-v1.1&w=200&h=300&r=1&z=1.5&t=25" width="550" height="450" frameborder="0"></iframe>

In this example, w and h both restrict scene width/height to scale to a given size, 200x300 in this case. (IFRAME size has higher priority over animation size, so you’ll get those famous black lines above and below your animation if the aspect ratio doesn’t match.) r says to loop the scene (1 to enable, 0 to disable), z specifies the zoom of the scene (1.5), and t specifies the time to jump to, just after the scene was loaded (25 means 2 seconds 500 milliseconds, same as in Youtube URLs).

URL Parameters List

An URL for the IFRAME page without the parameters may look like:

https://player.animatron.com/go?4998090d48b10fe0a5a44b80983e25f1-v1.1

Then, an URL with some parameters specified may look like:

https://player.animatron.com/go?4998090d48b10fe0a5a44b80983e25f1-v1.1&w=600&h=500&bg=f0fff0&m=0&r=0&z=1&t=25&p=37&

Any of the parameters are optional. Here are definitions for each of them:

  • w is forced width and h is forced height of the Player, so even if any scene loaded inside the Player has another size, the Player won’t be resized to fit it (as by default), but will be forced to scale scene to this size and black ribbons will appear if the aspect ratio is not the same. However, if the Player is placed inside of IFRAME, IFRAME size will have major priority over this size.
  • bg is the background color of the Player in format of ff00a6; if you don’t specify the background color, the Player’s background is transparent by default. The background color can’t contain an alpha value, only solid fill; when a scene has its own background color (which may contain alpha) and there is a Player background color specified, they are applied in order of: player background below, then scene background.
  • r specifies the repeating mode, 1 is to repeat (loop), 0 (default) — play once.
  • z is zoom of the scene, may be a float value
  • t is the time to start play from when the scene is loaded, specified in centiseconds, so t=370 means play from 3s 700ms. By default, the Player is stopped in this case, waiting for the user to press the play button.
  • p is time to pause at when scene is loaded, specified in centiseconds, so p=370 means pause at 3s 700ms. By default, the Player is stopped at time of 0 in this case, waiting for the user to press the play button. debug flag (0 or 1, off by default) allows you to turn on debug information such as FPS and exact time.
  • m is the mode of the Player, PREVIEW (no controls, no handling mouse/keyboard) is 0, DYNAMIC (no controls, handling mouse/kb) is 4, VIDEO (controls are shown, no mouse/kb handling, default) is 11. NB: These values are subject to change in near future.

P.S. We are planning to add parameters to allow disabling audio and controls/event handling separately in the near future.

Embedding using JavaScript code

Things become a bit more complicated if you want to control the Player’s behavior in more specific way, or to replace the Player’s controls with your own style.

The easiest way to embed the Player with JavaScript looks like this:

https://gist.github.com/f55a837d0eb0f45bd2e9

https://gist.github.com/f55a837d0eb0f45bd2e9

Let’s look at the details of a slightly more complex example: when you need to disable the native controls and to allow a user to quickly switch between scenes with your own controls.

Preview

To achieve this, you have to access the Animatron Player directly from the JavaScript. By the way, you are free to use the Player’s JS files directly from our CDN :). So, first you have to initialize the Player instance, point it to your project’s data and configure the CANVAS element for it, then call play() and pause() methods manually:

https://gist.github.com/88d1eecaa6874cbc9920

https://gist.github.com/88d1eecaa6874cbc9920

Let’s walk through this code step by step:

  1. First of all, you should include the Player’s code itself by adding the <SCRIPT> tag and specifying animatron.js bundle (all of the Player files minimized and archived in one JavaScript file).
  2. Now you have to define a Canvas element (the surface at which the Player will draw your animation) by adding a <CANVAS> tag and assigning an ID to it: <canvas id="anm"></canvas>
  3. OK, now we have the Player’s code and a Canvas to draw to, so let’s initialize the Player:

    • First of all we will need to find our project data. To do this we should open the Publish dialog as usual and extract the Project ID from the URL:

      Publish dialog

      And then substitute it into a URL https://snapshots.animatron.com/XXX where XXX is an extracted ID, so the resulting URL will look something like this: https://snapshots.animatron.com/8e188b4e170e60300117ce70fa76ab76-v1.1. Let’s call this URL a Data URL.

    • And then we should pass the resulting Data URL to the forSnapshot method which will initialize the Player and load project data from the specified URL.
  4. Now we have an initialized player and can send it some important signals like play(time) and pause().
  5. We also provided the onLoad function to execute when the snapshot was completely loaded in the Player. It is also possible to subscribe to player’s LOAD event instead event using player.on(anm.C.S_LOAD, <function>), but this event is fired before Player stops itself to prepare the scene.

All the URL parameters listed above may also apply to snapshot URLs, so you may freely add them in the end of it in the same way, just don’t forget to place a ? sign before:

https://snapshots.animatron.com/8e188b4e170e60300117ce70fa76ab76-v1.1?w=600&h=500&bg=f0fff0&m=0&r=0&z=1&t=25&p=37&debug=0

P.S. You may freely create as many player instances as you wish.