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

# Installation

> Install the Permutive JavaScript SDK via script tag or tag manager

The Permutive JavaScript SDK can be installed using several methods. Choose the approach that best fits your deployment workflow.

## Installation Methods

<Tabs>
  <Tab title="Script Tag (Recommended)">
    The script tag method is the recommended approach for most websites. It provides the fastest load time and simplest setup.

    ### Basic Installation

    Add to the `<head>` section of your page, as early as possible:

    ```html theme={"dark"}
    <script>
      !function(e,o,n,i){if(!e){e=e||{},window.permutive=e,e.q=[];var t=function(){return([1e7]+-1e3+-4e3+-8e3+-1e11).replace(/[018]/g,function(e){return(e^(window.crypto||window.msCrypto).getRandomValues(new Uint8Array(1))[0]&15>>e/4).toString(16)})};e.config=i||{},e.config.apiKey=o,e.config.workspaceId=n,e.config.environment=e.config.environment||"production",(window.crypto||window.msCrypto)&&(e.config.viewId=t());for(var g=["addon","identify","track","trigger","query","segment","segments","ready","on","once","user","consent"],r=0;r<g.length;r++){var w=g[r];e[w]=function(o){return function(){var n=Array.prototype.slice.call(arguments,0);e.q.push({functionName:o,arguments:n})}}(w)}}}(window.permutive,"<WORKSPACE_API_KEY>","<WORKSPACE_ID>",{});
    </script>
    <script async src="https://<ORGANIZATION_ID>.edge.permutive.app/<WORKSPACE_ID>-web.js"></script>
    ```

    Replace:

    * `<WORKSPACE_API_KEY>` - Your [public API key](https://dash.permutive.com/settings/keys/)
    * `<WORKSPACE_ID>` - Your [workspace ID](https://dash.permutive.com/settings/project/)
    * `<ORGANIZATION_ID>` - Your organization ID

    <Warning>
      Place the SDK script **before** any other scripts that depend on it (like ad scripts or analytics). The SDK uses a queue-based pattern so methods can be called immediately, but the actual SDK must load before events are sent.
    </Warning>

    ### With Configuration Options

    Pass configuration options as the fourth argument:

    ```html theme={"dark"}
    <script>
      !function(e,o,n,i){if(!e){e=e||{},window.permutive=e,e.q=[];var t=function(){return([1e7]+-1e3+-4e3+-8e3+-1e11).replace(/[018]/g,function(e){return(e^(window.crypto||window.msCrypto).getRandomValues(new Uint8Array(1))[0]&15>>e/4).toString(16)})};e.config=i||{},e.config.apiKey=o,e.config.workspaceId=n,e.config.environment=e.config.environment||"production",(window.crypto||window.msCrypto)&&(e.config.viewId=t());for(var g=["addon","identify","track","trigger","query","segment","segments","ready","on","once","user","consent"],r=0;r<g.length;r++){var w=g[r];e[w]=function(o){return function(){var n=Array.prototype.slice.call(arguments,0);e.q.push({functionName:o,arguments:n})}}(w)}}}(window.permutive,"<WORKSPACE_API_KEY>","<WORKSPACE_ID>",{
        consentRequired: true      // Require consent before tracking
      });
    </script>
    <script async src="https://<ORGANIZATION_ID>.edge.permutive.app/<WORKSPACE_ID>-web.js"></script>
    ```
  </Tab>

  <Tab title="Google Tag Manager">
    Use GTM when you need to manage tags centrally without code deployments.

    ### Setup Steps

    1. **Create a Custom HTML Tag**
       * Go to Tags > New > Custom HTML
       * Name it "Permutive SDK"

    2. **Add the SDK Code**
       ```html theme={"dark"}
       <script>
         !function(e,o,n,i){if(!e){e=e||{},window.permutive=e,e.q=[];var t=function(){return([1e7]+-1e3+-4e3+-8e3+-1e11).replace(/[018]/g,function(e){return(e^(window.crypto||window.msCrypto).getRandomValues(new Uint8Array(1))[0]&15>>e/4).toString(16)})};e.config=i||{},e.config.apiKey=o,e.config.workspaceId=n,e.config.environment=e.config.environment||"production",(window.crypto||window.msCrypto)&&(e.config.viewId=t());for(var g=["addon","identify","track","trigger","query","segment","segments","ready","on","once","user","consent"],r=0;r<g.length;r++){var w=g[r];e[w]=function(o){return function(){var n=Array.prototype.slice.call(arguments,0);e.q.push({functionName:o,arguments:n})}}(w)}}}(window.permutive,"{{Permutive API Key}}","{{Permutive Workspace ID}}",{});
       </script>
       <script async src="https://{{Permutive Organization ID}}.edge.permutive.app/{{Permutive Workspace ID}}-web.js"></script>
       ```

    3. **Create Variables** (optional but recommended)
       * Go to Variables > User-Defined Variables > New
       * Create Constant variables for API Key and Workspace ID
       * Reference them as `{{Permutive API Key}}` and `{{Permutive Workspace ID}}`

    4. **Set the Trigger**
       * Use "All Pages" trigger
       * Set **Tag Firing Priority** to a high number (e.g., 9999) to ensure it loads first

    5. **Create Web Addon Tag**
       ```html theme={"dark"}
       <script>
         permutive.addon('web', {
           page: {
             type: '{{Page Type}}',
             article: {
               title: '{{Page Title}}',
               categories: {{Page Categories}}
             }
           }
         });
       </script>
       ```

    <Info>
      For detailed GTM setup including Data Layer integration, see the [Tag Manager Guide](/sdks/web/javascript-sdk/guides/tag-managers).
    </Info>
  </Tab>

  <Tab title="Other Tag Managers">
    ### Tealium

    1. Create a JavaScript Code extension
    2. Set execution order to "Before Load Rules"
    3. Add the SDK code with Tealium data layer variables

    ### Adobe Launch

    1. Create a Core extension action for Custom Code
    2. Place in the `<head>` using the Document section
    3. Set rule order to 1 (earliest execution)

    See the [Tag Manager Guide](/sdks/web/javascript-sdk/guides/tag-managers) for detailed instructions for each platform.
  </Tab>
</Tabs>

## Understanding the Loader Script

The inline loader script (the first `<script>` block) does the following:

1. **Creates the global `permutive` object** if it doesn't exist
2. **Initializes a queue** (`permutive.q`) to store method calls before the SDK loads
3. **Sets configuration** including API key and workspace ID
4. **Creates stub methods** (`track`, `identify`, etc.) that add calls to the queue

This pattern allows you to call SDK methods immediately without waiting for the SDK to load. Calls are queued and executed in order once the SDK initializes.

```javascript theme={"dark"}
// These calls work immediately, even before live.js loads
permutive.identify([{ tag: 'email_sha256', id: 'abc123...' }]);
permutive.track('PageView', { category: 'news' });
permutive.addon('web', { page: { type: 'article' } });
```

## SDK Source Files

The SDK is served from your organization's edge CDN:

```
https://<ORGANIZATION_ID>.edge.permutive.app/<WORKSPACE_ID>-web.js
```

<Info>
  The SDK is served from Permutive's edge CDN with appropriate caching headers. It typically loads in under 100ms on modern connections.
</Info>

## Load Order Best Practices

<Steps>
  <Step title="Load Permutive First">
    Place the Permutive script tag before other third-party scripts, especially before ad scripts.
  </Step>

  <Step title="Use Async Loading">
    The `async` attribute on the `live.js` script allows parallel loading without blocking page render.
  </Step>

  <Step title="Initialize Web Addon Early">
    Call `permutive.addon('web', {...})` immediately after the SDK script to capture the pageview event early.
  </Step>

  <Step title="Configure Consent Before Tracking">
    If using consent management, call `permutive.consent()` before initializing the web addon if `consentRequired: true`.
  </Step>
</Steps>

## Verifying Installation

After installation, verify the SDK is loading correctly:

1. Add `?__permutive.loggingEnabled=true` to your URL
2. Open the browser console (F12 > Console)
3. Look for `[Permutive]` prefixed messages
4. Check Application > Local Storage for `permutive-*` keys

## Troubleshooting Installation

<AccordionGroup>
  <Accordion title="SDK not loading">
    **Symptoms:** No `permutive` object on window, no console messages.

    **Solutions:**

    * Verify the script URL is correct (`https://<ORGANIZATION_ID>.edge.permutive.app/<WORKSPACE_ID>-web.js`)
    * Check for network errors in DevTools > Network tab
    * Ensure the inline loader script runs before the SDK script
    * Check for Content Security Policy (CSP) blocking the script
  </Accordion>

  <Accordion title="Methods not working">
    **Symptoms:** Calls to `permutive.track()` or other methods don't do anything.

    **Solutions:**

    * Verify API key and workspace ID are correct
    * Check browser console for error messages
    * Ensure the loader script created stub methods correctly
  </Accordion>

  <Accordion title="Script blocked by CSP">
    **Symptoms:** Console error about Content Security Policy.

    **Solution:** Add Permutive domains to your CSP:

    ```
    script-src 'self' https://*.permutive.app;
    connect-src 'self' https://*.permutive.com https://*.permutive.app;
    ```
  </Accordion>

  <Accordion title="Tag manager timing issues">
    **Symptoms:** Events missing or SDK not initialized when other tags fire.

    **Solutions:**

    * Set Permutive tag priority to highest (e.g., 9999 in GTM)
    * Use `permutive.ready()` in dependent tags to wait for SDK
    * Ensure trigger fires on "All Pages" before other triggers
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Initialization" icon="gear" href="/sdks/web/javascript-sdk/getting-started/initialization">
    Configure SDK options
  </Card>

  <Card title="Verification" icon="circle-check" href="/sdks/web/javascript-sdk/getting-started/verification">
    Verify your integration
  </Card>
</CardGroup>
