Back to support

Getting started with the Player API

The Kuula Player API is a simple Javascript library that allows your page to interact with embedded Kuula posts and tours. It can be used to create advanced interactive presentations involving 360 panoramas.

As a companion to this tutorial, take a look at this Demo page. It shows a basic patter of adding the API and interacting with a player. If you open the source code of that page - you will find some additional comments and explanations.

Adding the API to the page

Before anything else, you will need to include the Kuula Player API Javacript library on your page. We suggest to do it in the <head> section of your document. We made sure that the library is as small as possible - it's only around 1KB, so it should not impact the page load time. Here's how to include it:

<script src="https://static.kuula.io/api.js"></script>

Embedding a post or tour

Now you can embed the tour on the page. You can use the Export Editor with the standard embedding functions on Kuula to grab the embed code. It can be either the Javascript based code or the HTML/iframe code.

<script src="https://static.kuula.io/embed.js" 
    data-kuula="https://kuula.co/share/collection/7lG5x?thumbs=-1&chromeless=1">
</script>

Using the API

The best place to add the Javascript interacting with the player is at the end of your HTML document, however it can also be included in the head part. Just make sure to include the API first (as show above).

Once the API script is loaded, it creates a global object called KuulaPlayerAPI. You will use it to interact with the API by reading events sent by the player or sending commands to the player. We will cover the events first and commands below in this article.

Events

Event: frameloaded

The first event you should register a listener for is called frameloaded. This will be called each time a Kuula embed is loaded. If you only have one embed on the page - this event will be sent once. Here's how to implement it:

KuulaPlayerAPI.addEventListener("frameloaded", function(e) {
    console.log("Frame id:   " + e.frame);
    console.log("Posts list: " + e.data.posts);
    console.log("Tour info:  " + e.data.tour);
});

This event will provide you with some valuable data.

First of all, it sends a unique id of the frame. You will need it to send commands to the player, so keep that variable around. Note, that it's necessary even if there is only one embed on the page.

You will also receive an array called posts containing a list of all the posts in the embed. If it is a single post embed - the list will only contain one element. If it is a tour - it will contain al the posts in this tour. Each post object has an id, that can be used to load the post int the embed (see below). Other than that, it also has a title and a description.

If the embedded player holds a tour instead of a single post, you will also receive a tour object containing some information about the tour itself, such as id, name and description.

Event: postloaded

Each time a new post is loaded into the embedded player, either using the API or by user interaction within the player itself, a postloaded event will be invoked. The event object has the frame property holding the id of the player that send this event along with infomration about the post (it, title, etc...) available under the data property.

KuulaPlayerAPI.addEventListener("postloaded", function(e) {
    console.log(e.data);
});

Event: hotspot

The hotspot event is invoked each time a use clicks on a hotspot in the embedded tour:

KuulaPlayerAPI.addEventListener("hotspot", function(e) {) {
    console.log("Frame id:          " + e.frame);
    console.log("Hotspot unique id: " + e.data.uid);
    console.log("Hotspot name:      " + e.data.name);
});

By default, the event data object will send a unique id of the hotspot (uid property). You can write code that will execute a certain action based on that id, but it's not practical and would make code hard to read. Instead, you can name a hotspot in the editor and use that name to implement your logic.

To name a hotspot, go to the post with that hotspot in the Kuula editor, select the hotspot and you will find the name input field all the way at the bottom of the editor panel, as on the image below:

If you set a name for the hotspot in that field and save the post, that name will be sent in the event to the API.

Hotspot events are sent for any type of hotspot, regardless of what action you assing to it. It can be a hotspot that opens a post or an interactive card. Most importantly however, you will receive the event even if the hotspot has no action assigned. This way you can add hotspot that will only result in some action on the host page.

Event: orientation

The orientation event is invoked at regular intervals, every 100 miliseconds, and send the current orientation of the panorama, the includes heading, pitch and zoom:

KuulaPlayerAPI.addEventListener("orientation", function(e) {) {
    console.log("Frame id:          " + e.frame);
    console.log("Panorama heading:  " + e.data.heading);
    console.log("Panorama pitch:    " + e.data.pitch);
    console.log("Panorama zoom:     " + e.data.zoom);
});

The heading is expressed in degress and is relative to the heading setting in the editor. The degress off heading are counter clockwise (right) and have a value ranging from 0 to 360.

The pitch is also a value in degrees in the range from -90 to 90, where 90 means all the way down.

Finally, the zoom value is in the range from -1 to 1 where -1 is full zoom in.

This information can be used in many ways, for example to add a custom floor plan with compass function showing the diretion the user is looking to.

Commands

Command: load

You can load any post from the embedded tour using the API using the load function. This can be used to build custom menus and control the content of the embedded player from using custom interactive elements on your page.

To load an post into an embedded player, you will need two things: the frame id received in the frameloaded event and the id of the post. As a reminder, posts and their id can be found in the posts array that also comes with the frameloaded event. With that data, loading a post is straightforward:

KuulaPlayerAPI.load(frameId, postId);

Command: setHeading, setPitch, setZoom

The trio of functions allows you to set the orientation of the currently displayed post. For accepted values and ranges please check Event: orientation above. The functions follow all the same parameter pattern:

KuulaPlayerAPI.setHeading(frameId, value);

Command: setParam

This function allows to change paramaters of a hotspots. To use it, you will first need to assign a "scriping id" to a hotspot in your post and then reference it in the function call as shown below ("hotspotId"):

KuulaPlayerAPI.setParam(frameId, hotspotId, param, value);

Currently supported parameters are: tint and opacity. Opacity takes a value between 0 and 1. The value of the tint is a hexadecimal color code (ex. "#ff8800").

Command: setAutoRotate

KuulaPlayerAPI.setAutoRotate(frameId, value);

The value argument defines the speed of the rotation. It can be any number, negative values to rotate in the opposite direction. The larger the number the faster the rotation. Passing 0 or false as argument will stop the rotation.