Google Ad Manager Integration

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.12.1")
    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)
    }
}

import com.google.android.gms.ads.admanager.AdManagerAdRequest;
import com.permutive.android.ads.PermutiveAdManagerAdRequestBuilder;
import com.permutive.android.ads.AdManagerAdRequestUtils;

public class MainActivity extends AppCompatActivity {

    private void loadAd() {
        Permutive permutive = ((MyApplication) getApplication()).getPermutive();

        // Option 1: Use PermutiveAdManagerAdRequestBuilder
        // (Same interface as AdManagerAdRequest.Builder)
        AdManagerAdRequest request1 =
            new PermutiveAdManagerAdRequestBuilder(permutive)
                .build();

        // Option 2: Use static utility methods
        AdManagerAdRequest.Builder builder = new AdManagerAdRequest.Builder();

        // Add custom targeting
        builder = AdManagerAdRequestUtils.addPermutiveTargeting(builder, permutive);
        AdManagerAdRequest request2 = builder.build();

        // Or add and build in one call
        AdManagerAdRequest request3 =
            AdManagerAdRequestUtils.buildWithPermutiveTargeting(builder, permutive);

        // Load ad with targeting
        adView.loadAd(request1);
    }
}

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

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

public class ArticleActivity extends AppCompatActivity {

    private AdManagerAdView adView;

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

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

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

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

        // Load ad with Permutive targeting
        loadAdWithPermutiveTargeting(permutive);
    }

    private void loadAdWithPermutiveTargeting(Permutive permutive) {
        AdManagerAdRequest adRequest =
            new PermutiveAdManagerAdRequestBuilder(permutive)
                .build();

        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:

Feature enabled - Contact your Customer Success Manager
URLs provided - Use PageTracker with full URLs
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

No Targeting Parameters in Ad Request

Problem: Permutive targeting not appearing in ad requests.Causes:

Not calling addPermutiveTargeting() or buildWithPermutiveTargeting()
Permutive not initialized
No cohorts available yet

Solutions:

Verify you’re using the correct methods
Ensure Permutive is initialized before loading ads
Check permutive.currentCohorts() returns data
Enable debug logging: permutive.setDeveloperMode(true)

Contextual Cohorts Not Included

Problem: Only user cohorts included, not contextual.Causes:

Contextual feature not enabled
Not providing URLs in trackPage()
Using older add-on version (<2.2.0)
Content not yet analyzed

Solutions:

Contact Customer Success Manager to enable feature
Always provide full URLs to trackPage()
Update to google-ads:2.2.0 or later
Verify URLs are publicly accessible

See Contextual Data Troubleshooting.

AAID Not Captured

Problem: AAID not being set as identity.Cause: AAID provider not configured.Solution: See AAID Provider Guide for setup.

Ads Not Serving

Problem: Ads not displaying.This is not a Permutive SDK issue. Troubleshoot standard Google Ad Manager:

Verify ad unit ID is correct
Check ad inventory availability
Verify Google Mobile Ads SDK setup
Review Google Ad Manager console

See Common Errors for more troubleshooting.

Best Practices

Do
Don't

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

Load ads before Permutive is initialized
Skip PageTracker for content pages
Omit URLs from trackPage() if you want contextual cohorts
Forget to update to v2.2.0+ for contextual support

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:

Check Troubleshooting Guide
Verify Google Ads add-on is installed
Enable debug logging
Contact your Customer Success Manager

For Google Ad Manager issues unrelated to Permutive, consult Google’s documentation.

Installation

Basic Usage

Contextual

Issues

​Overview

​Installation

​Basic Usage

​Adding Permutive Targeting

​What Gets Added to Ad Requests

​1. Reaction Segments (User Cohorts)

​2. Contextual Cohorts (v2.2.0+)

​Complete Integration Example

​AAID Integration

​Contextual Cohorts

​Enabling Contextual Cohorts

​Example with Contextual Cohorts

​Use Cases

​News/Content App

​E-Commerce App

​Ad Loading Best Practices

​Load Ads After Page Tracking

​Multiple Ad Units

​Troubleshooting

​Best Practices

​Version History

​v2.2.0 (Latest)

​v2.1.0

​v2.0.0

​Migration Notes

​Upgrading to v2.2.0

​Related Documentation

AAID Provider

Contextual Data

Page Tracking

Cohorts and Activations

Installation

Issues

​API Reference

​Kotlin Extensions

​Java Utilities

​Getting Help

Overview

Installation

Basic Usage

Adding Permutive Targeting

What Gets Added to Ad Requests

1. Reaction Segments (User Cohorts)

2. Contextual Cohorts (v2.2.0+)

Complete Integration Example

AAID Integration

Contextual Cohorts

Enabling Contextual Cohorts

Example with Contextual Cohorts

Use Cases

News/Content App

E-Commerce App

Ad Loading Best Practices

Load Ads After Page Tracking

Multiple Ad Units

Troubleshooting

Best Practices

Version History

v2.2.0 (Latest)

v2.1.0

v2.0.0

Migration Notes

Upgrading to v2.2.0

Related Documentation

API Reference

Kotlin Extensions

Java Utilities

Getting Help