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

> Real-time content-based segmentation for privacy-friendly targeting

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

<CardGroup cols={3}>
  <Card title="How It Works" href="#how-it-works" icon="gear" />

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

  <Card title="Ad Targeting" href="#in-ad-requests" icon="bullseye" />
</CardGroup>

## Overview

<ContextualOverview />

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

<Info>
  **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.
</Info>

## How It Works

<Steps>
  <Step title="Track page/video with URL">
    Use `PageTracker` or `MediaTracker` with content URLs
  </Step>

  <Step title="Content analyzed">
    Permutive analyzes the content at the URL (page title, main text, keywords, IAB categories, sentiment)
  </Step>

  <Step title="Contextual cohorts generated">
    Content-based segments are created in real-time
  </Step>

  <Step title="Automatic activation">
    Contextual cohorts automatically included in ad requests
  </Step>
</Steps>

***

## Implementation

### Page Tracking with Contextual Data

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

<CodeGroup>
  ```kotlin Kotlin theme={"dark"}
  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()
      }
  }
  ```

  ```java Java theme={"dark"}
  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();
      }
  }
  ```
</CodeGroup>

### Video Tracking with Contextual Data

Contextual analysis also works with video content:

```kotlin theme={"dark"}
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

```kotlin theme={"dark"}
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

```kotlin theme={"dark"}
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

```kotlin theme={"dark"}
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

```kotlin theme={"dark"}
// 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

```kotlin theme={"dark"}
// ✅ 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

<ContextualPrivacy />

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

```kotlin theme={"dark"}
// 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:**

```kotlin theme={"dark"}
// 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:

```kotlin theme={"dark"}
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

```kotlin theme={"dark"}
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

```kotlin theme={"dark"}
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:

```kotlin theme={"dark"}
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

<ContextualVsBehavioralTable />

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

1. **Feature not enabled**
   * Contact Customer Success Manager to enable

2. **SDK version too old**
   * Update to Core 1.10.0+, Google Ads 2.2.0+, or AppNexus 1.7.0+

3. **No URL tracked**
   * Ensure you're using `PageTracker` or `MediaTracker` with URLs

4. **Classification in progress**
   * First analysis may take 1-2 seconds
   * Check again after a moment

5. **URL not accessible**
   * Ensure URL is publicly accessible
   * Remove authentication requirements for analysis

6. **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

***

## Related Documentation

* [Cohorts and Activations](/sdks/mobile/android/core-concepts/cohorts-and-activations)
* [Page Tracking](/sdks/mobile/android/features/page-tracking)
* [Video Tracking](/sdks/mobile/android/features/video-tracking)
* [Google Ad Manager Integration](/sdks/mobile/android/integrations/google-ad-manager)
* [Xandr Integration](/sdks/mobile/android/integrations/appnexus-xandr)

***

## 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](https://sdk-docs.permutive.com/index.html).