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

# Contextual Data

> Content-based real-time targeting with the Permutive JavaScript SDK

export const ContextualVsBehavioralTable = () => <table>
    <thead>
      <tr>
        <th>Aspect</th>
        <th>Behavioral Cohorts</th>
        <th>Contextual Cohorts</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><strong>Based on</strong></td>
        <td>User history</td>
        <td>Current content</td>
      </tr>
      <tr>
        <td><strong>Speed</strong></td>
        <td>Minutes to hours</td>
        <td>Real-time</td>
      </tr>
      <tr>
        <td><strong>Persistence</strong></td>
        <td>Long-term</td>
        <td>Session/page</td>
      </tr>
      <tr>
        <td><strong>Privacy</strong></td>
        <td>Requires user profile</td>
        <td>No profiling needed</td>
      </tr>
      <tr>
        <td><strong>Accuracy</strong></td>
        <td>Improves over time</td>
        <td>Immediate</td>
      </tr>
      <tr>
        <td><strong>Use Case</strong></td>
        <td>Audience targeting</td>
        <td>Content alignment</td>
      </tr>
    </tbody>
  </table>;

export const ContextualPrivacy = () => <>
    <p>Contextual Cohorts operate entirely on page-level data, requiring no user consent. This enables publishers to monetize inventory from users who haven't consented to data collection, expanding addressable inventory while maintaining privacy compliance.</p>
    <p>Key privacy benefits:</p>
    <ul>
      <li><strong>No user data processing</strong> - Targets content, not user behavior</li>
      <li><strong>No consent required</strong> - Works for all users regardless of consent status</li>
      <li><strong>No cross-site tracking</strong> - Only analyzes current page content</li>
      <li><strong>Cookie-less</strong> - Works without third-party cookies or persistent identifiers</li>
    </ul>
  </>;

export const ContextualOverview = () => <>
    <p><strong>Contextual Cohorts</strong> enable publishers to target ads based on contextual data derived from page content without processing or storing any user data. Since no user consent is required, Contextual Cohorts allow publishers to reach users who have not given consent and cannot be targeted with behavioral data today.</p>
    <p>Contextual Cohorts work by analyzing page-level signals such as automated content classifications, editorial metadata, and affinity scores from consented users. This enables publishers to create a differentiated contextual targeting offering that combines the precision of content understanding with the unique insights from their first-party data.</p>
  </>;

Contextual targeting allows you to reach users based on the content they're currently viewing, without relying on user history or cookies.

<CardGroup cols={3}>
  <Card title="Overview" href="#overview" icon="bullseye" />

  <Card title="Implementation" href="#implementation" icon="code" />

  <Card title="Use Cases" href="#use-cases" icon="lightbulb" />
</CardGroup>

## Overview

<ContextualOverview />

## Privacy Benefits

<ContextualPrivacy />

## Behavioral vs Contextual

<ContextualVsBehavioralTable />

## Implementation

### Page Properties

The primary way to enable contextual targeting is through page properties:

```javascript theme={"dark"}
permutive.addon('web', {
  page: {
    type: 'article',
    article: {
      title: 'Electric Vehicle Sales Surge in 2024',
      categories: ['automotive', 'electric-vehicles', 'business'],
      tags: ['EV', 'Tesla', 'sustainability', 'green-tech'],
      authors: ['Jane Smith'],
      publishedAt: '2024-01-15T10:00:00Z'
    }
  }
});
```

These properties are analyzed to generate contextual cohorts like:

* `automotive_electric_vehicles`
* `business_sustainability`
* `technology_green_tech`

### Content Classifications

Permutive can integrate with content classification providers for automated contextual data:

<Tabs>
  <Tab title="IBM Watson">
    ```javascript theme={"dark"}
    // Watson classifications are added automatically
    // when configured in your Permutive dashboard
    permutive.addon('web', {
      page: {
        type: 'article',
        // Watson adds categories, concepts, entities
      }
    });
    ```
  </Tab>

  <Tab title="Custom Classifications">
    ```javascript theme={"dark"}
    // Pass your own classifications
    permutive.addon('web', {
      page: {
        type: 'article',
        classifications: {
          iab_categories: ['IAB19-6', 'IAB13-7'],
          sentiment: 'positive',
          topics: ['technology', 'innovation']
        }
      }
    });
    ```
  </Tab>
</Tabs>

### URL-Based Context

The SDK automatically captures URL context:

```javascript theme={"dark"}
// Current URL is automatically included
// https://example.com/technology/electric-vehicles/article-123

// You can also specify explicit context
permutive.addon('web', {
  context: {
    url: 'https://example.com/technology/article',
    title: 'Article Title',
    referrer: document.referrer
  },
  page: {
    type: 'article'
  }
});
```

## Contextual Cohorts

### How They Work

1. **Page loads** with content metadata
2. **SDK sends context** to Permutive
3. **Real-time analysis** determines applicable contextual cohorts
4. **Cohorts returned** immediately (milliseconds)
5. **Ad requests** include contextual targeting

```
Page about electric vehicles loads
            ↓
SDK sends: categories: ['automotive', 'electric-vehicles']
            ↓
Permutive returns: contextual cohort 'auto_ev_interest'
            ↓
Ad request includes contextual targeting
```

### Accessing Contextual Cohorts

Contextual cohorts are included in segment calls:

```javascript theme={"dark"}
// Get all segments including contextual
permutive.segments(function(segments) {
  console.log('All segments (incl. contextual):', segments);
});

// Get DFP segments (includes contextual activations)
permutive.segments(function(segments) {
  console.log('DFP segments:', segments);
  // Includes both behavioral and contextual
}, 'dfp');
```

### Contextual-Only Targeting

For users without behavioral data (new visitors, no consent):

```javascript theme={"dark"}
// Contextual cohorts work without user consent
// because they're based on content, not user history

permutive.addon('web', {
  page: {
    type: 'article',
    article: {
      categories: ['finance', 'investing']
    }
  }
});

// Even without consent, contextual targeting is available
```

## Page Property Best Practices

### Article Pages

```javascript theme={"dark"}
permutive.addon('web', {
  page: {
    type: 'article',
    article: {
      // Required
      title: 'Article Title',
      categories: ['primary-category', 'secondary-category'],

      // Recommended
      tags: ['keyword1', 'keyword2', 'keyword3'],
      authors: ['Author Name'],
      publishedAt: '2024-01-15T10:00:00Z',

      // Optional - enhances targeting
      id: 'article-123',
      section: 'Technology',
      premium: false,
      wordCount: 1500,
      readTime: 7
    }
  }
});
```

### Video Pages

```javascript theme={"dark"}
permutive.addon('web', {
  page: {
    type: 'video',
    video: {
      title: 'Video Title',
      id: 'video-123',
      categories: ['entertainment', 'music'],
      duration: 180,  // seconds
      series: 'Music Reviews',
      season: 2,
      episode: 5
    }
  }
});
```

### Homepage

```javascript theme={"dark"}
permutive.addon('web', {
  page: {
    type: 'homepage'
  }
});
```

### Section/Category Page

```javascript theme={"dark"}
permutive.addon('web', {
  page: {
    type: 'section',
    section: {
      name: 'Technology',
      path: '/technology',
      depth: 1
    }
  }
});
```

## Use Cases

<Tabs>
  <Tab title="Brand Safety">
    Use contextual data to ensure ads appear alongside appropriate content:

    ```javascript theme={"dark"}
    permutive.addon('web', {
      page: {
        type: 'article',
        article: {
          categories: ['news', 'politics'],
          // Contextual cohorts can be used for
          // brand safety exclusions
          brand_safe: true,
          content_rating: 'general'
        }
      }
    });
    ```
  </Tab>

  <Tab title="Cookieless Targeting">
    Reach users without cookies or consent:

    ```javascript theme={"dark"}
    // Works for all users regardless of consent status
    permutive.addon('web', {
      page: {
        type: 'article',
        article: {
          categories: ['travel', 'europe'],
          // Contextual targeting doesn't require
          // user tracking or consent
        }
      }
    });
    ```
  </Tab>

  <Tab title="Content Alignment">
    Align ads with editorial content:

    ```javascript theme={"dark"}
    permutive.addon('web', {
      page: {
        type: 'article',
        article: {
          title: 'Best Running Shoes for 2024',
          categories: ['fitness', 'gear-reviews'],
          tags: ['running', 'shoes', 'athletics'],
          // Ads for running products can target
          // this contextual signal
        }
      }
    });
    ```
  </Tab>

  <Tab title="Seasonal Content">
    Target based on timely content:

    ```javascript theme={"dark"}
    permutive.addon('web', {
      page: {
        type: 'article',
        article: {
          categories: ['holidays', 'gift-guides'],
          seasonal: 'christmas',
          // Seasonal advertisers can target
          // holiday content
        }
      }
    });
    ```
  </Tab>
</Tabs>

## Combining Behavioral and Contextual

The most effective targeting often combines both signals:

```javascript theme={"dark"}
permutive.ready(function() {
  permutive.segments(function(allSegments) {
    // allSegments includes both:
    // - Behavioral cohorts (user history)
    // - Contextual cohorts (current page)

    // Use for comprehensive targeting
    googletag.cmd.push(function() {
      googletag.pubads().setTargeting('permutive', allSegments);
    });
  });
}, 'realtime');
```

## Contextual Data Flow

```
┌─────────────────┐
│   Page Load     │
│ (with context)  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  SDK Captures   │
│ page properties │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│    Permutive    │
│ Classification  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Contextual    │
│ Cohorts Returned│
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Ad Request    │
│  (with cohorts) │
└─────────────────┘
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Contextual cohorts not appearing">
    **Problem:** Page properties set but no contextual cohorts.

    **Solutions:**

    * Verify page properties in debug mode
    * Check that contextual cohorts are configured in dashboard
    * Ensure categories match configured cohort rules
    * Allow a few seconds for processing
  </Accordion>

  <Accordion title="Wrong contextual classification">
    **Problem:** Page classified incorrectly.

    **Solutions:**

    * Review page property values
    * Use more specific categories/tags
    * Check for conflicting signals in page data
    * Contact support for classification tuning
  </Accordion>

  <Accordion title="Contextual targeting not working in ads">
    **Problem:** Contextual cohorts exist but ads not targeting.

    **Solutions:**

    * Verify contextual cohorts are activated for the ad platform
    * Check `_pdfps` (or platform-specific key) in localStorage
    * Confirm ad server is reading targeting values
    * Test with debug mode enabled
  </Accordion>
</AccordionGroup>

## Related Documentation

<CardGroup cols={2}>
  <Card title="Contextual Cohorts" icon="bullseye" href="/products/signals/cohorts/contextual">
    Build contextual cohorts
  </Card>

  <Card title="Pageview Tracking" icon="file" href="/sdks/web/javascript-sdk/features/pageview-tracking">
    Configure page properties
  </Card>

  <Card title="Google Ad Manager" icon="rectangle-ad" href="/sdks/web/javascript-sdk/integrations/google-ad-manager">
    Contextual targeting in GAM
  </Card>

  <Card title="Classification Providers" icon="wand-magic-sparkles" href="/integrations/contextual/catalog">
    Content classification integrations
  </Card>
</CardGroup>