Install Koala
Learn how to install the Koala JavaScript SDK.
See the Quick Start for general installation instructions.
FAQ
Does Koala work across different subdomains? (eg., example.com, app.example.com, docs.example.com)
Yes, if you intall the pixel in all places, we’ll seamlessly track the entire user journey across all subdomains with no additional configuration.
What happens with Koala installed on different top-level domains? (eg., vercel.com, nextjs.org)
You can install the pixel in both places, but the same user will show up as two different users. This is not a Koala limitation per se, but rather a design choice browsers have made to not let different top-level domains share cookies. If the users identify themselves, we’ll automatically merge them into one profile, but they will show up as different profiles until the identification happens.
Troubleshooting
Using a strict Content Security Policy
Koala asynchronously loads different parts of the library as needed. If your site uses a strict Content Security Policy (CSP) that specifies which locations can download JavaScript or use Websockets, then you’ll need to update the CSP to handle those pieces used for Koala.
You may see client-side errors about a “Content Security Policy” directive if you are using a strict CSP and Koala has not be added to it.
Depending on your CSP configuration, you may need various CSP directives like connect-src
or script-src
to allow Koala to work properly.
If you have a strict connect-src
, add these endpoints to it:
https://*.getkoala.com
wss://*.getkoala.com
If you have a strict script-src
, add this endpoint to it:
https://*.getkoala.com
If you have a strict script-src-elem
, add this endpoint to it:
https://*.getkoala.com
It’s likely you can find it in your codebase if you do a case-insensitive search for script-src
, but if you need to learn more about it, use this resource to learn more: https://content-security-policy.com
Installing the library under a custom global namespace
When you load Koala through snippet code, by default, the SDK installs on window.ko
global variable. If this causes a conflict with another library or code on your site, you can change the global variable used by Koala.
Change the global variable in the beginning of your snippet code as shown below. In this case, Koala uses window.custom_key
to load instead of window.ko
.
Alternatively, you can use the window.globalKoalaKey
to set the global variable.