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 (the Player).
Kakadu is a Norwegian software company based in Stavanger, focused on improving customer experience.
Downloads
Recorder
The Recorder is a browser extension for creating and publishing guides on your website.
Player
The Player is a small script embedded on your website that loads, displays, and plays guides. Player releases and downloads are available in our GitHub repository. Please contact Tina if you need access.
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:
- 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.
- Click “Choose element”.
- Select the element you wish to highlight in this step.
- Optionally add a description for the user.
- Click “Add step” and repeat from step 1 until you’ve added all steps.
- 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 Kakadu Help).
Technicals
Stabilizing elements
Some elements on a webpage are considered unstable. That means the Recorder can’t guarantee the Player will highlight the same element each time a guide is played.
A stable element keeps its identity even if the DOM changes or the page is resized.
To stabilize an element, add any of these attributes to the HTML: data-kakadu-id, data-test-id, data-testid, data-track-id, data-trackid.
Versioning
We follow semantic versioning with the format BREAKING.FEATURE.PATCH. The Recorder and Player are versioned and released together, but only Player changes determine major and minor increments. Recorder-only updates are always patches.
Player API
Installation
To install the Player on your website, embed this script on every page that should be able to play 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>Methods
Coming soon...
Options
Telemetry
The Player collects anonymous usage data. You can view this data in our dashboard to optimize your guides, and we use it to improve the Player. You can opt out by setting telemetry.enabled to false, like this:
// After the Kakadu Player script
window.kakadu.options ??= {};
(window.kakadu.options.telemetry ??= {}).enabled = false;Help button
Kakadu Help is optional and must be explicitly enabled. When enabled, a floating button will appear in the lower-left corner on pages where the Player 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 Player 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.
Self-hosting
The Player can be self-hosted on your own server by downloading all Player files and placing them under /player/{version}/, where {version} is the Player version you downloaded. You’ll find downloadable releases in our GitHub repository.
For example, if you have downloaded the Player 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 player script like this, while paying attention to the IIFE argument: The 4th argument is your customer ID, the 5th argument is the Player version, and the 6th argument is the Player asset URL.
Your updated player 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).