> ## 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.

# JavaScript SDK

> Integrate Permutive into your website for user segmentation, personalization, and ad targeting

<CardGroup cols={4}>
  <Card title="Quick Start" href="/sdks/web/javascript-sdk/getting-started/quick-start" icon="rocket" />

  <Card title="Features" href="#features" icon="puzzle-piece" />

  <Card title="Integrations" href="#integrations" icon="plug" />

  <Card title="Issues" href="/sdks/web/javascript-sdk/troubleshooting/common-errors" icon="triangle-exclamation" />
</CardGroup>

## Overview

The Permutive JavaScript SDK enables user segmentation, personalization, and ad targeting on your website. Track user behavior, manage identities, and deliver targeted advertising through integrations with major ad platforms including Google Ad Manager, Prebid.js, and Xandr.

**Current Version:** See your Permutive dashboard for the latest version.

<Info>
  **Browser Support:** The SDK supports all modern browsers including Chrome, Firefox, Safari, and Edge. It is designed to work in environments without third-party cookies.
</Info>

## Getting Started

New to the Permutive JavaScript SDK? Start here.

<CardGroup cols={2}>
  <Card title="Quick Start Guide" icon="rocket" href="/sdks/web/javascript-sdk/getting-started/quick-start">
    Get up and running with your first pageview in minutes
  </Card>

  <Card title="Installation" icon="download" href="/sdks/web/javascript-sdk/getting-started/installation">
    Script tag and tag manager installation options
  </Card>

  <Card title="Initialization" icon="gear" href="/sdks/web/javascript-sdk/getting-started/initialization">
    SDK initialization and configuration options
  </Card>

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

## Core Concepts

Understand the fundamental concepts of the Permutive SDK.

<CardGroup cols={2}>
  <Card title="Identity Management" icon="user" href="/sdks/web/javascript-sdk/core-concepts/identity-management">
    Track users across sessions and devices
  </Card>

  <Card title="Event Properties" icon="list" href="/sdks/web/javascript-sdk/core-concepts/event-properties">
    Structure and validate event data
  </Card>

  <Card title="Cohorts and Activations" icon="users" href="/sdks/web/javascript-sdk/core-concepts/cohorts-and-activations">
    Understanding user segmentation
  </Card>

  <Card title="Contextual Data" icon="bullseye" href="/sdks/web/javascript-sdk/core-concepts/contextual-data">
    Content-based real-time targeting
  </Card>

  <Card title="Consent Management" icon="shield-check" href="/sdks/web/javascript-sdk/core-concepts/consent-management">
    GDPR, TCF, and consent handling
  </Card>
</CardGroup>

## Features

Detailed guides for specific SDK features.

<CardGroup cols={2}>
  <Card title="Pageview Tracking" icon="file" href="/sdks/web/javascript-sdk/features/pageview-tracking">
    Automatic and manual pageview tracking with the web addon
  </Card>

  <Card title="Event Tracking" icon="bolt" href="/sdks/web/javascript-sdk/features/event-tracking">
    Track custom events with track(), on(), and once()
  </Card>

  <Card title="Video Tracking" icon="video" href="/sdks/web/javascript-sdk/features/video-tracking">
    Track video content viewing
  </Card>

  <Card title="Real-Time Triggers" icon="bell" href="/sdks/web/javascript-sdk/features/real-time-triggers">
    React to cohort changes with trigger(), segment(), and query()
  </Card>
</CardGroup>

## Integrations

Connect Permutive with ad platforms and header bidding solutions.

<CardGroup cols={2}>
  <Card title="View All Integrations" icon="plug" href="/sdks/web/javascript-sdk/integrations/overview">
    Google Ad Manager, Prebid.js, Xandr, and more
  </Card>
</CardGroup>

## Common Tasks

<AccordionGroup>
  <Accordion title="Track a Pageview" icon="file">
    The web addon automatically tracks pageviews when configured. You can also include custom page properties.

    ```javascript theme={"dark"}
    permutive.addon('web', {
      page: {
        type: 'article',
        article: {
          title: 'Breaking News: Tech Advances',
          categories: ['technology', 'news'],
          authors: ['Jane Smith'],
          publishedAt: '2024-01-15'
        }
      }
    });
    ```
  </Accordion>

  <Accordion title="Track a Custom Event" icon="bolt">
    ```javascript theme={"dark"}
    permutive.track('Purchase', {
      product_id: 'SKU123',
      product_name: 'Premium Subscription',
      price: 9.99,
      currency: 'USD'
    });
    ```
  </Accordion>

  <Accordion title="Set User Identity" icon="user">
    ```javascript theme={"dark"}
    // Simple identity
    permutive.identify([
      { tag: 'email_sha256', id: 'a1b2c3d4e5f6...' },
      { tag: 'internal_id', id: 'user_12345', priority: 1 }
    ]);
    ```
  </Accordion>

  <Accordion title="React to Cohort Changes" icon="bell">
    ```javascript theme={"dark"}
    // Check if user is in a specific cohort
    permutive.segment(12345, function(inCohort) {
      if (inCohort) {
        showPremiumContent();
      }
    });

    // Get all cohorts
    permutive.segments(function(segments) {
      console.log('User cohorts:', segments);
    });
    ```
  </Accordion>

  <Accordion title="Target Google Ads" icon="bullseye">
    ```javascript theme={"dark"}
    // Using the DFP addon (automatically sets targeting)
    permutive.addon('web', { page: { /* ... */ } });

    // Or manually get segments for GPT
    permutive.segments(function(segments) {
      googletag.cmd.push(function() {
        googletag.pubads().setTargeting('permutive', segments);
      });
    }, 'dfp');
    ```
  </Accordion>
</AccordionGroup>

## Key API Methods

| Method                                    | Purpose                        |
| ----------------------------------------- | ------------------------------ |
| `permutive.track(event, properties)`      | Track custom events            |
| `permutive.identify(identities)`          | Set user identities            |
| `permutive.trigger(code, param, handler)` | React to cohort entry/exit     |
| `permutive.segment(code, handler)`        | Check single cohort membership |
| `permutive.segments(handler, type)`       | Get all cohorts                |
| `permutive.query(code, handler)`          | Reserved for future use        |
| `permutive.ready(callback, stage)`        | Wait for SDK initialization    |
| `permutive.consent(data)`                 | Set consent status             |
| `permutive.addon(name, options)`          | Initialize addons              |
| `permutive.on(event, callback)`           | Persistent event listener      |
| `permutive.once(event, callback)`         | Single event listener          |
| `permutive.reset()`                       | Clear user data                |

## Requirements

| Requirement  | Details                                               |
| ------------ | ----------------------------------------------------- |
| Browsers     | Modern browsers (Chrome, Firefox, Safari, Edge)       |
| JavaScript   | ES5+ (SDK is transpiled for compatibility)            |
| Cookies      | First-party cookies required for identity persistence |
| localStorage | Required for cohort storage                           |

## Installation

<Tabs>
  <Tab title="Script Tag (Recommended)">
    Add to the `<head>` 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>`, `<WORKSPACE_ID>`, and `<ORGANIZATION_ID>` with your credentials from the Permutive dashboard.
  </Tab>

  <Tab title="Tag Manager">
    Add the Permutive tag as a high-priority tag that fires on all pages. See the [Tag Manager Guide](/sdks/web/javascript-sdk/guides/tag-managers) for GTM, Tealium, and Adobe Launch setup.
  </Tab>
</Tabs>

## Key Concepts

<AccordionGroup>
  <Accordion title="Queue-Based Loading">
    The SDK uses a queue-based loading pattern. Methods called before the SDK loads are queued and executed in order once the SDK initializes. This means you can safely call SDK methods immediately without waiting for load.
  </Accordion>

  <Accordion title="Cohorts vs. Activations">
    * **Cohorts**: All segments a user belongs to
    * **Activations**: Cohorts configured for specific ad platforms (e.g., `dfp` for Google Ad Manager)
  </Accordion>

  <Accordion title="Behavioral vs. Contextual">
    * **Behavioral**: Based on user history (e.g., "sports enthusiast")
    * **Contextual**: Based on current page content (e.g., viewing sports article right now)
  </Accordion>

  <Accordion title="Web Addon">
    The `web` addon provides automatic tracking for pageviews, engagement time, form submissions, and link clicks. It's the recommended way to track user activity.
  </Accordion>
</AccordionGroup>

## Additional Resources

<Tabs>
  <Tab title="Guides">
    * **[Tag Manager Setup](/sdks/web/javascript-sdk/guides/tag-managers)** - GTM, Tealium, Adobe Launch
    * **[Single Page Applications](/sdks/web/javascript-sdk/features/pageview-tracking#spa-support)** - React, Vue, Angular integration
  </Tab>

  <Tab title="Reference">
    * **[Prebid Integration](/integrations/advertising/bidstream/prebid)** - RTD and Identity Manager modules
    * **[Consent](/governance/consent)** - Consent mechanisms and GDPR compliance
  </Tab>
</Tabs>

## FAQ

<AccordionGroup>
  <Accordion title="Does the SDK work without third-party cookies?">
    Yes. The Permutive SDK uses first-party cookies and localStorage, which are not affected by third-party cookie restrictions. It works effectively in Safari, Firefox, and other browsers that block third-party cookies.
  </Accordion>

  <Accordion title="How do I enable debug logging?">
    Add `?__permutive.loggingEnabled=true` to any page URL to enable debug logging in the browser console. You'll see detailed information about events, cohorts, and SDK activity.
  </Accordion>

  <Accordion title="What's the difference between track() and the web addon?">
    The **web addon** automatically tracks standard events (Pageview, PageviewEngagement, FormSubmission, LinkClick) with minimal configuration. Use `track()` for custom events that don't fit these patterns.
  </Accordion>

  <Accordion title="How do I handle consent/GDPR?">
    Set `consentRequired: true` in your configuration, then call `permutive.consent({ opt_in: true, token: '...' })` after obtaining user consent. See the [Consent Management](/sdks/web/javascript-sdk/core-concepts/consent-management) guide for details.
  </Accordion>

  <Accordion title="Does the SDK support Single Page Applications?">
    Yes. Call `permutive.addon('web', { page: {...} })` on each route change to track new pageviews. See [Pageview Tracking](/sdks/web/javascript-sdk/features/pageview-tracking#spa-support) for details.
  </Accordion>
</AccordionGroup>

## Getting Help

* **[Chrome Extension](/sdks/web/javascript-sdk/troubleshooting/chrome-extension)** - Visual deployment validation and debugging
* **[Troubleshooting Guide](/sdks/web/javascript-sdk/troubleshooting/common-errors)** - Solutions to common issues
* **Customer Success Manager** - Your primary contact
* **[Technical Services](mailto:technical-services@permutive.com)** - Technical integration support

## Privacy & Compliance

Permutive is designed with privacy in mind: GDPR compliant, CCPA compliant, no PII storage, user consent respected, and transparent data usage.