Google Ad Manager

Google Ad Manager is a comprehensive ad management platform that helps publishers sell, deliver, and optimize ads across web, app, and video content.

Setup

Troubleshooting

Overview

Google Ad Manager (GAM) is Google’s comprehensive ad serving platform that helps publishers manage their advertising inventory and maximize revenue. Our integration with Google Ad Manager (GAM) primarily enables you to target your advertising campaigns with Permutive cohorts. Additionally, this integration can be used to ingest ad impressions and clicks into Permutive. This integration is both a Source and Destination:

Source: Permutive is able to ingest ad impressions and clicks.
Destination: Permutive is able to activate your cohorts in GAM.

Use cases include:

Send Permutive cohorts to your ad server so that they can be used for decisioning and targeting in real-time.
Track ad impressions and clicks in Permutive, for insights, retargeting or modeling.
(Advanced) Ad Logs: Capture every ad click in Permutive through Ad Logs in GAM 360.
(Advanced) Campaign Optimization: Optimize your GAM campaigns with Permutive’s AI.

Environment Compatibility

Environment	Supported	Notes
Web		—
iOS		Cohort targeting and ad impression events are supported. Advanced event collection (SlotViewable, SlotClicked, etc.) requires Ad Logs
Android		Cohort targeting and ad impression events are supported. Advanced event collection (SlotViewable, SlotClicked, etc.) requires Ad Logs
CTV		Supported via Permutive CTV SDKs
API Direct		For environments where SDK deployment is not possible

Prerequisites

Network Code - You must provide your Network Code, which is displayed in your GAM dashboard.
Permissions - You must grant Permutive permission to create targeting keys and values in your GAM account. This allows Permutive to programmatically create targeting key-values when you configure cohorts for activation into GAM. To do this, assign dfp@permutive.com a custom role with the following permissions:
- View ad units, placements and key-values
- Edit ad units, placements and key-values
- Edit key-values values
- Access to Inventory tab

Show Advanced: Ad Logs

Ad Logs Prerequisites

For more comprehensive ad click tracking, Permutive is able to ingest GAM Data Transfer Files for customers using Google Ad Manager 360.

You must be using Google Ad Manager 360.
You should have a Data Transfer storage bucket setup, as described here.
You must be an Administrator of your GAM network, and able to grant access to your Data Transfer storage bucket.

Show Advanced: Campaign Optimization

Campaign Optimization Prerequisites

To utilize Permutive’s Optimization product with your GAM campaigns, there are additional prerequisites:

Permissions - Additional GAM permissions are required to enable Campaign Optimization. See the GAM API Usage Guide for the complete list of required permissions. Your CSM will work with you to ensure the custom role for dfp@permutive.com includes all necessary permissions.
AI Opt-in - You must opt in to Permutive’s AI product development principles to access AI-based recommendations.
Cohorts - At least 100 cohorts activated to GAM is recommended for consistent AI recommendations.

Setup

Primary Setup Steps
Web
iOS
Android
API Direct

Enable in Permutive Dashboard

You must enable the Google Ad Manager integration in the Permutive dashboard, if this has not already be done. Please ensure you’ve already granted permissions in GAM appropriately (see prerequisites). In the Permutive dashboard, navigate to your workspace’s integrations page. Click Add Integration and select Google Ad Manager. You will be asked to enter your Network Code at this stage.

Check Key-Values in GAM

In your GAM dashboard, head to “Inventory” => Key-Values and search for permutive. You should find that a targeting key has been created for permutive, with the Reportable attribute set to On. If the Reportable attribute is Off, click on permutive and select include values in reporting. Hit Save. If you cannot find the targeting key-value, please reach out to Permutive Support.

Verify Setup

In the Permutive Dashboard, navigate to one of your cohorts. Check that the Google Ad Manager activation sync is visible. You can try toggling this to On. After doing this, in your GAM dashboard you should see a new targeting value created under the permutive targeting key, with the value corresponding your cohort’s ID. This verifies your integration setup is successful.

Show Advanced: Ad Logs

Ad Logs Setup

Enable in Permutive Dashboard

You must first enable the GAM Logs integration in your Permutive Dashboard.

Grant Storage Bucket Access

Grant read access to your Ad Manager storage bucket to the user shown in the integration configuration page in the dashboard. For more information please see the “Manage access to your Ad Manager storage buckets” section of the GAM Data Transfer Files documentation.

Create Targeting Keys in GAM

In your GAM dashboard, under Inventory => Key-Values, create the following keys:

puid
prmtvvid
prmtvsid
prmtvwid

The value type for all keys must be set as dynamic and reporting should be disabled.

Verify Setup

You should see a new event, called GamLogSlotClicked on the Events page in your Permutive Dashboard. Check back in 24 hours — you should see on the Events page that Permutive is ingesting these events from your Ad Logs (check under Recent Events).

In order for the integration to track impressions and clicks from Mobile Apps, you must first configure our GAM integration for Android and/or iOS.

Show Advanced: Optimization Configuration

Campaign Optimization Setup

Please speak to your CSM to enable this feature.

Deploy GAM specific JavaScript

You’ll need to deploy a small piece of additional JavaScript on-site, alongside the standard Permutive tag. This script ensures that we are always able to target users with cohort membership data from their previous pages views or browsing sessions. We recommend deploying this script immediately above the Permutive tag.

In many cases, this step will have been carried out as part of your initial Permutive deployment.

window.googletag = window.googletag || {};
window.googletag.cmd = window.googletag.cmd || [];
window.googletag.cmd.push(function () {
  if (window.googletag.pubads().getTargeting('permutive').length === 0) {
    var kvs = window.localStorage.getItem('_pdfps');
    window.googletag.pubads().setTargeting('permutive', kvs ? JSON.parse(kvs) : []);
  }
});

Integrate Permutive with Google Mobile Ads on iOS

You’ll need to update your iOS apps to include the Permutive iOS SDK to target your GAM ads in-app.Our SDK offers a googleCustomTargeting function to return a dictionary of current targeting data. This is able to be added to the customTargeting of GAMRequest instances to include current Permutive information for ad targeting. The returned dictionary contains Permutive targeting data for the user. If the ad request is for a “page” being tracked through a PageTracker, the googleCustomTargeting function can accept an optional active PageTracker instance parameter, if available, to improve targeting information. If you are already setting customTargeting property on your GAMRequest, you will need to merge the returned dictionary with your existing values.The returned dictionary from calling googleCustomTargeting will contain the following keys and their associated values:

[
"permutive": ["Cohort1", "Cohort2"],
"puid": "permutiveID",
"ptime": timestamp,
"prmtvwid": randomUUID,
"prmtvsid": sessionId, // if available
"prmtvvid": viewID // if available (will be added if using a PageTracker)
]

To use this method, simply call Permutive.shared.googleCustomTargeting. You can optionally pass in a PageTracker instance if you wish to populate the prmtvvid field as shown in the example below.

let banner = GAMBannerView(adSize: kGADAdSizeBanner)

let adRequest = GAMRequest()

adRequest.customTargeting = Permutive.shared.googleCustomTargeting(adTargetable: pageTracker) /* if using pagetracker, otherwise can be nil*/

banner.load(request)

Integrate Permutive with Google Mobile Ads on Android

You’ll need to integrate your Android apps to include the Permutive Android SDK to target your ads in-app.Alongside our Android SDK, you must add our google-ads dependency to your Gradle build:

implementation("com.permutive.android:google-ads:2.2.0")

Our Android SDK then provides an easy way to add Permutive targeting data to your Ad Manager ad requests:

// To add custom targeting:
val adRequest1 = 
    AdManagerAdRequest.Builder()
        .addPermutiveTargeting(permutive)
        .build()

// Or simply without the build call:
val adRequest2 = 
    AdManagerAdRequest.Builder()
        .buildWithPermutiveTargeting(permutive)

Cohort Activation via API Direct

In environments where it is not possible to deploy a Permutive SDK, you can use Permutive’s CCS (Custom Cohort Segmentation) API for event tracking and segmentation instead.Access to this API requires customer-specific authorization. You will need a dedicated API key from Permutive.

How it Works

The CCS API can be used to:

Track events for a specific user (optional)
Retrieve cohort IDs for activation

The events array in the request is optional. If you only need to retrieve cohort memberships without tracking a new event, you can pass an empty array.

Example Request:

curl --request POST \
     --url 'https://api.permutive.app/ccs/v1/segmentation?activations=true&synchronous-validation=false&k=PERMUTIVE_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "alias": {
    "tag": "user_id",
    "id": "12345"
  },
  "events": [
    {
      "name": "Pageview",
      "time": "2025-10-02T09:40:43.179Z",
      "properties": {}
    }
  ]
}
'

The API accepts a user identity passed in the alias object. Permutive then either links this identity to an existing Permutive user ID or creates a new Permutive user ID if the identity hasn’t been seen before.For cross-environment segmentation and targeting, the identity provided should be consistent with identities used in your other environments (web, app).Example Response:

{
  "user_id": "2008c38f-dece-4570-976d-87593ed001c3",
  "cohorts": ["12345", "23456", "34567"],
  "activations": {
    "target_dfp": ["12345"]
  }
}

The API response includes cohort IDs for GAM activation under the target_dfp key within the activations object. These can then be passed to GAM as key-values for targeting.Important Notes:

Replace PERMUTIVE_API_KEY with your actual Permutive API key
The activations=true query parameter is required to receive activation data in the response

Usage

Activate Contextual Cohorts in GAM — target ads based on page content without the Permutive SDK
Optimize your campaigns with Campaign Optimization

Data Types

With your GAM integration setup, you’ll see the following additional event types collected in Permutive:

SlotViewable

Tracks for every ad impression that becomes viewable. Based on Google Publisher Tag’s ImpressionViewableEvent.

advertiser_id

number

The Advertiser ID for this impression, from GAM.

line_item_id

number

The Line Item ID for this impression, from GAM.

campaign_id

number

The Campaign ID for this impression, from GAM.

creative_id

number

The Creative ID for this impression, from GAM.

service_name

string

The service name, from GAM.

slot.ad_unit_path

string

The ad unit path, from GAM.

slot.slot_element_id

string

The slot element ID, from GAM.

SlotClicked

Tracks a subset of your ad clicks.

advertiser_id

number

The Advertiser ID for this impression, from GAM.

line_item_id

number

The Line Item ID for this impression, from GAM.

campaign_id

number

The Campaign ID for this impression, from GAM.

creative_id

number

The Creative ID for this impression, from GAM.

service_name

string

The service name, from GAM.

slot.ad_unit_path

string

The ad unit path, from GAM.

slot.slot_element_id

string

The slot element ID, from GAM.

is_empty

boolean

Indicates whether an empty creative was served.

width

number

The width of the creative served.

height

number

The height of the creative served.

Show Advanced: Ad Logs

Ad Logs Data Types

GamLogSlotClicked

Tracks your ad clicks comprehensively, based on GAM’s Data Transfer Files.

advertiser_id

number

The Advertiser ID for this impression, from GAM.

line_item_id

number

The Line Item ID for this impression, from GAM.

slot.targeting_keys

list[object]

List of targeting keys present on the impression.

slot.targeting_keys.key

string

Represents a GAM targeting key.

slot.targeting_keys.values

list[string]

Represents GAM targeting values.

Troubleshooting

Unable to enable Google Ad Manager integration in Permutive Dashboard

If you see an error when enabling the Google Ad Manager integration, check that you have granted the correct permissions to dfp@permutive.com (see Prerequisites).

The `permutive` targeting key was not created

Double check that you have granted the correct permissions to dfp@permutive.com (see Prerequisites). In rare cases, you may have reached GAMs limit of 200 active targeting keys. In this case, you must remove an old/inactive key to enable Permutive.

Permutive targeting values not appearing in ad requests

If Permutive cohorts are not being passed to GAM, check the following:

Timing Issue: Open your browser console and append ?googfc to your site URL to access the GAM console. Look for the “permutive” targeting key in the Page Request tab. If Permutive values appear after “Calling fillslot”, the targeting is being set too late. To fix this, ensure the Permutive tag loads as early as possible in the page <head>, ideally before googletag.enableServices() is called.
Missing Cached Segments: Deploy the GAM-specific JavaScript snippet (shown in the Web setup tab) to ensure cached cohorts from previous sessions are always available for targeting.
First Pageview Targeting: If first-pageview targeting is critical, consider implementing a timeout that waits for Permutive to load before enabling GAM services.

Mobile app not passing Permutive segments to GAM

For iOS and Android apps, verify the following:

iOS: Confirm you’re calling Permutive.shared.googleCustomTargeting() and passing the result to your GAMRequest.customTargeting property. If using a PageTracker, pass it as a parameter to include the prmtvvid field.
Android: Ensure you’ve added the com.permutive.android:google-ads dependency and are using .addPermutiveTargeting(permutive) or .buildWithPermutiveTargeting(permutive) on your AdManagerAdRequest.Builder.
AAID/IDFA: Use a proxy tool (like mitmproxy) to verify the Permutive SDK is tracking the AAID (Android) or IDFA (iOS) identifier. On Android, this requires explicit implementation as outlined in the developer documentation.
Event Validation: Check that Permutive events are being accepted (HTTP 200 response) and not rejected (4xx response). Enable debug mode on Android with setDeveloperMode(true) to see detailed logs.

Low targetable impression volume

If your targetable impression volume is lower than expected:

Ensure the Permutive tag loads early in the page lifecycle, preferably in the <head> tag rather than through a tag manager.
Implement the GAM-specific JavaScript snippet to read cached cohorts from local storage, ensuring returning visitors are immediately targetable.
Review the timing of when googletag.enableServices() is called relative to Permutive initialization. Consider adding a configurable timeout (e.g., 2 seconds) to wait for Permutive before enabling GAM services.

Changelog

June 2025

Enhanced support for activating Contextual Cohorts via GAM

For detailed changelog information, visit our Changelog.