Cookie Matching

Cookie Matching is a feature that enables you to match your cookie—for example, an ID for a user that browsed your website—with a corresponding bidder-specific Google User ID, and construct user lists that can help you make more effective bidding choices. This guide describes concepts used in Cookie Matching, as well as different Cookie Matching workflows, and any variations they may have for certain use cases.

Concepts

Domain owners typically set the contents of cookies for users that browse their site, which are used to identify users within that domain. Even if two domain owners would otherwise agree to exchanging this data, the security model of internet browsers restricts one from reading a cookie set by another domain.

In the context of digital advertising, Google identifies users with cookies that belong to the doubleclick.net domain, and bidders participating in Real-Time Bidding may have their own domain where they identify some set of users they would like to show ads. Cookie Matching enables the bidder to match their cookies with Google's, such that they can determine whether an impression sent in a bid request is associated with one of users being targeted, they will receive either their own cookie data or a bidder-specific Google User ID that is an encrypted form of the doubleclick.net cookie in the bid request.

The cookie matching service described in this guide facilitates the creation and maintenance of the association between a bidder's cookie and the Google User ID, and also allows one to populate user lists.

Match tables

A match table can be used to map an ID or other data from one domain to another. Bidders can use the Cookie Matching Service to populate their own match tables by mapping their cookie for a given user to the user's Google User ID, or to populate a match table hosted by Google. Match tables are necessary for a bidder's bidder application to access cookie data for the user being shown the impression.

Google-hosted match tables

For easier maintenance, latency improvements, and access to match data for users in certain regions, it is recommended that you allow Google to host your match table. This allows you to specify a web-safe base64-encoded string— hereafter referred to as hosted match data—that will be mapped to the Google User ID for a given user. Once a match has been established, it can be used in the following ways:

  • Real-Time Bidding: In subsequent bid requests for impressions associated with the user, Google will send you the hosted match data you matched with their Google User ID. If your bidding endpoint is configured to use Google's RTB protocol, you will receive this as decoded bytes via the BidRequest.hosted_match_data field. In Google's OpenRTB implementation, BidRequest.user.buyeruid will return this data as a web-safe base64-encoded string.

  • User Lists: User lists can be populated with either Google User IDs or hosted match data.

  • Pretargeting: You can configure your pretargeting such that you only receive bid requests containing hosted match data. This can be used to eliminate less relevant impressions for users outside of your cookie space.

User lists

User lists can be created and managed with the Real-Time Bidding API. Once created, you can populate these lists with the Cookie Matching workflows described below, or via the Bulk Uploader Service.

Getting Started

In order to get started with Cookie Matching, you must contact your Technical Account Manager, who can enable specific workflows and help you configure the following:

  • Cookie Matching Network ID (NID): A string ID uniquely identifying a bidder account for Cookie Matching and other related operations.
  • Cookie Matching URL: The base URL for an endpoint that will accept and handle incoming requests as part of the Cookie Matching workflows. Bidders can embed macros in this URL to control the ordering of parameters passed to it in Cookie Matching workflows.
  • Match Tag: The tag you must place in a user's browser for the bidder-initiated Cookie Matching workflow. This can be served alongside ads, or placed on web properties outside of ads.
  • Cookie Matching Report URL (optional): In the Unidirectional Cookie Matching Workflow, this is an optional URL that can be provided to specify an endpoint that will receive error details in the event that cookie matching fails via an HTTP 302 redirect. By default, responses will only be sent to this URL if there was an error with the cookie matching operation, but bidder's may request that the redirect always be sent.
  • Cookie Match Assist URL: For exchanges implementing the Cookie Match Assist workflow, this is the base URL of the endpoint intended to respond to incoming requests.
  • Cookie Match Assist Quota: For exchanges implementing the Cookie Match Assist workflow, this is the maximum number of requests that their Cookie Matching URL can receive every second. This is intended to prevent CMA requests from overloading the exchange's servers with requests.

In any of the supported Cookie Matching workflows, a bidder's Cookie Matching URL typically has parameters appended in a non-guaranteed ordering. Bidders with integrations requiring consistent ordering of parameters can place macros in their Cookie Matching URL to guarantee their placement.

Supported macros

Bidders can optionally configure their Cookie Matching URL to include one or more macros in the form of either %%GOOGLE_<PARAM_NAME>%% or %%GOOGLE_<PARAM_NAME>_PAIR%%. The supported macros and their expanded values are:

Macro Expanded value
GOOGLE_GID GOOGLE_USER_ID
GOOGLE_GID_PAIR &google_gid=GOOGLE_USER_ID
GOOGLE_CVER COOKIE_VERSION_NUMBER
GOOGLE_CVER_PAIR &cver=COOKIE_VERSION_NUMBER
GOOGLE_ERROR ERROR_ID
GOOGLE_ERROR_PAIR &google_error=ERROR_ID
GOOGLE_PUSH PIXEL_MATCH_DATA
GOOGLE_PUSH_PAIR &google_push=PIXEL_MATCH_DATA
GOOGLE_ALL_PARAMS google_gid=GOOGLE_USER_ID&cver=COOKIE_VERSION_NUMBER&google_error=ERROR_ID

Macro example

A bidder has a cookie matching integration with an endpoint hosted at https://user.bidder.com.cookies, and their implementation requires preset bidder-defined parameters in addition to Pixel Matching parameters in the following order: google_push, google_gid, google_cver, and google_error. The bidder can accomplish this by setting their Cookie Matching URL to:

https://user.bidder.com/cookies?w=0%%GOOGLE_PUSH_PAIR%%&x=1%%GOOGLE_GID_PAIR%%&y=2%%GOOGLE_CVER_PAIR%%&z=3%%GOOGLE_ERROR_PAIR%%

When Google later sends a match request to this bidder, it will be expanded to something like the following:

https://user.bidder.com/cookies?w=0&google_push=PUSH_DATA&x=1&google_gid=GOOGLE_GID&y=2&google_cver=1&z=3

Google's Cookie Matching Service currently supports three workflows for different use cases that are described below.

Bidirectional Cookie Matching refers to a bidder-initiated workflow, where they place a match tag in the user's browser that directs it to Google. This workflow allows both Google and the bidder to populate match tables. Below is a simple example of this workflow.

Step 1: Place the match tag

In order to initiate this flow, the bidder must place their match tag such that it renders in the user's browser. A simple match tag that only returns the Google User ID to the bidder may be structured as follows:

<img src="https://cm.g.doubleclick.net/pixel?google_nid=BIDDER_ACCOUNT_NID&google_cm" />

There are additional parameters you can include in the match tag to fulfill different use cases. To learn more about these parameters, see Match Tag URL Parameters.

Step 2: Google responds with redirect including match data

The match tag will cause Google's Cookie Matching Service to receive a request from the user's browser, which will issue an HTTP 302 redirect to the bidder's Cookie Matching URL. The redirect will include query parameters specifying the Google User ID and its version number in the URL, and the bidder will also receive their cookie included in the request headers. In practice, for a cookie matching URL specified as https://ad.network.com/pixel, the redirect URL for the simple match tag as seen above could look like the following:

https://ad.network.com/pixel?google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1

The Google User ID passed through the google_gid parameter is an unpadded web-safe base64-encoded string. For bidders choosing to host a match table, it is recommended that they store the exact string returned by the Cookie Matching Service. In subsequent bid requests, this will correspond to values specified via BidRequest.google_user_id in Google's RTB protocol, or BidRequest.user.id in Google's OpenRTB implementation.

The version specified in google_cver indicates the numeric version number for the Google User ID. The Google User ID for a given user will infrequently change, after which this will be incremented.

If Google encounters an error while processing your match request, a google_error parameter will instead be specified.

Step 3: Bidder processes redirect and responds with pixel

The bidder receives a redirect to their cookie matching URL including parameters they specified in the first step, and those Google provided in the second step. In addition, they will also receive their cookie in the HTTP headers. If the operation was successful, a bidder hosting their own match table could match their cookie to the Google User ID included in the response. It is recommended that bidders store the exact string returned by the Cookie Matching Service.

If the operation was unsuccessful, the bidder will receive a google_error parameter in the redirect. This is a numeric value corresponding to different error states that identify the particular error that occurred. You can learn more about the possible error values here. If you receive an error, you may attempt to match for that user again by placing a new match tag.

The bidder must always respond by serving a 1x1 invisible pixel image, or alternatively return an HTTP 204 No Content response.

This workflow is illustrated by the diagram below, where requests and responses are represented by an arrow, and the data items that accompany them are listed in parentheses.

Match Tag URL Parameters

Parameter Description
google_nid Network ID (NID) for the bidder account. This ID can be retrieved through the Buyer REST API Accounts resource's cookieMatchingNid field.
google_cm Indicates to Google's Cookie Matching Service that it should perform cookie matching. The value of the parameter is ignored and may be omitted.
google_sc This parameter is deprecated. Sets Google's cookie for the user if one is not present. The value of the parameter is ignored and may be omitted. Omitting the parameter results in an error if no cookie exists.
google_no_sc This parameter is deprecated. This indicates to Google's Cookie Matching Service that it should not set a cookie for the user if one is not present. The value of the parameter is ignored and may be omitted.
google_hm

Contains data that the bidder wants to store in a Google-hosted match table.
google_redir A URL-encoded string that a bidder can specify if they want to direct Google to send the HTTP 302 redirect to the encoded URL for this match tag. This allows Google to be placed at the front in a chained call to partners. This will result in an error if specified without google_hm, or with google_cm.
google_ula A string used to add the user to an existing user list. The value's expected format is userlistid[,timestamp]:
  • userlistid: a single numerical user list ID.
  • timestamp: an optional timestamp in POSIX format, indicates when the user has been added to the user list.

This URL parameter may be repeated to add the user to multiple lists.

In addition to the above parameters, bidders may specify their own, which will be appended as parameters to the redirect URL. Note that bidder-defined parameters named with the google_ prefix will be ignored because those are reserved by Google for future development, and preservation of the parameters' ordering is not guaranteed. A match tag including bidder-defined parameters may look like:

<img src="https://cm.g.doubleclick.net/pixel?google_nid=BIDDER_ACCOUNT_NID&google_cm&extra1=xx&extra2=yy" />

Redirect URL Parameters

The redirect URL is built from the base Cookie Matching URL configured for a bidder's account, including google_ and bidder-defined parameters depending on those specified in the match tag. The following google_ response parameters are defined:

Parameter Description
google_gid Google User ID. Set if google_cm is specified in the request and the request was successful.
google_cver Cookie version. Set if google_cm is specified in the request and the request was successful.
google_error

An integer value indicating the overall request error. When received, it indicates that no operations have been performed, and no other google_ response parameters will be set. The supported error values include the following:

  • 1: User has a Google cookie, but has opted out of any tracking using this cookie.
  • 2: No valid operations specified. e.g., a no-op request was received.
  • 3: User does not have a Google cookie. Google will not set the cookie via the Cookie Matching Service.
  • 4: Conflicting operations specified. You are not allowed to specify both the google_push and google_cm flags on the same request since they have conflicting purposes.
  • 5: An invalid google_push parameter was passed in a redirect to a Google server as part of a bidirectional Pixel Matching request. Your redirect must set google_push to the same value passed to you in the initial pixel request.
  • 6: An invalid NID was supplied in the match tag.
  • 7: An invalid cookie was detected.
  • 8: Deprecated. No cookie found.
  • 9: No cookie found, an attempt to set a test cookie is made.
  • 10: The google_redir parameter was used without google_hm being specified, or was used in addition to google_cm.
  • 15: The request comes from a region where Google requires the match table to be hosted by Google. As a result, this response does not contain a Google User ID. This is currently enabled for only a small percentage of traffic, but is planned to be fully enabled in June 2020.
google_hm

Only appears if the attempt to write to the Google-hosted match table fails. When that happens, its value is one of the following status codes:

  • 1 - Forbidden: The customer is not yet whitelisted to write hosted match table entries.
  • 2 - Decode error: The parameter value could not be decoded.
  • 3 - Payload too long: The parameter value decoded into more than 24 bytes of data.
  • 4 - Internal error: There was an internal error storing the data.
  • 5 - Throttled: This write was not processed due to throttling.
google_ula

Status of user list add operation, repeated if multiple google_ula were specified in the request. The format is:
userlistid,status code

Ex: google_ula=1234567890,0

The google_ula operation can return any of the following status codes:

  • 0 - No error. The user has been added to the user list.
  • 2 - Permission denied. You don't have permission to add users to the given user list.
  • 5 - Bad user list ID. The supplied user list ID is invalid.
  • 6 - Closed attribute ID. The supplied user list ID is closed.
  • 10 - Internal error. The Cookie Matching service has encountered an internal error; you can try re-matching the user again.

The following scenarios describe what cookie matching might look like for a typical user browsing a web page.

Scenario 1: User clears their cookies and browses a site

Jane clears her cache of all cookies. She then visits the homepage of ExampleNews.com.

Here's what happens:

  1. ExampleNews.com renders, and calls ads from Google (Ad Manager).
  2. Because the ad unit is eligible for dynamic allocation, Google sends bid requests to FinestDSP and other bidders via the Real-Time Bidding service.
  3. FinestDSP's bidder application receives and processes the bid request, and sends its bid response.
  4. Google receives bid responses from bidders, including FinestDSP's response that specifies an ad with a match tag (pixel).
  5. FinestDSP wins the auction. Google serves FinestDSP's ad and match tag to Jane.
  6. The match tag calls Google's Cookie Match Service, specifying the google_nid and google_cm parameters.
  7. The Cookie Match Service reads Jane's Google cookie, and sends Jane's browser a redirect to FinestDSP's Cookie Matching URL with the google_user_id and google_cver parameters set.
  8. Jane's browser loads the redirect to FinestDSP's Cookie Match URL.
  9. FinestDSP's cookie matching endpoint processes the redirect request, which includes URL parameters set by Google, and their cookie for Jane in the HTTP headers. FinestDSP can now store the mapping of their cookie to the google_user_id in their match table.
  10. FinestDSP responds to the redirect with an invisible 1x1 pixel.
Scenario 2: User with existing mapping

A week after Scenario 1, Jane visits ExampleNews.com again. Now that Jane has both bidder and Ad Manager cookies on her machine, let's see how matching works.

  1. The web page renders, causing Google (Ad Manager) to request ads that will be rendered on the page.
  2. During the ad auction, Google sends a bid request to applicable bidders, including FinestDSP.
  3. FinestDSP receives the bid request, including signals such as the google_user_id.
  4. FinestDSP looks up the google_user_id in its match table, and finds the cookie associated with Jane that was created a week earlier (in Scenario 1).
  5. Based on information associated with the cookie, FinestDSP's bidding logic places a bid on the impression, and wins the auction.
  6. Jane might see an ad tailored to her interests, based on information that FinestDSP possesses.

Unidirectional Cookie Matching is similar to the Bidirectional workflow, except that it is altered such that only Google hosts and populates a match table. This can be used in instances where the bidder is not permitted to host Google User IDs in their own match table. In order to use this flow, bidders must allow Google to host the match table, can no longer specify google_cm in requests to Google's Cookie Matching Service, and will consequently not receive google_gid to populate their own match table. Once Google has established a match for a user, bidders can add them to user lists using their own cookie data. Similarly, bid requests for these users will exclude the Google User ID, but include hosted match data. A simple example of the revised workflow is summarized in the steps below.

In order to initiate this flow, a bidder must place a match tag such that it renders in the user's browser. Unlike the workflow for users outside of California, the match tag must direct the user's browser to your Cookie Matching URL. For example, with a Cookie Matching URL configured as https://ad.network.com/pixel, it would look like:

<img src="https://ad.network.com/pixel" />

When loading in the user's browser, it will request a pixel from the bidder's Cookie Matching URL. This request will contain their cookie in the HTTP header, which should be extracted for the next step.

The bidder's cookie matching endpoint must redirect to Google's Cookie Matching service, including the google_hm parameter populated with their web-safe base64-encoded cookie data. The redirect URL might look like the following:

https://cm.g.doubleclick.net/pixel?google_nid=BIDDER_ACCOUNT_NID&google_hm=HOSTED_MATCH_DATA

Google will receive a redirect containing the parameters you specified, in addition to Google's cookie in the HTTP headers.

Step 4: Google serves pixel on success or error redirect if report url specified

If the cookie matching operation is successful—or if no Cookie Matching Report URL has been specified for the bidder's account—Google will serve a 1x1 transparent pixel by default, and the workflow will end here. Impressions for this user in subsequent bid requests will include the bidder's hosted match data in BidRequest.hosted_match_data for the Google Protocol, or BidRequest.user.buyeruid for Google's OpenRTB implementation. Bidders can also populate user lists using the hosted match data they specified.

Otherwise, if an error occurred, Google will send a redirect to the bidder's Cookie Matching Report URL with the cause of the error specified in the google_error parameter. If the bidder's Cookie Matching Report URL were https://ad.network.com/report, the redirect URL would look like:

<img src="https://ad.network.com/report?google_error=ERROR_ID" />

The user's browser will redirect to the bidder's Cookie Matching Report URL, including the error reason (if any) specified by Google in the google_error parameter. To learn more about interpreting the error code, see the parameter description.

Step 6: Bidder serves 1x1 transparent pixel

The bidder must respond by serving a 1x1 transparent pixel to the user's browser.

The default workflow for users in California is illustrated by the diagram below, where requests and responses are represented by an arrow, and the data items that accompany them are listed in parentheses.

Parameter Description
google_nid Network ID (NID) for the bidder account. This ID can be retrieved through the Buyer REST API Accounts resource's cookieMatchingNid field.
google_sc This parameter is deprecated. Sets Google's cookie for the user if one is not present. The value of the parameter is ignored and may be omitted. Omitting the parameter results in an error if no cookie exists.
google_no_sc This parameter is deprecated. This indicates to Google's Cookie Matching Service that it should not set a cookie for the user if one is not present. The value of the parameter is ignored and may be omitted.
google_hm

Contains data that the bidder wants to store in a Google-hosted match table.
google_redir An encoded URL that you want Google to send an HTTP 302 redirect. The specified URL will receive redirects with the google_error parameter for both errors and successful operations.
google_ula A string used to add the user to an existing user list. The value's expected format is userlistid[,timestamp]:
  • userlistid: a single numerical user list ID.
  • timestamp: an optional timestamp in POSIX format, indicates when the user has been added to the user list.

This URL parameter may be repeated to add the user to multiple lists.
Parameter Description
google_error

An integer value indicating the overall request error. When received, it indicates that no operations have been performed, and no other google_ response parameters will be set. The supported error values include the following:

  • 1: User has a Google cookie, but has opted out of any tracking using this cookie.
  • 2: No valid operations specified. e.g., a no-op request was received.
  • 3: User does not have a Google cookie. Google will not set the cookie via the Cookie Matching Service.
  • 4: Conflicting operations specified. You are not allowed to specify both the google_push and google_cm flags on the same request since they have conflicting purposes.
  • 5: An invalid google_push parameter was passed in a redirect to a Google server as part of a bidirectional Pixel Matching request. Your redirect must set google_push to the same value passed to you in the initial pixel request.
  • 6: An invalid NID was supplied in the match tag.
  • 7: An invalid cookie was detected.
  • 8: Deprecated. No cookie found.
  • 9: No cookie found, an attempt to set a test cookie is made.
  • 10: The google_redir parameter was used without google_hm being specified, or was used in addition to google_cm.
  • 15: The request comes from a region where Google requires the match table to be hosted by Google. As a result, this response does not contain a Google User ID. This is currently enabled for only a small percentage of traffic, but is planned to be fully enabled in June 2020.

Google-initiated: Bidirectional Pixel Matching

Bidirectional Pixel Matching is a workflow for Google's Cookie Matching Service where Google attempts to match a Google User ID with an algorithmically selected bidder other than the Real-Time Bidding auction winner. When an ad is placed, Google will place a match tag directing the user's browser to load a transparent pixel from the chosen bidder's Cookie Matching URL. This will enable both Google and the bidder to populate a match table with a given user. Below is a simple example of this workflow.

Step 1: Google places a match tag

When a participating publisher's page loads in the user's browser, and an ad slot on that page is filled by Google, a match tag may be placed that requests a pixel from an algorithmically selected bidder. The Pixel Matching tag placed by Google combines the bidder's Cookie Matching URL with additional parameters the bidder can use to populate their match table. For a Cookie Matching URL specified as https://ad.network.com/pixel, it is structured as follows:

<img src="https://ad.network.com/pixel?google_gid=GOOGLE_GID&google_cver=1&google_push=PUSH_DATA" />

Bidders receiving pixel matching requests are required to respond with a redirect to Google's Cookie Matching Service that is structured as follows:

https://cm.g.doubleclick.net/pixel?google_nid=GOOGLE_NID&google_push=PUSH_DATA

Note that the above redirect URL is similar to that of the URL used in the match tag for the Bidder-Initiated Cookie Matching Workflow. In Pixel Matching, the google_cm parameter is replaced by the google_push parameter, and its value must be equal to the value provided by Google in the request. Also similar to the bidder-initiated workflow, additional parameters can be specified to fulfill additional use cases.

Step 3: Google processes redirect and responds with pixel

Google logs that a match has been created for the user, and handles any additional operations requested via query parameters Finally, Google responds with a 1x1 transparent pixel.

Pixel Matching workflow diagram

This workflow is illustrated by the diagram below, where requests and responses are represented by an arrow, and the data items that accompany them are listed in parentheses.

Google match tag request parameters

Parameter Description
google_gid Google User ID. For users outside of California, this will always be specified in Google's match tag.
google_cver The cookie version. This will always be specified in Google's match tag.
google_push Indicates that this request is initiating the Pixel Matching workflow. The value must be returned via the corresponding parameter in the bidder's redirect response.

Bidder Pixel Matching redirect parameters

Parameter Description
google_nid Network ID (NID) for the bidder account. This ID can be retrieved through the Buyer REST API Accounts resource's cookieMatchingNid field.
google_push Indicates that this redirect is completing the Pixel Matching workflow. The value from the corresponding Google match tag must be specified here.
google_hm

Contains data that the bidder wants to store in a Google-hosted match table.
google_ula A string used to add the user to an existing user list. The value's expected format is userlistid[,timestamp]:
  • userlistid: a single numerical user list ID.
  • timestamp: an optional timestamp in POSIX format, indicates when the user has been added to the user list.

This URL parameter may be repeated to add the user to multiple lists.

Google-initiated: Unidirectional Pixel Matching

Unidirectional Pixel Matching differs from the Bidirectional workflow in that Google's match tag does not include a parameter specifying the Google User ID, but will continue to populate a Google-hosted match table. This can be used in instances where the bidder is not permitted to host Google User IDs in their own match table. A simple example of the revised workflow is summarized in the steps below.

Step 1: Google places a match tag

Google places a match tag for an algorithmically selected bidder. It no longer includes the google_gid parameter, and so might look like the following:

<img src="https://ad.network.com/pixel" />

Step 2: User's browser requests pixel from bidder's Cooking Matching URL

The user's browser requests a pixel from the bidder's Cookie Matching URL, including the bidder's cookie in the HTTP headers.

The bidder's cookie matching endpoint must redirect to Google's Cookie Matching service, including the google_hm parameter populated with their web-safe base64-encoded cookie data. The redirect URL might look like the following:

https://cm.g.doubleclick.net/pixel?google_nid=BIDDER_ACCOUNT_NID&google_hm=HOSTED_MATCH_DATA

Google will receive a redirect containing the parameters you specified, in addition to Google's cookie in the HTTP headers. If the operation was successful, impressions for this user in subsequent bid requests will include the bidder's hosted match data in BidRequest.hosted_match_data for the Google Protocol, or BidRequest.user.buyeruid for Google's OpenRTB implementation. Bidders can also populate user lists using the hosted match data they specified.

Finally, Google returns a 1x1 transparent pixel to the user's browser.

Open Bidding allows exchanges to use bidder initiated and Google initiated cookie matching workflows, to match a Google User ID with their cookie. Cookie Match Assist (CMA) is an additional feature for exchanges that enables them to build match tables with their own bidders.

  1. When placing an ad, Google algorithmically selects a participating exchange and places a Cookie Match Assist tag that has the following structure:

    <img src="https://ob.exchange.com/pixel?google_gid=GOOGLE_GID&google_cver=1"/>

  2. Google's CMA match tag causes the exchange's Cookie Matching URL to receive a pixel request.

  3. The exchange's Cookie Matching endpoint receives the request, where its own cookie matching service is responsible for matching the user ID with one of its bidders. In the diagram below, the exchange's cookie matching service responds to the user's browser with a redirect to one of its bidder's endpoints.
  4. The bidder receives the request, along with any parameters specified by the exchange to match the user ID with their cookie.

Restrictions

Cap frequency of requests for fresh matches

Bidders are responsible for limiting the number of calls to the Cookie Matching service for users who have a fresh entry in the Google-hosted match table. An entry in the hosted match table may be considered expired in 14 days, after which it can be refreshed.

Respond to all pixel match requests

Bidders using the Pixel Matching workflow are expected to respond to all incoming Pixel Match requests with a response including the google_push parameter. This allows Google to enforce policies by monitoring usage. If a bidder's response rate drops below 90%, Google will throttle the number of Pixel Match requests sent to their account.

Use HTTPS endpoints

It is required that endpoints used in all Cookie Matching workflows use HTTPS.

When responding to a Pixel Match request sent to you over HTTPS, you are required to redirect to the Cookie Matching Service over HTTPS. Likewise, a Cookie Match Assist endpoint that redirects to bidders must also use HTTPS. If you send requests to Google over HTTP more often than once every 2 minutes, the number of match requests sent to your account will be throttled.

Examples

The examples below illustrate how to use the Cookie Matching service to accomplish specific objectives. Note that unless stated otherwise, it is assumed that the user being acted upon is outside of California.

Populate a bidder-hosted match table

A bidder can use the Cookie Matching workflow to populate their own match table by providing only the google_nid and google_cm parameters in their match tag. This might look like:

<img src="https://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_cm" />

If the bidder's Cookie Matching URL is set to https://ad.network.com/pixel?id=1, and the cookie matching operation is successful, the redirect Google sends in response to the bidder's match tag might look like:

https://ad.network.com/pixel?id=1&google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1

If the cookie matching operation fails because the user does not have a Google cookie, the response would be:

https://ad.network.com/pixel?id=1&google_error=3

The error code is dependent on the underlying cause of the error. To learn more about possible error codes for the Cookie Matching workflow, see the redirect URL parameters.

Add to single user list

The google_ula parameter can be specified in a bidder's match tag to add the user to a user list with the given ID. If the Google or bidder-hosted match table has a fresh entry for the user, the bidder can place a match tag including the google_nid and google_ula parameters to add the user to the specified list without initiating the full Cookie Matching workflow. See the restrictions on invoking the Cookie Matching Service for more deails. The corresponding match tag may look like:

<img src="https://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_ula=12345" />

For a successful response, where the bidder's Cookie Matching URL is https://ad.network.com/pixel, Google's redirect URL would be:

https://ad.network.com/pixel?google_ula=12345,0

If there is an overall error— for example, there is no Google cookie for the user— the redirect URL will include the google_error parameter:

  • https://ad.network.com/pixel?google_error=3

If there is an error specifically concerning adding the user to the list, you will receive google_ula in the redirect. Unlike the corresponding match tag parameter, this replaces the timestamp with a status code to indicate the operation's success. For example, if the request failed because the bidder account didn't have access to the specified user list, the redirect URL would be:

https://ad.network.com/pixel?google_ula=12345,2

Add to multiple user lists

Bidders can specify that a user should be added to multple user lists by including multiple google_ula parameters in the match tag. In practice, this may look like:

<img src="https://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_ula=12345,7654321&google_ula=45678" />

The status of the operation for each user list is similarly reported via distinct google_ula parameters in the redirect:

https://ad.network.com/pixel?google_ula=12345,2&google_ula=45678,0

In the redirect above, we can see that the operation succeeded for the user list with ID 45678, but failed for user list ID 12345 because the bidder didn't have permission to access it.

To perform cookie matching and add the user to a user list in a single request, a bidder's match tag should include google_cm and google_ula:

<img src="https://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_ula=12345&google_cm" />

The redirect URL specified by Google would include google_gid, google_cver, and google_ula. This might look like the following:

https://ad.network.com/pixel?id=&google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1&google_ula=12345,0

Storing a match in a Google-hosted match table

If a bidder wants to store their cookie data in a Google-hosted match table, and does not intend to store match with the Google User ID in their own match table, their match tag must include the google_hm parameter where its value must be a web-safe base64-encoded string. For a user where the bidder's unencoded cookie data is Cookie number 1!, the encoded value would be Q29va2llIG51bWJlciAxIQ==, which would be used in a match tag like the following:

<img src="https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=Q29va2llIG51bWJlciAxIQ%3D%3D" />

For a successful response, where the bidder's Cookie Matching URL is https://cookie-monster.com/pixel, Google's redirect URL would be:

https://cookie-monster.com/pixel

The google_gid parameter is not in the redirect because the match tag did not include google_cm, and google_hm is not included in successful responses. In future bid requests for impressions for this user, the bidder will receive their hosted match data in BidRequest.hosted_match_data for Google's RTB protocol, or BidRequest.user.buyeruid for Google's OpenRTB implementation.

If the bidder instead used a match tag where the value of google_hm was not base64-encoded—such as chocolate_chunk!—the redirect URL might look like the following:

https://cookie-monster.com/pixel?google_hm=2

The above redirect URL includes a google_hm value of 2, suggesting that the operation failed because the value could not be decoded.

Bidder and Google-hosted match tables with user lists

If a bidder hosts their own use list in addition to a Google-hosted user list, and wants a single match tag to match both tables and add the user to a given user list, their match tag must include the google_cm, google_hm, and google_ula parameters. If the bidder's cookie data is Cookie number 1!, the encoded value would be Q29va2llIG51bWJlciAxIQ==, which would produce a match tag like the following:

<img src="https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=Q29va2llIG51bWJlciAxIQ%3D%3D&google_cm&google_ula=12345" />

For a successful response, where the bidder's Cookie Matching URL is https://cookie-monster.com/pixel, Google's redirect URL would look like the following:

https://cookie-monster.com/pixel?google_gid=ABCDETC&google_cver=1&google_ula=12345,0

On receiving the redirect, the bidder can match the Google User ID specified in google_gid with their cookie data in their match table. In addition, they can determine that the Google-hosted match table and user list operations were successful. As a consequence, any Pretargeting the bidder configured to target the specified user list ID will now cause the bidder to receive bid requests for impressions from the user. Likewise, in these bid requests, the bidder will receive their hosted match data in BidRequest.hosted_match_data for Google's RTB protocol, or BidRequest.user.buyeruid for Google's OpenRTB implementation.