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.
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:
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.
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.
2
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.
3
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.
You must first enable the GAM Logs integration in your Permutive Dashboard.
2
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.
3
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.
4
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.
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.
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:
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)
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.
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.
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:
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
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.
