Onboarding Animation with KeyshapeJS

Onboarding means giving an introduction about products or services to new users. It is often presented as a series of steps, which the users go through. Animations can make onboarding more playful and fun.

Below is an imaginary onboarding example made in Keyshape. It is made of four steps. Animations are used between the steps to make it more engaging. Press the “Next” button to see how it works!

Creating the Animation in Keyshape

You can find the Keyshape file for the animation at the bottom of this page so you can open in it Keyshape and see how it has been made. It has four time markers and the animation progresses from one marker to the next one when the "Next" button is pressed. Only the time of the time markers matters here, their names are not used by the code.

The animation was exported as an SVG with KeyshapeJS animation. Note that the "Loop" export parameter has been set to "Play once" so that each animation step plays only once.

HTML Code

The HTML code for this is simple. The <object> element displays the SVG animation. It has "global=paused" parameter so that the animation doesn't start playing immediately. There are two HTML buttons under the object element. The elements have ids so that JavaScript can access them.

<object id="candy-svg" data="onboarding.svg?global=paused" type="image/svg+xml"></object>
<p>
  <button id="go-to-start">Go to Start</button>
  <button id="next">Next</button>
</p>

The Next Button

The “Next” button changes the play range to play from the current time to the next time marker.

Below is the code which changes the play range. It compares the current animation time to the time markers. When it finds a time marker, which comes after the current time, it changes the play range to play until it.

Playing and pausing animations can happen at a global or timeline level. The top level object controls how a global timeline progresses. The “global=paused” parameter in the object URL sets the global timeline to paused after the animation has been loaded. The timeline level pauses and plays only one timeline. If the global timeline is paused, then nothing happens even if a timeline is set to play.

The code below calls globalPlay() for the KeyshapeJS object to make it play the first time after the animation has been loaded.

There is also a call to play() for the timeline. The timeline will play until it reaches the play range end time.

document.getElementById("next").addEventListener("click", function() {
    var el = document.getElementById("candy-svg");
    if (el.contentDocument && el.contentDocument.defaultView.KeyshapeJS) {
        var ks = el.contentDocument.defaultView.KeyshapeJS;
        var timeline = ks.timelines()[0];
        var markerTimes = Object.values(timeline.markers());
        for (var i = 0; i < markerTimes.length; i++) {
            var markerTime = markerTimes[i];
            if (timeline.time() < markerTime) {
                timeline.range(markerTimes[i-1], markerTime);
                ks.globalPlay();
                timeline.play();
                return;
            }
        }
    }
}, false);

The Go to Start Button

In addition to the “Next” button, there is the “Go to Start” button. Onboarding doesn’t necessarily need it, but it was added so that it is possible to try the example multiple times.

The button just pauses the timeline and sets its time to zero.

document.getElementById("go-to-start").addEventListener("click", function() {
    var el = document.getElementById("candy-svg");
    if (el.contentDocument && el.contentDocument.defaultView.KeyshapeJS) {
        var timeline = el.contentDocument.defaultView.KeyshapeJS.timelines()[0];
        timeline.pause(0);
    }
}, false);

Additional Steps

It would be easy to add more steps by adding more time markers to the animation in Keyshape.

There are also other ways to improve the example. For example, the label of the “Next” button could be changed to “Finished” when the animation reaches the end.

Local testing and browser security

The example may not work correctly on some web browsers if the HTML file is opened directly (using the file:// protocol), because browsers don’t allow JavaScript to access the SVG file for security reasons.

The solution is to run a local web server. On Mac, right click the file’s folder, select “New Terminal at Folder” and then run “python -m SimpleHTTPServer” to launch the server. The page can be opened in a web browser by going to the address “http://localhost:8000/index.html”

Keyshape Files

Document History

- Modified to use the new time marker API.
- Modified to use time markers.
- Document created.