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
What is Cookie Matching?
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 lets you 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 through the
BidRequest.hosted_match_datafield. In Google's OpenRTB implementation,BidRequest.user.buyeruidwill 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 through 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 through 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.
Cookie matching macros
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
Cookie Matching Service workflows
Google's Cookie Matching Service currently supports three workflows for different use cases that are described below.
Bidder-initiated: Bidirectional Cookie Matching
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 through 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.
Cookie 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.
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 |
Data the bidder wants to store in a Google-hosted match table.
The value is a web-safe base64-encoded string (padding optional). The raw data must be 40
bytes or less. For example, |
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]:
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_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:
|
google_ula |
Status of user list add operation, repeated if multiple Ex: The
|
Cookie Matching workflow example scenarios
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 their cache of all cookies. They then visit the homepage of ExampleNews.com.
Here's what happens:
- ExampleNews.com renders, and calls ads from Google (Ad Manager).
- Because the ad unit is eligible for dynamic allocation, Google sends bid requests to FinestDSP and other bidders through the Real-Time Bidding service.
- FinestDSP's bidder application receives and processes the bid request, and sends its bid response.
- Google receives bid responses from bidders, including FinestDSP's response that specifies an ad with a match tag (pixel).
- FinestDSP wins the auction. Google serves FinestDSP's ad and match tag to Jane.
- The match tag calls Google's Cookie Match Service, specifying the
google_nidandgoogle_cmparameters. - 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_idandgoogle_cverparameters set. - Jane's browser loads the redirect to FinestDSP's Cookie Match URL.
- 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_idin their match table. - 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 their machine, here's how matching works.
- The web page renders, causing Google (Ad Manager) to request ads that will be rendered on the page.
- During the ad auction, Google sends a bid request to applicable bidders, including FinestDSP.
- FinestDSP receives the bid request, including signals such as the
google_user_id. - FinestDSP looks up the
google_user_idin its match table, and finds the cookie associated with Jane that was created a week earlier (in Scenario 1). - Based on information associated with the cookie, FinestDSP's bidding logic places a bid on the impression, and wins the auction.
- Jane might see an ad tailored to their interests, based on information that FinestDSP possesses.
Bidder-initiated: Unidirectional Cookie Matching
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.
Step 1: Place the match tag directed to bidder's Cookie Matching URL
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 not from a US state with privacy restrictions,
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.
Step 2: Redirect to Google's Cookie Matching service
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
Step 3: User's browser is redirected to Google's Cookie Matching service
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" />
Step 5: User's browser redirects to bidder's Cookie Matching Report URL
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.
Cookie Matching workflow diagram for users from US states with privacy restrictions
The default workflow for users in US states with privacy restrictions 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.
URL Parameters for bidder redirect to Google's Cookie Matching service
| 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]:
This URL parameter may be repeated to add the user to multiple lists. |
URL Parameters for Google redirect to Bidder's Cookie Matching Report URL
| 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-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" />
Step 2: Bidder must respond with redirect to Google's Cookie Matching Service URL
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 through 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 not from a US state with privacy restrictions, 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 through 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]:
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. The match tag includes the
google_push parameter. Here's an example:
<img src="https://ad.network.com/pixel?google_push=PUSH_DATA" />
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.
Step 3: Redirect to Google's Cookie Matching Service
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
Step 4: User's browser is redirected to Google's Cookie Matching service
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.
Cookie Match Assist
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.
How Cookie Match Assist works
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"/>
Google's CMA match tag causes the exchange's Cookie Matching URL to receive a pixel request.
- 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.
- 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 not from a US state with privacy restrictions.
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 through
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.
Step through Cookie Matching workflow and add to user list
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.