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

# Google Ad Manager Integration

> Add Permutive targeting to Google Ad Manager requests

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.

<CardGroup cols={4}>
  <Card title="Installation" href="#installation" icon="download" />

  <Card title="Basic Usage" href="#basic-usage" icon="code" />

  <Card title="Contextual" href="#contextual-cohorts" icon="bullseye" />

  <Card title="Issues" href="#troubleshooting" icon="wrench" />
</CardGroup>

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

```kotlin theme={"dark"}
dependencies {
    implementation("com.permutive.android:core:1.12.0")
    implementation("com.permutive.android:google-ads:2.2.0")  // Add this
}
```

See [Installation Guide](/sdks/mobile/android/getting-started/installation) for details.

***

## Basic Usage

### Adding Permutive Targeting

The add-on provides extension methods for adding Permutive targeting to Google Ad Manager requests:

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

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

***

## 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](/sdks/mobile/android/core-concepts/contextual-data) for details.

***

## Complete Integration Example

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

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

***

## AAID Integration

The Google Ads add-on automatically provides AAID (Android Advertising ID) functionality. See the [AAID Provider Guide](/sdks/mobile/android/integrations/aaid-provider) 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

```kotlin theme={"dark"}
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](/sdks/mobile/android/core-concepts/contextual-data) for details.

***

## Use Cases

### News/Content App

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

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

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

```kotlin theme={"dark"}
// Build once
val adRequest = AdManagerAdRequest.Builder()
    .buildWithPermutiveTargeting(permutive)

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

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="No Targeting Parameters in Ad Request">
    **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)`
  </Accordion>

  <Accordion title="Contextual Cohorts Not Included">
    **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](/sdks/mobile/android/core-concepts/contextual-data#troubleshooting).
  </Accordion>

  <Accordion title="AAID Not Captured">
    **Problem:** AAID not being set as identity.

    **Cause:** AAID provider not configured.

    **Solution:** See [AAID Provider Guide](/sdks/mobile/android/integrations/aaid-provider) for setup.
  </Accordion>

  <Accordion title="Ads Not Serving">
    **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](/sdks/mobile/android/troubleshooting/common-errors) for more troubleshooting.
  </Accordion>
</AccordionGroup>

***

## Best Practices

<Tabs>
  <Tab title="Do">
    * 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
  </Tab>

  <Tab title="Don't">
    * 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
  </Tab>
</Tabs>

***

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

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

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="AAID Provider" icon="fingerprint" href="/sdks/mobile/android/integrations/aaid-provider">
    Automatic AAID identification
  </Card>

  <Card title="Contextual Data" icon="bullseye" href="/sdks/mobile/android/core-concepts/contextual-data">
    Content-based targeting
  </Card>

  <Card title="Page Tracking" icon="file" href="/sdks/mobile/android/features/page-tracking">
    Track pages for contextual cohorts
  </Card>

  <Card title="Cohorts and Activations" icon="users" href="/sdks/mobile/android/core-concepts/cohorts-and-activations">
    Understanding segments
  </Card>

  <Card title="Installation" icon="download" href="/sdks/mobile/android/getting-started/installation">
    Add-on installation
  </Card>

  <Card title="Issues" icon="wrench" href="/sdks/mobile/android/troubleshooting/common-errors">
    Solve common issues
  </Card>
</CardGroup>

***

## API Reference

For complete API documentation, see the [Javadocs](https://sdk-docs.permutive.com/index.html).

### 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](/sdks/mobile/android/troubleshooting/common-errors)
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](https://developers.google.com/ad-manager/mobile-ads-sdk/android).