Contextual Data

Contextual data enables real-time content-based segmentation without relying on historical user behavior. The SDK analyzes content users are viewing and generates contextual cohorts instantly.

How It Works

Implementation

Ad Targeting

Overview

Contextual Cohorts 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.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. In the iOS SDK, contextual cohorts are generated in real-time when you track pages or videos with URLs. The SDK automatically includes these cohorts in ad requests alongside behavioral cohorts.

Requirements

SDK Version: 2.0.0 or higher
Platform: iOS 12.0+ / tvOS 12.0+
Feature Enablement: Contact your Customer Success Manager

Feature Activation Required: Contextual content classification must be enabled by Permutive for your workspace. Please contact your Customer Success Manager if you’d like to use this feature.

How It Works

Track page with URL

Use PageTracker with a content URL

Content analyzed

Permutive analyzes the content at the URL (page title, main text, keywords, IAB categories, sentiment)

Contextual cohorts generated

Content-based segments are created in real-time

Automatic activation

Contextual cohorts automatically included in ad requests

Implementation

Page Tracking with Contextual Data

Simply include URLs when tracking pages - contextual analysis happens automatically:

import UIKit
import Permutive_iOS

class ArticleViewController: UIViewController {
    private var pageTracker: PageTrackerProtocol?

    override func viewDidLoad() {
        super.viewDidLoad()

        // Create event properties
        let properties = try? EventProperties([
            "category": "automotive",
            "subcategory": "electric_vehicles",
            "author": "Jane Smith"
        ])

        // Track page with URL - contextual analysis automatic
        let context = Context(
            title: "Complete Guide to Electric Vehicles",
            url: URL(string: "https://example.com/articles/electric-vehicle-guide"),
            referrer: URL(string: "https://example.com/automotive")
        )

        pageTracker = try? Permutive.shared.createPageTracker(
            properties: properties,
            context: context
        )
    }

    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        try? pageTracker?.resume()
    }

    override func viewDidDisappear(_ animated: Bool) {
        super.viewDidDisappear(animated)
        pageTracker?.pause()
    }

    deinit {
        pageTracker?.stop()
    }
}

Accessing Contextual Cohorts

Contextual cohorts are automatically included in activations with special keys:

In Current Activations

let activations = Permutive.shared.activations

// Google Ad Manager contextual cohorts
let gamContextual = activations["dfp_contextual"] ?? []
// Example: ["automotive_ev", "automotive_reviews", "tech_innovation"]

// Xandr/AppNexus contextual cohorts
let xandrContextual = activations["appnexus_adserver_contextual"] ?? []

// Log contextual cohorts
print("GAM contextual cohorts: \(gamContextual)")

In Ad Requests

Contextual cohorts are automatically included when using googleCustomTargeting:

// Contextual cohorts automatically added with key "prmtvctx"
let adRequest = GAMRequest()
adRequest.customTargeting = Permutive.shared.googleCustomTargeting(
    adTargetable: pageTracker  // Include PageTracker for view ID
)
bannerView.load(adRequest)

// The resulting ad request includes:
// - permutive: ["123", "456"]           // Behavioral cohorts
// - prmtvctx: ["cabf", "cabc", "bzwu"]  // Contextual cohorts
// - puid: "user_id"
// - ptime: "timestamp"
// - prmtvvid: "view_id"

Performance Considerations

Content Analysis Timing

First analysis: May take 1-2 seconds for initial content fetch and analysis
Cached results: Subsequent views of the same URL use cached analysis
Background processing: Analysis happens asynchronously, doesn’t block UI
Network required: Content classification requires network connectivity

Best Practices for Performance

// ✅ Good: Create PageTracker early, analysis starts immediately
override func viewDidLoad() {
    super.viewDidLoad()

    // Start tracking (and analysis) as early as possible
    pageTracker = try? Permutive.shared.createPageTracker(
        properties: properties,
        context: context
    )

    // Load your content
    loadArticleContent()
}

Privacy and Compliance

Privacy-Friendly Targeting

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.Key privacy benefits:

No user data processing - Targets content, not user behavior
No consent required - Works for all users regardless of consent status
No cross-site tracking - Only analyzes current page content
Cookie-less - Works without third-party cookies or persistent identifiers

Data Sent for Analysis

When tracking a page with a URL:

URL - The page URL for content fetching
Title - Page title (if provided)
No PII - No personal information sent for classification

The URL should be publicly accessible for content analysis to work.

Error Handling

Classification Failures

Contextual classification may fail if:

URL is not publicly accessible
Content is behind a paywall or login
Network connectivity issues
Server-side analysis errors

The SDK handles failures gracefully:

// If contextual classification fails:
// 1. Behavioral cohorts still work
// 2. Events still tracked
// 3. No error surfaced to app
// 4. Contextual activations will be empty

let contextualCohorts = Permutive.shared.activations["dfp_contextual"] ?? []

if contextualCohorts.isEmpty {
    // This is OK - may be:
    // - Feature not enabled
    // - Classification in progress
    // - Classification failed
    // - No URL tracked yet

    // Behavioral targeting still works
    let behavioralCohorts = Permutive.shared.activations["dfp"] ?? []
}

Debugging Classification

Enable debug logging to see classification status:

options.logModes = LogMode.all

// Look for logs like:
// Permutive: [info] Contextual classification requested for URL: https://...
// Permutive: [info] Contextual cohorts received: [cohort1, cohort2, ...]
// Permutive: [error] Contextual classification failed: <reason>

Use Cases

Content-Aligned Advertising

class ArticleViewController: UIViewController {
    private var pageTracker: PageTrackerProtocol?

    override func viewDidLoad() {
        super.viewDidLoad()

        // Track article page
        let context = Context(
            title: article.title,
            url: URL(string: article.url),
            referrer: nil
        )
        pageTracker = try? Permutive.shared.createPageTracker(
            properties: nil,
            context: context
        )
    }

    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        try? pageTracker?.resume()

        // Load ad - contextual cohorts automatically included
        loadAd()
    }

    private func loadAd() {
        // Contextual cohorts ensure ad is relevant to article content
        let adRequest = GAMRequest()
        adRequest.customTargeting = Permutive.shared.googleCustomTargeting(
            adTargetable: pageTracker
        )
        bannerView.load(adRequest)
    }
}

Contextual + Behavioral Targeting

Combine contextual and behavioral cohorts for powerful targeting:

let activations = Permutive.shared.activations

// Behavioral: User interests over time
let behavioral = activations["dfp"] ?? []
// Example: ["sports_enthusiast", "premium_subscriber"]

// Contextual: Current content
let contextual = activations["dfp_contextual"] ?? []
// Example: ["sports_soccer", "sports_worldcup"]

// Both automatically included in ad requests
let adRequest = GAMRequest()
adRequest.customTargeting = Permutive.shared.googleCustomTargeting(
    adTargetable: pageTracker
)

// Ad platform receives:
// - permutive: ["sports_enthusiast", "premium_subscriber"]
// - prmtvctx: ["sports_soccer", "sports_worldcup"]
//
// Result: Highly targeted ad for soccer content to a sports enthusiast

Contextual vs. Behavioral Cohorts

Aspect	Behavioral Cohorts	Contextual Cohorts
Based on	User history	Current content
Speed	Minutes to hours	Real-time
Persistence	Long-term	Session/page
Privacy	Requires user profile	No profiling needed
Accuracy	Improves over time	Immediate
Use Case	Audience targeting	Content alignment

In the SDK, contextual cohorts use activation keys dfp_contextual and appnexus_adserver_contextual, while behavioral cohorts use dfp and appnexus_adserver.

When to Use Each

Use Behavioral Cohorts When:

Building long-term audience segments
Retargeting campaigns
Personalization based on user history
Lookalike modeling

Use Contextual Cohorts When:

Real-time content alignment needed
Privacy regulations are strict
New users without history
Brand safety is critical
Cookie-less environment

Use Both When:

Maximum targeting precision needed
Combining user intent (contextual) with user interests (behavioral)
Premium inventory requires both signals

tvOS Considerations

tvOS Note: Contextual data works identically on tvOS. Provide URLs in the Context when creating PageTrackers for content analysis.

Troubleshooting

No contextual cohorts appearing

Problem: dfp_contextual is empty or not present.Possible Causes & Solutions:

Feature not enabled
- Contact Customer Success Manager to enable
SDK version too old
- Update to SDK 2.0.0+
No URL tracked
- Ensure you’re using PageTracker with a Context that has a valid URL
Classification in progress
- First analysis may take 1-2 seconds
- Check again after a moment
URL not accessible
- Ensure URL is publicly accessible
- Remove authentication requirements for analysis
Network issues
- Check device connectivity
- Look for network errors in logs

Classification taking too long

Problem: Contextual cohorts not appearing before ads load.Solutions:

Start page tracking earlier in view lifecycle
Consider delaying ad request slightly if contextual is critical
Use behavioral cohorts as fallback

Wrong contextual cohorts

Problem: Cohorts don’t match content.Possible Causes:

URL points to different content than displayed
Content changed since classification
Cache from previous analysis

Solutions:

Ensure URL matches actual content
Use unique URLs for different content
Wait for cache expiry or contact support to invalidate

Best Practices

Do

Track pages with URLs as early as possible
Use publicly accessible URLs
Ensure URLs are stable and won’t change
Test with debug logging enabled
Use unique URLs for different content
Combine with behavioral targeting for best results

Don’t

Use authentication-protected URLs
Track pages without URLs (contextual won’t work)
Expect instant results (allow 1-2 seconds)
Rely solely on contextual for returning users
Use duplicate URLs for different content

Cohorts and Activations

Understanding user segmentation

Page Tracking

PageTracker guide

Google Ad Manager

GAM integration

Xandr Integration

AppNexus integration

Get Started

Products

SDKs

Governance

How It Works

Implementation

Ad Targeting

Overview

Requirements

How It Works

Implementation

Page Tracking with Contextual Data

Accessing Contextual Cohorts

In Current Activations

In Ad Requests

Performance Considerations

Content Analysis Timing

Best Practices for Performance

Privacy and Compliance

Privacy-Friendly Targeting

Data Sent for Analysis

Error Handling

Classification Failures

Debugging Classification

Use Cases

Content-Aligned Advertising

Contextual + Behavioral Targeting

Contextual vs. Behavioral Cohorts

When to Use Each

tvOS Considerations

Troubleshooting

Best Practices

Do

Don’t

Cohorts and Activations

Page Tracking

Google Ad Manager

Xandr Integration

Get Started

Products

SDKs

Governance

How It Works

Implementation

Ad Targeting

​Overview

​Requirements

​How It Works

​Implementation

​Page Tracking with Contextual Data

​Accessing Contextual Cohorts

​In Current Activations

​In Ad Requests

​Performance Considerations

​Content Analysis Timing

​Best Practices for Performance

​Privacy and Compliance

​Privacy-Friendly Targeting

​Data Sent for Analysis

​Error Handling

​Classification Failures

​Debugging Classification

​Use Cases

​Content-Aligned Advertising

​Contextual + Behavioral Targeting

​Contextual vs. Behavioral Cohorts

​When to Use Each

​tvOS Considerations

​Troubleshooting

​Best Practices

​Do

​Don’t

​Related Documentation

Cohorts and Activations

Page Tracking

Google Ad Manager

Xandr Integration

Overview

Requirements

How It Works

Implementation

Page Tracking with Contextual Data

Accessing Contextual Cohorts

In Current Activations

In Ad Requests

Performance Considerations

Content Analysis Timing

Best Practices for Performance

Privacy and Compliance

Privacy-Friendly Targeting

Data Sent for Analysis

Error Handling

Classification Failures

Debugging Classification

Use Cases

Content-Aligned Advertising

Contextual + Behavioral Targeting

Contextual vs. Behavioral Cohorts

When to Use Each

tvOS Considerations

Troubleshooting

Best Practices

Do

Don’t

Related Documentation