Setup
Troubleshooting
Looking to target ads in an embedded YouTube player on your website or app? See the Embedded YouTube Player Integration.
Overview
YouTube is the world’s largest video platform. This integration enables targeting of Permutive cohorts on YouTube.com itself, using Google Ads remarketing built on the Google tag (gtag.js) and deployed through Google Tag Manager. This integration is a Destination:- Destination: Permutive cohort memberships are passed to Google Ads via a custom event on the Google tag, where they are used to build rule-based remarketing audiences in the publisher’s own Google Ads account.
- Retarget your website visitors with Permutive cohorts when they watch content on YouTube.com
- Extend audience reach for direct-sold and audience-extension campaigns that you run through your own Google Ads account
- Use the same cohort-based audiences to target Search and Gmail campaigns alongside YouTube
How it worksYouTube ad targeting is based on the viewer’s signed-in Google Account, not on publisher-side identifiers — cookies and key-values set on your own site cannot be matched to a YouTube viewing session directly.Google Ads remarketing solves this by having the Google tag (gtag.js), running on your site, record visits against Google’s own identity signals. Google performs the match to signed-in Google accounts internally — the publisher passes no user IDs or PII. The
cohorts event parameter sent alongside each visit determines which audience segments, defined as rules in Google Ads, that visit qualifies for.Scope & limitations
- Designed for publishers with their own Google Ads account running their own direct-sold or audience-extension campaigns. Audiences live in your Google Ads account and are not available to third-party buyers or in DV360.
- Web environments only.
- Only signed-in Google users are matchable. In consent-regulated regions, remarketing lists populate only for users who have granted consent (Google Consent Mode).
- Audience lists build cumulatively and can take up to around 30 days to reach full scale. Google’s minimum audience-size thresholds apply before a list is eligible to serve.
- Segment membership reflects the user’s cohorts at the time of the visit and persists until the configured membership duration expires.
- All active cohort memberships are shared with Google Ads via the event.
Environment Compatibility
Prerequisites
- Permutive Web SDK: Deployed on your site, with cohorts computing client-side so that the
_psegslocalStorage key is populated. - Google Ads account: Your own Google Ads account, used to create and target remarketing segments.
- Google Tag Manager: Used to deploy the variable and tag described in Setup below, or the ability to deploy the equivalent snippets directly in your page code.
- Google Consent Mode: Configured where consent regulations apply, so that remarketing lists populate correctly for users who have granted consent.
Setup
- Primary Setup Steps
- Web
1
Create a Custom JavaScript variable for Permutive cohorts
In Google Tag Manager, create a new Custom JavaScript variable (for example, named
Permutive Cohorts) that reads the user’s current Permutive cohort memberships from localStorage:Reading localStorage directly is used here, rather than the SDK’s
permutive.segments() method, because GTM Custom JavaScript variables must return their value synchronously, whereas permutive.segments() is asynchronous. Elsewhere in our SDK documentation we recommend permutive.segments() for retrieving cohorts in your own code — this variable is the synchronous equivalent needed specifically for GTM. See Cohorts and Activations for more on the _psegs key.2
Create the Google tag and Permutive event Custom HTML tag
Create a Custom HTML tag in GTM that loads the Google tag (gtag.js) with your Google Ads conversion ID, and fires a custom Replace
permutive event carrying the cohorts variable as an event parameter:AW-XXXXXXXXX with your Google Ads conversion ID. If you have multiple Google Ads accounts, add one gtag('config', ...) line per account — the permutive event only needs to fire once.3
Choose a trigger
Set the tag to fire on a trigger that runs after the Permutive SDK has executed on the page — Window Loaded is a reliable choice.Because Google Ads remarketing lists build cumulatively across visits, an occasional stale read is generally tolerable. Firing the tag after Permutive keeps the cohorts passed on each visit as fresh as possible.
4
Create rule-based segments in Google Ads Audience Manager
In Google Ads Audience Manager, create one rule-based “your data” (website visitor) segment per Permutive cohort you want to target. Each rule should match the
cohorts event parameter containing the relevant cohort ID, with a configured membership duration (90 days is a reasonable starting point).See Google’s documentation on creating website visitor segments for the exact steps in the Google Ads UI.5
Target the segments in your campaigns
Add the segments you’ve created as audience targeting on your YouTube, Search, or Gmail campaigns in Google Ads.
6
Verify the setup
Use GTM Preview mode or Google Tag Assistant to confirm the Custom HTML tag fires on the expected trigger and the
permutive event is sent. You can also inspect the network request made to Google Ads in your browser’s developer tools and confirm the cohorts parameter is present with the expected cohort IDs.Data Types
With this integration configured, Permutive cohort membership is passed to Google Ads via a custom gtag event:permutive (gtag event)
permutive (gtag event)
A custom event fired on the Google tag (gtag.js) whenever the Permutive Custom HTML tag runs, carrying the user’s current cohort memberships to Google Ads.
_psegs (localStorage key)
_psegs (localStorage key)
The Permutive Web SDK localStorage key holding all of a user’s current cohort memberships, as a JSON array of cohort ID strings. This is the source the GTM Custom JavaScript variable reads from. See Cohorts and Activations for more detail on how this key is populated.
Troubleshooting
Segment not populating
Segment not populating
If a rule-based segment in Google Ads Audience Manager isn’t building membership:
- Consent denied under Consent Mode: For users in consent-regulated regions who haven’t granted consent, visits aren’t recorded against remarketing lists.
- Tag not firing: Use GTM Preview mode to confirm the Custom HTML tag is firing on the page.
- Segment rule not matching the
cohortsparameter: Array values don’t always surface cleanly in Google Ads segment rule matching. If your rule isn’t matching reliably against the array, a fallback is to have the Custom JavaScript variable return a comma-joined string instead (.join(',')on the array) and match the segment rule against that string. - Initial delay: Newly created segments can take 24–48 hours to begin showing membership.
Lower-than-expected reach
Lower-than-expected reach
If reach on YouTube, Search, or Gmail is lower than expected:
- ~30-day ramp: Remarketing lists build cumulatively over time and can take up to around 30 days to reach full scale.
- Minimum list sizes: Google enforces minimum audience-size thresholds before a list is eligible to serve.
- Signed-in users only: Only visits from users signed into a Google Account can be matched — anonymous YouTube viewers can’t be targeted.
Cohorts empty or stale when the tag fires
Cohorts empty or stale when the tag fires
If the
cohorts parameter is empty, or reflects an earlier visit:- Trigger timing: If the tag fires before the Permutive SDK has finished computing cohorts for the pageview, the
cohortsparameter may be empty or stale. Move the trigger to fire later, for example on Window Loaded. - SDK not deployed: Confirm the Permutive Web SDK is present and running on the page.
- Check localStorage directly: Open your browser’s developer tools and inspect
localStorage._psegsto confirm cohort IDs are present before the tag fires.
Verifying the tag fires correctly
Verifying the tag fires correctly
To confirm the integration is working end-to-end:
- Use GTM Preview mode or Google Tag Assistant to confirm the Custom HTML tag fires on the expected trigger, and check the
Permutive Cohortsvariable’s output in Preview mode. - Inspect the network request made to Google Ads in your browser’s developer tools (Network tab) and confirm the
cohortsparameter is present with the expected cohort IDs.
Changelog
For detailed changelog information, visit our Changelog.