Embedding integration guide

This guide is intended for web developers who would like to integrate Kuula tours into their publishing systems. These system can include website content management, real estate listings, CRMs or similar. The goal is to allow the users and editors in the system to safely and efficently publish Kuula virtual tours.

This guide shows how to validate Kuula links and programatically turn them into an embedded element in your system in a consistent and secure way.

Virtual tour links

Valid links to posts and tours on Kuula only use HTTPS and can have one of the following structures:

Those links represent, in order:

• A virtual tour
• A specific post within a virtual tour

Link structure

There are the following variable parts in those URLs:

• POST_IDstring of alpha numeric characters. This parameter is optional.
• TOUR_IDstring of alpha numeric characters. This parameter is mandatory. Currently, every id has a lenght of 5 characters, but that can change in the future, so please do not base your validation on the lenght of the id.
• Query string a list of parameters presented as key/value pairs - key1=value&key2=value This is optional, however most of the time users choose to add some customizations.

Here's a regular expression that you can use to validate Kuula links:

Click here for interactive version.

The first group in this expression contains the tour id (or a post id if this is a single post link). The second group contains the query string parameters.

Other formats: profile links

Some users may copy and paste a link to a tour from their profile instead of the sharing link. Those links have the following structure:

Those links cannot be embedded. The browser will show a security error.

You can choose to reject them and inform the user that it is not a valid link or you can do a substitution of the path element /post to /share to programatically get the correct format.

Other formats: MLS links

Another possible format is an MLS approved link, which has the same structure, but uses a special domain called mls.kuu.la

Same as above, you can choose to reject this format and inform the user what the correct link should look like.

However, those links can be embedded, so you can also accept them as is.

Query string parameters

Kuula allows a lot of different customizations in the embedded player. Those parameters can be adjusted by the tour creators in the Export Editor. They are attached to the link in the form of a query string.

This article is not an exhaustive list of all existing parameters. We only focus on the parameters that require special attributes in the iframe code or those that impact load times.

Fullscreen

fs=1 - this parameter specifies if a fullscreen button will show up in the top/right corner of the player. It can have a value 0 or 1, default is 1.

Apple iOS doesn't support Javascript fullscreen API, therefore on this platform, the button opens up a new browser tab with the tour scaled to full window size.

In order for fullscreen to work on all other platforms, the iframe code needs to have the allowfullscreen attribute present. We recommend adding fullscreen support to the embeds as this is a very popular feature and users expect it to work. However, you can disable that feature by replacing/setting this parameter to 0: fs=0

Virtual Reality

vr=1 - this parameter specifies if a VR button will show up in the top/right corner of the player. The name of the parameters is vr and it can have a value 0 or 1, default is 0.

Apple iOS doesn't support native VR API, so on this platform, the button opens up a new browser tab with the tour in full window and VR mode.

VR is supported natively on Android phones and in Meta Quest headsets. For it to work properly, the iframe code needs to have the allow="xr-spatial-tracking; gyroscope; accelerometer" attributes.

On desktop and laptop computers that do not suport VR, the VR icon will remain hidden regrdless of the settings.

If you do not wish to support VR in your embedded tours, you can disable that feature by setting this parameter to 0: vr=0

Start on load

initload=1 - this parameter specifies if the tour will load automatically of show a title screen with a button that needs to be activated before the tour loads. Showing the title screen can decrease the inital load time of the tour and therefore the page where it is embedded. It can have a value 0 or 1, default is 0.

HD / SD

sd=1 - if set to 1, the tour will use 4k definition images only. This can improve performance and loading times on desktop. On mobile, all tours load in 4K/SD mode regardless of this parameter. It can have a value 0 or 1, default is 0.

HTML iframe element

We recommend using the iframe code below:

After validating the link, you can set it as the src attribute in the code above and add the iframe to the DOM.

The allowfullscreen and allow attributes are only necessary, if you want to support fullscreen and VR as explained above.

This code assumes, that the size of the iframe element is controled by CSS code on your page. The Kuula player is fully responsive, so you can scale the iframe using media queries. Please consult this guide for more details.

Customizing the player behavior

You can use the Kuula Player API to further customize the look & feel and behavior of the embedded player. For more information, please see the API tutorial.

Technical support

If you are working on integration of Kuula tours with your system and you have any technical questions, please let us know.