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.

  - !function(){var k="ko", ...
  + !function(){var k="custom_key", ...

Alternatively, you can use the window.globalKoalaKey to set the global variable.

<script>
  // Koala will use this global key instead of window.ko, in this case window.custom_key
  window.globalKoalaKey = "custom_key";
</script>

<script>
  // paste your Koala snippet here
</script>