Kakadu Guide
•
Docs

Documentation

What is Kakadu Guide?

Guide is a real-time guidance tool from Kakadu. It delivers contextual help directly in your product, exactly when users need it. Kakadu Guide consists of a browser extension (the Recorder) and a lightweight website script.

Kakadu is a Norwegian software company based in Stavanger, focused on improving customer experiences.

View demo
•Get in touch

Downloads

Recorder

The Recorder is a browser extension for creating and publishing guides on your website.

Script

Install the script on your website to load, display, and play guides.

Usage

Creating guides

To create a guide, open the Recorder and click “New guide”. Then, either follow our visual quick-start guide, or the steps below:

  1. Navigate to the page you want to create a guide for.
    • You can hide and show the Recorder by clicking the button in the upper-left corner.
  2. Click “Choose element”.
    • Select the element you wish to highlight in this step.
  3. Optionally add a description for the user.
  4. Click “Add step” and repeat from step 1 until you’ve added all steps.
  5. Click “Save”.
    • Make a note of the guide ID.

Testing guides

To test a guide, open the Recorder and click “Open guide”. Enter the guide ID, then click “Test guide”. You’ll be redirected to the first step and the test will begin.

Publishing guides

To publish a guide, open the Recorder and click “Open guide”. Enter the guide ID, then click “Edit guide”. In the edit form, set Status to published (available for use) or listed (available and visible in the help button modal).

Technicals

Stabilizing elements

Some elements on a webpage are considered unstable. That means the Recorder can’t guarantee the script will highlight the same element each time a guide is played.

A stable element keeps its identity when elements move or the page is resized.

To stabilize an element, add any of these attributes to the HTML, with a unique ID: data-kakadu-id, data-test-id, data-testid, data-track-id, data-trackid.

Before:
<div>Hello, world!</div>
After:
<div data-kakadu-id="this-is-my-unique-id">Hello, world!</div>

Versioning

We follow semantic versioning with the format BREAKING.FEATURE.PATCH. The Recorder and the script are versioned and released together, but only script changes determine major and minor increments. Recorder-only updates are always patches.

Script

Installation

Add the script to every page that should be able to play your guides:

<script type="text/javascript">((s,a,n,i,o,g,h)=>{var l;try{const c=[],e=t=>Array.from(t),r=t=>{c.push(t)},d=h??"https://guide.kakadu.no";s[n]||(s[n]={apiUrl:d,assetUrl:g,version:o,customerId:i,queue:c,async load(){r(["load",...e(arguments)])},async prefetch(){r(["prefetch",...e(arguments)])},async start(){r(["start",...e(arguments)])},async end(){r(["end",...e(arguments)])},async event(){r(["event",...e(arguments)])},addListener(){r(["addListener",...e(arguments)])},removeListener(){r(["removeListener",...e(arguments)])}});const u=s[n];u.apiUrl=d,u.assetUrl=g,u.version=o,u.customerId=i;const y=`${g}/player/${o}/guide.js`;if(!a.querySelector(`script[src="${y}"]`)){const t=a.createElement("script");t.src=y,t.async=!0;const p=a.querySelectorAll("script")[0];(l=p.parentNode)==null||l.insertBefore(t,p)}}catch(c){console.error(c)}})(window,document,"kakadu","YOUR_KAKADU_GUIDE_CUSTOMER_ID","v2","https://guide.kakadu.no");</script>

Options

Help button

The help button is optional and must be explicitly enabled. When enabled, a floating button will appear in the lower-left corner on pages where the script is embedded. Clicking it opens a modal that shows all your listed guides. From there, users can click a guide to start it.

You can enable the help button by setting help.enabled to true, like this:

// After the Kakadu script
window.kakadu.options ??= {};
(window.kakadu.options.help ??= {}).enabled = true;

You can set the guide’s listed status when editing a guide in the Recorder.

Telemetry

The script collects anonymous usage data. You can view this data in our dashboard to optimize your guides, and we use it to improve the script. We strongly recommend leaving this on, but you can opt out by setting telemetry.enabled to false, like this:

// After the Kakadu script
window.kakadu.options ??= {};
(window.kakadu.options.telemetry ??= {}).enabled = false;

Self-hosting

The script can be self-hosted on your own server by downloading all script files and placing them under /player/{version}/, where {version} is the script version you downloaded. You’ll find downloadable releases in our GitHub repository.

For example, if you have downloaded the script version v1.0.2, you would place the files in a /player/v1.0.2/ subdirectory. The path leading up to and before the /player/ directory is up to you.

Install the script like this, while paying attention to the IIFE argument: The 4th argument is your customer ID, the 5th argument is the script version, and the 6th argument is the script asset URL.

Your updated script should look something like this:

<script type="text/javascript">((s,a,n,i,o,g,h)=>{var l;try{const c=[],e=t=>Array.from(t),r=t=>{c.push(t)},d=h??"https://guide.kakadu.no";s[n]||(s[n]={apiUrl:d,assetUrl:g,version:o,customerId:i,queue:c,async load(){r(["load",...e(arguments)])},async prefetch(){r(["prefetch",...e(arguments)])},async start(){r(["start",...e(arguments)])},async end(){r(["end",...e(arguments)])},async event(){r(["event",...e(arguments)])},addListener(){r(["addListener",...e(arguments)])},removeListener(){r(["removeListener",...e(arguments)])}});const u=s[n];u.apiUrl=d,u.assetUrl=g,u.version=o,u.customerId=i;const y=`${g}/player/${o}/guide.js`;if(!a.querySelector(`script[src="${y}"]`)){const t=a.createElement("script");t.src=y,t.async=!0;const p=a.querySelectorAll("script")[0];(l=p.parentNode)==null||l.insertBefore(t,p)}}catch(c){console.error(c)}})(window,document,"kakadu","YOUR_KAKADU_GUIDE_CUSTOMER_ID","v2","https://your-website.com/optional-subfolder");</script>

Stop self-hosting

To stop self-hosting, set the 6th argument of the IIFE to the default asset URL: https://guide.kakadu.no (like in the installation example).