Skip to main content

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 targeting allows you to reach users based on the content they’re currently viewing, without relying on user history or cookies.

Overview

Implementation

Use Cases

​
Overview

​
Privacy Benefits

​
Behavioral vs Contextual

​
Implementation

​
Page Properties

The primary way to enable contextual targeting is through page properties: 
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: 
// Watson classifications are added automatically
// when configured in your Permutive dashboard
permutive.addon('web', {
  page: {
    type: 'article',
    // Watson adds categories, concepts, entities
  }
});

​
URL-Based Context

The SDK automatically captures URL context: 
// 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: 
// 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): 
// 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

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

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

permutive.addon('web', {
  page: {
    type: 'homepage'
  }
});

​
Section/Category Page

permutive.addon('web', {
  page: {
    type: 'section',
    section: {
      name: 'Technology',
      path: '/technology',
      depth: 1
    }
  }
});

​
Use Cases

Use contextual data to ensure ads appear alongside appropriate content:
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'
    }
  }
});

​
Combining Behavioral and Contextual

The most effective targeting often combines both signals: 
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

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

Contextual Cohorts

Build contextual cohorts

Pageview Tracking

Configure page properties

Google Ad Manager

Contextual targeting in GAM

Classification Providers

Content classification integrations