Contextual Data - Permutive

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

In the Android 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

Core SDK: 1.10.0 or higher
Google Ads Add-on: 2.2.0 or higher (for GAM integration)
AppNexus Add-on: 1.7.0 or higher (for Xandr integration)
Minimum Android API: 21 (Android 5.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/video with URL

Use PageTracker or MediaTracker with content URLs

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 android.net.Uri
import com.permutive.android.EventProperties

class ArticleActivity : AppCompatActivity() {

    private val permutive by lazy {
        (application as MyApplication).permutive
    }

    private lateinit var pageTracker: PageTracker

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_article)

        // Track page with URL - contextual analysis automatic
        pageTracker = permutive.trackPage(
            title = "Complete Guide to Electric Vehicles",
            url = Uri.parse("https://example.com/articles/electric-vehicle-guide"),
            referrer = Uri.parse("https://example.com/automotive"),
            eventProperties = EventProperties.from(
                "category" to "automotive",
                "subcategory" to "electric_vehicles",
                "author" to "Jane Smith"
            )
        )
    }

    override fun onDestroy() {
        super.onDestroy()
        pageTracker.close()
    }
}

import android.net.Uri;
import com.permutive.android.EventProperties;
import com.permutive.android.PageTracker;

public class ArticleActivity extends AppCompatActivity {

    private PageTracker pageTracker;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_article);

        Permutive permutive = ((MyApplication) getApplication()).getPermutive();

        // Track page with URL - contextual analysis automatic
        EventProperties properties = new EventProperties.Builder()
            .with("category", "automotive")
            .with("subcategory", "electric_vehicles")
            .with("author", "Jane Smith")
            .build();

        pageTracker = permutive.trackPage(
            properties,
            "Complete Guide to Electric Vehicles",
            Uri.parse("https://example.com/articles/electric-vehicle-guide"),
            Uri.parse("https://example.com/automotive")
        );
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        pageTracker.close();
    }
}

Video Tracking with Contextual Data

Contextual analysis also works with video content:

val videoTracker = permutive.trackVideoView(
    durationMilliseconds = videoDurationMs,
    videoProperties = MediaTracker.VideoProperties(
        title = "Electric Car Review: Tesla Model 3",
        genre = listOf("Automotive", "Reviews"),
        contentType = listOf("Video", "Review")
    ),
    pageProperties = MediaTracker.PageProperties(
        title = "Video: Tesla Model 3 Review",
        url = Uri.parse("https://example.com/videos/tesla-model-3-review"),
        referrer = Uri.parse("https://example.com/automotive")
    )
)

Accessing Contextual Cohorts

Contextual cohorts are automatically included in activations with special keys:

In Current Activations

val activations = permutive.currentActivations

// Google Ad Manager contextual cohorts
val gamContextual = activations["dfp_contextual"].orEmpty()
// Example: ["automotive_ev", "automotive_reviews", "tech_innovation"]

// Xandr/AppNexus contextual cohorts  
val xandrContextual = activations["appnexus_adserver_contextual"].orEmpty()

// Log contextual cohorts
Log.d("Permutive", "GAM contextual cohorts: ${gamContextual.joinToString()}")

In Ad Requests

Our add-on libraries automatically include contextual cohorts:

Google Ad Manager

import com.google.android.gms.ads.admanager.AdManagerAdRequest
import com.permutive.android.ads.addPermutiveTargeting

// Contextual cohorts automatically added with key "prmtvctx"
val adRequest = AdManagerAdRequest.Builder()
    .addPermutiveTargeting(permutive)  // Includes both behavioral and contextual
    .build()

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

Xandr/AppNexus

import com.permutive.android.appnexus.addPermutiveTargeting

// Contextual cohorts automatically added
adView.addPermutiveTargeting(permutive)
adView.loadAd()

// Custom keywords include:
// - permutive: behavioral cohorts
// - prmtvctx: contextual cohorts  
// - puid: user ID
// - ptime: timestamp

Configuration

Contextual features are controlled by server-side configuration automatically applied to your SDK:

Configuration Flags

The SDK receives configuration that controls:

Segmentation enabled - Whether content classification is active
Event enrichment - Whether contextual data is added to events
Platform activations - Which ad platforms receive contextual cohorts

Checking Configuration Status

// Configuration is applied automatically
// No manual configuration needed in the SDK

💡 Automatic Configuration Contextual features are enabled/disabled by your workspace configuration. Contact your Customer Success Manager to modify settings.

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

Impact on App Performance

Contextual analysis is designed to be lightweight:

✅ Async processing - Doesn’t block main thread
✅ Cached results - Same URLs reuse previous analysis
✅ Efficient networking - Minimal data transfer
✅ Graceful degradation - Falls back to behavioral targeting if unavailable

Best Practices for Performance

// ✅ Good: Track page early, analysis starts immediately
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_article)
    
    // Start tracking (and analysis) as early as possible
    pageTracker = permutive.trackPage(...)
    
    // Load your content
    loadArticleContent()
}

// ❌ Avoid: Delaying page tracking
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_article)
    
    loadArticleContent()
    
    // Tracking delayed - contextual cohorts may not be ready for early ads
    Handler().postDelayed({
        pageTracker = permutive.trackPage(...)
    }, 5000)
}

Privacy and Compliance

Privacy-Friendly Targeting

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.

Opt-Out Handling

If users opt out of targeting:

// If user opts out, you can still track pages but don't use contextual cohorts
val pageTracker = permutive.trackPage(...)

// Don't include contextual activations in ads
// Behavioral targeting already respects consent at SDK level

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

val contextualCohorts = permutive.currentActivations["dfp_contextual"].orEmpty()

if (contextualCohorts.isEmpty()) {
    // This is OK - may be:
    // - Feature not enabled
    // - Classification in progress
    // - Classification failed
    // - No URL tracked yet
    
    // Behavioral targeting still works
    val behavioralCohorts = permutive.currentActivations["dfp"].orEmpty()
}

Debugging Classification

Enable debug logging to see classification status:

permutive.setDeveloperMode(true)

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

Use Cases

Content-Aligned Advertising

class ArticleActivity : AppCompatActivity() {
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_article)
        
        // Track article page
        pageTracker = permutive.trackPage(
            title = article.title,
            url = Uri.parse(article.url)
        )
        
        // Load ad - contextual cohorts automatically included
        loadAd()
    }
    
    private fun loadAd() {
        // Contextual cohorts ensure ad is relevant to article content
        val adRequest = AdManagerAdRequest.Builder()
            .addPermutiveTargeting(permutive)
            .build()
        
        adView.loadAd(adRequest)
    }
}

Video Ad Targeting

class VideoPlayerActivity : AppCompatActivity() {
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        // Track video with URL
        videoTracker = permutive.trackVideoView(
            durationMilliseconds = video.duration,
            videoProperties = MediaTracker.VideoProperties(
                title = video.title,
                genre = video.genres
            ),
            pageProperties = MediaTracker.PageProperties(
                url = Uri.parse(video.url)
            )
        )
        
        // Load pre-roll ad with contextual targeting
        loadPreRollAd()
    }
    
    private fun loadPreRollAd() {
        // Ad is contextually targeted to video content
        val adRequest = AdManagerAdRequest.Builder()
            .addPermutiveTargeting(permutive)
            .build()
        
        imaAdsLoader.requestAds(adRequest)
    }
}

Contextual + Behavioral Targeting

Combine contextual and behavioral cohorts for powerful targeting:

val activations = permutive.currentActivations

// Behavioral: User interests over time
val behavioral = activations["dfp"].orEmpty()
// Example: ["sports_enthusiast", "premium_subscriber"]

// Contextual: Current content
val contextual = activations["dfp_contextual"].orEmpty()
// Example: ["sports_soccer", "sports_worldcup"]

// Both automatically included in ad requests
val adRequest = AdManagerAdRequest.Builder()
    .addPermutiveTargeting(permutive)
    .build()

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

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

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 Core 1.10.0+, Google Ads 2.2.0+, or AppNexus 1.7.0+
No URL tracked
- Ensure you’re using PageTracker or MediaTracker with URLs
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 activity 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/videos 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

API Reference

Contextual cohorts are accessed through standard SDK APIs:

Permutive.currentActivations["dfp_contextual"] - GAM contextual cohorts
Permutive.currentActivations["appnexus_adserver_contextual"] - Xandr contextual cohorts
PageTracker - Track pages with URLs for analysis
MediaTracker - Track videos with URLs for analysis

For complete API documentation, see the Javadocs.

How It Works

Implementation

Ad Targeting

​Overview

​Requirements

​How It Works

​Implementation

​Page Tracking with Contextual Data

​Video Tracking with Contextual Data

​Accessing Contextual Cohorts

​In Current Activations

​In Ad Requests

​Google Ad Manager

​Xandr/AppNexus

​Configuration

​Configuration Flags

​Checking Configuration Status

​Performance Considerations

​Content Analysis Timing

​Impact on App Performance

​Best Practices for Performance

​Privacy and Compliance

​Privacy-Friendly Targeting

​Data Sent for Analysis

​Opt-Out Handling

​Error Handling

​Classification Failures

​Debugging Classification

​Use Cases

​Content-Aligned Advertising

​Video Ad Targeting

​Contextual + Behavioral Targeting

​Contextual vs. Behavioral Cohorts

​When to Use Each

​Troubleshooting

​No Contextual Cohorts Appearing

​Classification Taking Too Long

​Wrong Contextual Cohorts

​Best Practices

​✅ Do

​❌ Don’t

​Related Documentation

​API Reference

Overview

Requirements

How It Works

Implementation

Page Tracking with Contextual Data

Video Tracking with Contextual Data

Accessing Contextual Cohorts

In Current Activations

In Ad Requests

Google Ad Manager

Xandr/AppNexus

Configuration

Configuration Flags

Checking Configuration Status

Performance Considerations

Content Analysis Timing

Impact on App Performance

Best Practices for Performance

Privacy and Compliance

Privacy-Friendly Targeting

Data Sent for Analysis

Opt-Out Handling

Error Handling

Classification Failures

Debugging Classification

Use Cases

Content-Aligned Advertising

Video Ad Targeting

Contextual + Behavioral Targeting

Contextual vs. Behavioral Cohorts

When to Use Each

Troubleshooting

No Contextual Cohorts Appearing

Classification Taking Too Long

Wrong Contextual Cohorts

Best Practices

✅ Do

❌ Don’t

Related Documentation

API Reference