> ## Documentation Index
> Fetch the complete documentation index at: https://getkoala.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Install Koala

> Learn how to install the Koala JavaScript SDK.

See [the Quick Start](/docs/get-started/quick-start#copy-the-snippet) 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.

<Note>
  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.
</Note>

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](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`.

```diff theme={null}
  - !function(){var k="ko", ...
  + !function(){var k="custom_key", ...
```

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

```html theme={null}
<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>
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.