Skip to main content
The Google Ads add-on library provides helper methods to automatically add Permutive targeting to Google Ad Manager ad requests, including automatic AAID identification and contextual cohort support.

Installation

Basic Usage

Contextual

Issues

​
Overview

The Google Ads add-on provides:
  • Automatic targeting - Helper methods for Google Ad Manager
  • AAID identification - Automatic Android Advertising ID capture
  • Contextual cohorts - Automatic content-based targeting (v2.2.0+)
  • Reaction segments - User cohort targeting
  • Simple integration - Minimal code changes required

​
Installation

Add the Google Ads add-on to your build.gradle.kts: 
dependencies {
    implementation("com.permutive.android:core:1.10.0")
    implementation("com.permutive.android:google-ads:2.2.0")  // Add this
}
See Installation Guide for details.

​
Basic Usage

​
Adding Permutive Targeting

The add-on provides extension methods for adding Permutive targeting to Google Ad Manager requests: 
import com.google.android.gms.ads.admanager.AdManagerAdRequest
import com.permutive.android.ads.addPermutiveTargeting
import com.permutive.android.ads.buildWithPermutiveTargeting

class MainActivity : AppCompatActivity() {

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

    private fun loadAd() {
        // Option 1: Add targeting and build separately
        val adRequest1 = AdManagerAdRequest.Builder()
            .addPermutiveTargeting(permutive)
            .build()

        // Option 2: Add targeting and build in one call
        val adRequest2 = AdManagerAdRequest.Builder()
            .buildWithPermutiveTargeting(permutive)

        // Load ad with targeting
        adView.loadAd(adRequest1)
    }
}

​
What Gets Added to Ad Requests

When you call addPermutiveTargeting(), the following targeting parameters are automatically added to your ad request:

​
1. Reaction Segments (User Cohorts)

User cohorts the user belongs to: 
Custom Targeting:
  permutive: ["segment_id_1", "segment_id_2", "segment_id_3"]
These are retrieved from permutive.currentCohorts().

​
2. Contextual Cohorts (v2.2.0+)

Content-based cohorts from the current page (when using PageTracker with URLs): 
Custom Targeting:
  permutive: ["segment_id_1", "segment_id_2", "contextual_segment_1", "contextual_segment_2"]
These are automatically included when:
  • You’re using PageTracker with URLs
  • Contextual data feature is enabled
  • Content has been analyzed
See Contextual Data for details.

​
Complete Integration Example

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import com.google.android.gms.ads.AdSize
import com.google.android.gms.ads.admanager.AdManagerAdView
import com.google.android.gms.ads.admanager.AdManagerAdRequest
import com.permutive.android.ads.buildWithPermutiveTargeting

class ArticleActivity : AppCompatActivity() {

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

    private lateinit var adView: AdManagerAdView

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

        // Track page (enables contextual cohorts)
        val pageTracker = permutive.trackPage(
            title = "Article Title",
            url = Uri.parse("https://example.com/article")  // URL enables contextual
        )

        // Set up ad view
        adView = findViewById(R.id.adView)
        adView.adUnitId = "/your/ad/unit/id"
        adView.setAdSizes(AdSize.BANNER)

        // Load ad with Permutive targeting
        loadAdWithPermutiveTargeting()
    }

    private fun loadAdWithPermutiveTargeting() {
        val adRequest = AdManagerAdRequest.Builder()
            .buildWithPermutiveTargeting(permutive)

        adView.loadAd(adRequest)
    }
}

​
AAID Integration

The Google Ads add-on automatically provides AAID (Android Advertising ID) functionality. See the AAID Provider Guide for complete documentation on:
  • Setting up AAID identification
  • Required permissions for Android API 31+
  • Privacy considerations
  • Troubleshooting

​
Contextual Cohorts

​
Enabling Contextual Cohorts

Contextual cohorts are automatically included (v2.2.0+) when:
  1. Feature enabled - Contact your Customer Success Manager
  2. URLs provided - Use PageTracker with full URLs
  3. Content analyzed - Permutive has analyzed the content

​
Example with Contextual Cohorts

class ArticleActivity : AppCompatActivity() {
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        // Track page with URL (enables contextual cohorts)
        val pageTracker = permutive.trackPage(
            title = article.title,
            url = Uri.parse(article.url),  // Full URL required
            eventProperties = EventProperties.from(
                "article_id" to article.id,
                "category" to article.category
            )
        )
        
        // Load ad - contextual cohorts automatically included
        val adRequest = AdManagerAdRequest.Builder()
            .buildWithPermutiveTargeting(permutive)
        
        adView.loadAd(adRequest)
    }
}
The ad request will include both:
  • User cohorts (behavioral segments)
  • Contextual cohorts (content-based segments)
See Contextual Data Guide for details.

​
Use Cases

​
News/Content App

class ArticleActivity : AppCompatActivity() {
    
    private fun displayArticleWithAds() {
        // Track article page
        val pageTracker = permutive.trackPage(
            title = article.title,
            url = Uri.parse(article.url),
            eventProperties = EventProperties.from(
                "category" to article.category,
                "author" to article.author
            )
        )
        
        // Load multiple ad units with Permutive targeting
        loadBannerAd()
        loadNativeAd()
        loadInterstitialAd()
    }
    
    private fun loadBannerAd() {
        val request = AdManagerAdRequest.Builder()
            .buildWithPermutiveTargeting(permutive)
        bannerAdView.loadAd(request)
    }
    
    private fun loadNativeAd() {
        val request = AdManagerAdRequest.Builder()
            .buildWithPermutiveTargeting(permutive)
        nativeAdLoader.loadAd(request)
    }
    
    private fun loadInterstitialAd() {
        val request = AdManagerAdRequest.Builder()
            .buildWithPermutiveTargeting(permutive)
        
        AdManagerInterstitialAd.load(
            this,
            "/your/interstitial/ad/unit",
            request,
            interstitialAdLoadCallback
        )
    }
}

​
E-Commerce App

class ProductActivity : AppCompatActivity() {
    
    private fun displayProductWithAds() {
        // Track product page
        val pageTracker = permutive.trackPage(
            title = product.name,
            url = Uri.parse("app://product/${product.id}"),
            eventProperties = EventProperties.from(
                "product_id" to product.id,
                "category" to product.category,
                "price" to product.price
            )
        )
        
        // Load ads with user + contextual targeting
        val adRequest = AdManagerAdRequest.Builder()
            .buildWithPermutiveTargeting(permutive)
        
        adView.loadAd(adRequest)
    }
}

​
Ad Loading Best Practices

​
Load Ads After Page Tracking

For contextual cohorts, load ads after calling trackPage(): 
// ✅ CORRECT - Track page first
val pageTracker = permutive.trackPage(...)

// Small delay to allow contextual data retrieval
Handler(Looper.getMainLooper()).postDelayed({
    val adRequest = AdManagerAdRequest.Builder()
        .buildWithPermutiveTargeting(permutive)
    adView.loadAd(adRequest)
}, 100)  // 100ms delay

​
Multiple Ad Units

Reuse the same ad request for multiple ad units: 
// Build once
val adRequest = AdManagerAdRequest.Builder()
    .buildWithPermutiveTargeting(permutive)

// Use for multiple ads
bannerAdView.loadAd(adRequest)
nativeAdView.loadAd(adRequest)

​
Troubleshooting

Problem: Permutive targeting not appearing in ad requests.Causes:
  1. Not calling addPermutiveTargeting() or buildWithPermutiveTargeting()
  2. Permutive not initialized
  3. No cohorts available yet
Solutions:
  1. Verify you’re using the correct methods
  2. Ensure Permutive is initialized before loading ads
  3. Check permutive.currentCohorts() returns data
  4. Enable debug logging: permutive.setDeveloperMode(true)
Problem: Only user cohorts included, not contextual.Causes:
  1. Contextual feature not enabled
  2. Not providing URLs in trackPage()
  3. Using older add-on version (<2.2.0)
  4. Content not yet analyzed
Solutions:
  1. Contact Customer Success Manager to enable feature
  2. Always provide full URLs to trackPage()
  3. Update to google-ads:2.2.0 or later
  4. Verify URLs are publicly accessible
See Contextual Data Troubleshooting.
Problem: AAID not being set as identity.Cause: AAID provider not configured.Solution: See AAID Provider Guide for setup.
Problem: Ads not displaying.This is not a Permutive SDK issue. Troubleshoot standard Google Ad Manager:
  1. Verify ad unit ID is correct
  2. Check ad inventory availability
  3. Verify Google Mobile Ads SDK setup
  4. Review Google Ad Manager console
See Common Errors for more troubleshooting.

​
Best Practices

  • Call addPermutiveTargeting() on all ad requests
  • Track pages with full URLs for contextual cohorts
  • Load ads after calling trackPage()
  • Use AAID provider for user identification
  • Test targeting in Google Ad Manager console

​
Version History

​
v2.2.0 (Latest)

  • ✅ Automatic contextual cohort support
  • ✅ Requires core 1.10.0+
  • ✅ Enhanced ad targeting

​
v2.1.0

  • Minimum API 23 required
  • Bug fixes and improvements

​
v2.0.0

  • Updated for Google Mobile Ads SDK 21.0+
  • Breaking changes from Google SDK update
See the Permutive Dashboard for the latest release information.

​
Migration Notes

​
Upgrading to v2.2.0

No code changes required! Contextual cohorts are automatically included if:
  • Feature is enabled by Permutive
  • You’re using PageTracker with URLs
// Same code works with v2.1.0 and v2.2.0
val adRequest = AdManagerAdRequest.Builder()
    .buildWithPermutiveTargeting(permutive)

// v2.2.0 automatically includes contextual cohorts
adView.loadAd(adRequest)

AAID Provider

Automatic AAID identification

Contextual Data

Content-based targeting

Page Tracking

Track pages for contextual cohorts

Cohorts and Activations

Understanding segments

Installation

Add-on installation

Issues

Solve common issues

​
API Reference

For complete API documentation, see the Javadocs.

​
Kotlin Extensions

  • AdManagerAdRequest.Builder.addPermutiveTargeting(permutive: Permutive) - Add targeting
  • AdManagerAdRequest.Builder.buildWithPermutiveTargeting(permutive: Permutive) - Add targeting and build

​
Java Utilities

  • PermutiveAdManagerAdRequestBuilder(permutive: Permutive) - Builder wrapper
  • AdManagerAdRequestUtils.addPermutiveTargeting(builder, permutive) - Static helper
  • AdManagerAdRequestUtils.buildWithPermutiveTargeting(builder, permutive) - Static helper with build

​
Getting Help

If you encounter issues with Google Ad Manager integration:
  1. Check Troubleshooting Guide
  2. Verify Google Ads add-on is installed
  3. Enable debug logging
  4. Contact your Customer Success Manager
For Google Ad Manager issues unrelated to Permutive, consult Google’s documentation.