Guide is Kakadu’s real-time guidance tool. It enables your users to get help in context, where they are, and when they need it. Kakadu Guide consists of a browser extension (the recorder) and a website script (the player).
The Player is a small script that you can implement on your website to display and run real-time guides. Player releases and downloads are available in our GitHub repository. Please get in touch with Tina if you don’t have access.
The latest version of the player is v1.0.2.
The Recorder is a browser extension that lets you create guides on your website.
The latest version of the recorder is v1.0.2.
Once installed, the recorder is available in your browser’s toolbar. To start recording a guide, click the recorder button on a normal website, and then follow the instructions presented in the sidebar that appears.
The customer ID is provided to you by us. If you don’t have it, lost it, or otherwise need assistance, please get in touch with Tina at Kakadu.
To display and run real-time guides on your website, you must install the player. When fully loaded, the player is just under ~200 KB of JavaScript and CSS.
To get started, install the guide.script.js script on your website:
The latest version of the player is v1.0.2.
For example:
<script type="text/javascript">
((s,o,n,i,u,l,p)=>{var g;try{const a=[],t=r=>Array.from(r),e=r=>{a.push(r)},y=p??"https://guide.kakadu.no";s[n]||(s[n]={apiUrl:y,assetUrl:l,version:u,customerId:i,queue:a,async load(){e(["load",...t(arguments)])},async prefetch(){e(["prefetch",...t(arguments)])},async start(){e(["start",...t(arguments)])},async end(){e(["end",...t(arguments)])},addListener(){e(["addListener",...t(arguments)])},removeListener(){e(["removeListener",...t(arguments)])}});const c=s[n];c.apiUrl=y,c.assetUrl=l,c.version=u,c.customerId=i;const f=`${l}/player/${u}/guide.js`;if(!o.querySelector(`script[src="${f}"]`)){const r=o.createElement("script");r.src=f,r.async=!0;const m=o.querySelectorAll("script")[0];(g=m.parentNode)==null||g.insertBefore(r,m)}}catch(a){console.error(a)}})(window,document,"kakadu","YOUR_KAKADU_GUIDE_CUSTOMER_ID","v1","https://test.assets.guide.kakadu.no");
</script>Replace YOUR_KAKADU_GUIDE_CUSTOMER_ID with your customer ID.
The player guide.script.js script itself won’t do anything until manually triggered, but it will preload the guide.js script in the background:
You can start a guide manually by executing the window.kakadu.start function with the guide ID that you got from the recorder.
window.kakadu.start({id: 'YOUR_KAKADU_GUIDE_ID'});Running the start function will load additional resources (the complete player application):
You can automatically start guides when users visit a page by utilizing guide links (veiledningslink). When a recording is completed in the recorder, you will be presented with a guide ID, alongside a guide link that you can copy and use wherever you want.
To use guide links, the player needs to be implemented on the page.
The URL looks like this:
https://your-website.com/your-page?kakadu-start=YOUR_KAKADU_GUIDE_IDAfter starting a guide, leaving the page, and then returning to it after more than 5 minutes have passed, the guide will not reopen. There is a 5 minute time limit on guide interaction to keep it alive.
The player API is available as a global on the window.kakadu object once the guide.script.js script is initialized.
window.kakadu.startStart a guide, and open the player.
window.kakadu.start({id: 'YOUR_KAKADU_GUIDE_ID'});window.kakadu.prefetchPrefetch the player and the given guide. Does not open the player.
window.kakadu.prefetch({id: 'YOUR_KAKADU_GUIDE_ID'});window.kakadu.endEnd a guide, and close the player.
window.kakadu.end();window.kakadu.addListenerAdd event listeners to the player.
const listener = () => {
console.log('The player has started');
};
window.kakadu.addListener('start', listener);The player will emit the following events:
start: The player has started a guide.end: The player has stopped a guide.window.kakadu.removeListenerRemove event listeners from the player.
window.kakadu.removeListener('start', listener);The player can be self-hosted on your own server by downloading all the player files and placing them in a /player/{version}/ subdirectory, where {version} is the version of the player you have 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.
Then, update your player script:
<script type="text/javascript">
((s,o,n,i,u,l,p)=>{var g;try{const a=[],t=r=>Array.from(r),e=r=>{a.push(r)},y=p??"https://guide.kakadu.no";s[n]||(s[n]={apiUrl:y,assetUrl:l,version:u,customerId:i,queue:a,async load(){e(["load",...t(arguments)])},async prefetch(){e(["prefetch",...t(arguments)])},async start(){e(["start",...t(arguments)])},async end(){e(["end",...t(arguments)])},addListener(){e(["addListener",...t(arguments)])},removeListener(){e(["removeListener",...t(arguments)])}});const c=s[n];c.apiUrl=y,c.assetUrl=l,c.version=u,c.customerId=i;const f=`${l}/player/${u}/guide.js`;if(!o.querySelector(`script[src="${f}"]`)){const r=o.createElement("script");r.src=f,r.async=!0;const m=o.querySelectorAll("script")[0];(g=m.parentNode)==null||g.insertBefore(r,m)}}catch(a){console.error(a)}})(window,document,"kakadu","YOUR_KAKADU_GUIDE_CUSTOMER_ID","v1.0.2","https://your-website.com");
</script>You’ll notice that as the 6th argument in the IIFE, you may set the asset URL: The URL where you’re hosting the player files. In the example above, it’s set to https://your-website.com.
Given that example asset URL (and version), these player files should be hosted and accessible:
https://your-website.com/player/v1.0.2/guide.js
https://your-website.com/player/v1.0.2/guide.player.js
https://your-website.com/player/v1.0.2/guide.player.cssKeep in mind that /player/{version}/ (and the file names) will be automatically added to the end of the asset URL. To host the player files in a subfolder, simply add the subfolder to the asset URL, like this: https://your-website.com/your-subfolder.
To stop self-hosting, simply remove the asset URL argument from the player script. The asset URL is the 6th argument in the IIFE.
The Start/help button is, by default, located in the bottom left corner of the screen. It must be explicitly enabled in code (disabled by default). You can enable it by setting guide.start.enabled to true in options, like this:
// After the Kakadu script
window.kakadu.options ??= {};
(window.kakadu.options.start ??= {}).enabled = true;Clicking the Start/help button opens a modal with all the guides you have set to listed. You can do that in the recorder by updating the status when editing a guide.
If you have no guides set to listed, the Start/help button will not be visible.
By default, the player collects anonymous data about guide usage. This data can be used by both you, through our application dashboard, to optimize the guides, and by us to optimize the player.
If you would like to stop collecting telemetry, you can do this by setting telemetry.enabled to false in options, like this:
// After the Kakadu script
window.kakadu.options ??= {};
(window.kakadu.options.telemetry ??= {}).enabled = false;When selecting elements for steps in the recorder, selector stability is important to ensure your guides stay reliable. Unstable selectors are selectors that, for example, rely on the order of elements on the page, such as nth-child and nth-of-type.
These types of selectors should be avoided because guides may break when your website is updated. Our recommendation is to tag elements used in steps with a data-kakadu-id attribute.
We follow standard semantic versioning rules, where versions follow the format: BREAKING.FEATURE.PATCH. Both the recorder and the player are versioned and released together, but only changes to the player determine the type of version increment — all other updates (such as changes to the recorder) are treated as patches.
Your privacy is important to us. It is our policy to respect your privacy regarding any information we may collect from you across our website, and other sites we own and operate. The entirety of this website and contents is protected by the Norwegian copyright laws.
We’ll only ask for personal information when we truly need it to provide a service to you. We collect it by fair and lawful means, with your knowledge and consent. We also let you know why we’re collecting it and how it will be used.
We only retain collected information for as long as necessary to provide you with your requested service. What data we store, we’ll protect within commercially acceptable means to prevent loss and theft, as well as unauthorised access, disclosure, copying, use or modification.
We don’t share any personally identifying information publicly or with third-parties except when required to by law, or when absolutely necessary to provide our service.
The Recorder
The Recorder does not collect any personal information.
The Player
The Player does not collect any personal information. However, it collects anonymous quantitative data about guide usage, such as guide start, guide step, and guide completion.
You have the right to request the deletion of your personal data. To initiate this process, please send an email to hei@kakadu.no. We will verify your identity and proceed with the deletion of your data in accordance with applicable laws.
Our website may link to external sites that are not operated by us. Please be aware that we have no control over the content and practices of these sites, and cannot accept responsibility or liability for their respective privacy policies.
You are free to refuse our request for your personal information, with the understanding that we may be unable to provide you with some of your desired services.
Your continued use of our website will be regarded as acceptance of our practices around privacy and personal information. If you have any questions about how we handle user data and personal information, feel free to contact us.