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://beta.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.

Event: frameloaded

The Player API sends events to the host page that you can listen to. The first one you should register to 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.

Loading a post

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);

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) {});

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 enter 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.

Miscellaneous functions

We keep expanding the API and adding functions to allow more control over the player, so this list might change from time to time.

For now, there is only one extra function available that allows to toggle automatic rotation of the tour:

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 will stop the rotation.

Close