Cookie Matching

This guide explains how the Cookie Matching Service enables you to make more effective bidding choices.

The Cookie Matching Service enables a buyer to associate two types of cookies:

1. A cookie associated with a web browser within the buyer domain.
2. A doubleclick.net cookie that is associated with a web browser (we share a buyer-specific encrypted ID for buyers to match on).

With an RTB application, the buyer can bid on impressions where the user has a specific Google User ID, and can use information associated with that ID as criteria in a bid for an ad impression. Google can host the match table that correlates the data from the two domains. Having Google host the table may be simpler, with reduced latency and easier upgrades.

To access cookie matching, contact your account representative.

After you're set up with cookie matching, you can start using hosted match tables by responding to cookie matching requests with the google_hm parameter.

Learn more about hosted matching in the View bidding metrics with RTB graphs and Set up pretargeting configurations help center articles.

Background

A browser cookie is typically set by the party that owns the domain to which the cookie belongs. The cookie identifies a user within that domain. The security model of the browser restricts one party from reading the cookie set by another party, even if both parties would otherwise agree to such an exchange.

The buyer typically identifies users with cookies that belong to the domain of a third-party ad network. The buyer can associate the cookies with other user information in a database.

For itself, Google identifies users with cookies that belong to the doubleclick.net domain under which Google serves ads. For buyers, Google identifies users using a buyer-specific Google User ID consisting of an encrypted version of the doubleclick.net cookie, derived from but not equal to that cookie. Google passes the user ID to the buyer (raw cookies are never sent).

When receiving a particular Google User ID for the first time, the buyer has no knowledge about the user associated with the ID other than what the bid request reveals. The buyer can match the Google User ID with a buyer cookie, and subsequently consider user information associated with the buyer cookie in making decisions about users identified by the Google User ID. This can be useful in remarketing campaigns, and in refining targeting or bidding for impressions in real time bidding.

The Cookie Matching Service provides the information that a buyer network needs to maintain an association between the buyer cookie and the Google user ID, in the form of a match table. Additionally, the buyer can forward data to Google for storage and later use in bid requests.

Benefits of hosted match tables

Buyers who choose to have Google host their match tables stand to gain the following benefits:

• Lower infrastructure investment
• Mapping the Google User ID to a useful form does not require a table lookup
• During pretargeting, there is the option to filter on whether or not a cookie match exists, which can reduce unwanted bid requests

How cookie matching works

To build an association in the match table, the buyer must serve a tag provided by Google, called the match tag. The match tag can be served with the buyer's ads, or it can be placed on its web properties outside of ads. It is structured as follows:

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

Here 1234 would be replaced by the buyer identifier supplied by Google.

The buyer should only serve this tag if the buyer does not already have a match for this user (or if that entry is stale).

Upon receiving the request for the tag from the user's browser, Google issues a 302 redirect to the buyer. This 302 redirect includes the Google User ID and a version number in the URL, and the buyer cookie in the request headers. The buyer supplies the base URL, and Google appends URL parameters.

Buyers can ask their Technical Account Manager to set or update cookie matching URLs or they can specify the URL themselves through the Buyer REST API using the Accounts resource.

For example, the buyer could supply this base URL:

https://ad.network.com/pixel

Google could then redirect to a URL like this:

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

The Google User ID passed through the google_gid parameter is an unpadded URL-safe standard base64-encoded string. We recommend storing the exact string returned by the Cookie Matching Service in the match table.

The google_user_id field in the BidRequest protocol buffer corresponds to the Google User ID returned by the Cookie Matching Service.

The google_cver parameter indicates a numeric version number for the Google User ID. Google may infrequently change the cookie obfuscation scheme, at which point the google_cver value will be increased.

The buyer receives this redirect, which includes the buyer cookie in the request headers, and updates the match table with the association between this buyer cookie and the Google User ID. The buyer must then serve a 1x1 invisible image pixel to the user's browser, or return a 204 No Content response.

Entries are added to the match table at the rate at which match tags are served to unique users.

This process is illustrated by the diagram below. Each request or response is represented by an arrow, and the data items that accompany the request or response are listed in parentheses.

You can opt to set extra URL parameters on the request and these are passed to your server in the redirect:

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

All parameters that do not start with the google_ prefix are copied over into the redirect URL. The order in which the parameters are passed to the Cookie Matching service is not important. Similarly, the order in which extra parameters are passed in the redirect URL is not guaranteed.

https://ad.network.com/pixel?google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1&extra1=xx&extra2=yy

You can use these parameters to pass additional information about the impression. Extra parameters should be no longer than one kilobyte.

Example scenarios

How would cookie matching look to a typical web user, and what's happening behind the scenes? Let's take a look at two scenarios.

Scenario 1: Cleared cookies

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, Authorized Buyers sends bid requests to FinestDSP (among other DSPs).
3. FinestDSP processes the bid request in its bid engine, and sends its bid response to Authorized Buyers.
4. FinestDSP wins the auction, and sends an ad with a match tag (pixel) to Authorized Buyers.
5. Authorized Buyers serves FinestDSP's ad and match tag to Jane, and also sets Jane's Ad Manager cookie.
6. The match tag calls Google's Cookie Match Service.
7. The Cookie Match Service reads Jane's Ad Manager cookie, and sends a redirect to FinestDSP with google_user_id set.
8. The browser loads FinestDSP's URL.
9. FinestDSP generates a cookie, which it stores against Jane's google_user_id in its match table.
10. FinestDSP drops its cookie in Jane's browser and responds to the redirect with an invisible 1x1 pixel.

Scenario 2: Buyer and Ad Manager cookies

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

1. The web page renders, executing the HTML code's call to Google for ads.
2. During the ad auction, Authorized Buyers sends a bid request to an RTB buyer, FinestDSP, giving that buyer the option of bidding on the impression.
3. The buyer receives the bid request with impression information and the google_user_id.
4. FinestDSP looks up the google_user_id in its match table to find the cookie created a week earlier (in Scenario 1).
5. Based on the information associated with its cookie, FinestDSP decides to bid on the impression, and wins the auction.
6. Jane might see an ad tailored to her or her interests, again based on information that FinestDSP possesses.

Cookie Matching Service

This section explains how buyers can use the Cookie Matching Service.

Before you can use the Cookie Matching Service, you must have:

• An Authorized Buyers account
• A real-time bidder up and running

Next, you must provide Google with your redirect URL. This is the URL to which the Cookie Matching Service should redirect the request for your match tag. This request comes from the user's browser, as described in How cookie matching works above.

You can provide Google with the redirect URL through your Authorized Buyers account representative. Or, if you have access to the RTB Protocol, you can set the URL using one of the methods for updating an Accounts resource.

Serve cookie match tag

You must have the ability to place the Google-supplied match pixel tag on the user's browser. You may choose to place this pixel along with served ads, or on web properties under your control.

Serve pixels

Your servers must recognize the redirect URL, and serve a 1x1 empty pixel to the user's browser in a timely fashion. While processing incoming requests to the redirect URL, your servers should also parse the URL to extract the Google User ID and error codes, and update the match table.

Handle errors

The Cookie Matching Service communicates errors in the google_error special URL parameter in the redirect. The value of this parameter is numeric and identifies the particular error that occurred. You should still respond with a 1x1 empty pixel if the google_error URL parameter is present. If you receive an error, you may show a match tag for the related buyer cookie again.

Cookie Matching Service alternative

To do cookie matching without using the Cookie Matching Service, embed the google_user_id field in the BidRequest. This way, the google_user_id can be extracted from the BidRequest and not from the redirect URL to which the Cookie Matching Service inserts the google_user_id. By avoiding redirects, you also reduce the likelihood of the cookie match request timing out, as from the user navigating away from the page for example.

Pixel matching

In cookie matching, the buyer that wins the auction for an impression can associate a cookie with a Google User ID. In another component of Google's cookie matching code, called pixel matching, Google algorithmically selects an additional buyer whose cookie can be matched with the Google User ID. Google then places a match tag onto the impression, and includes the chosen buyer's URL in the match tag.

This sets the stage for the following interaction:

1. When the page loads in the user's browser, the match tag generates a pixel request to the buyer.
• If you are the chosen buyer:
1. You receive your own cookie along with the Google User ID, enabling you to associate the two in your match table.
2. You must redirect the request back to Google.
2. The chosen buyer responds with a redirect.
3. Google receives the redirect and stores the match between user and buyer.
4. Google serves the pixel to the browser.

Pixel matching does not operate on the properties of publishers who opt out of the additional match.

How it works

Google places the match tag on the page, which combines a buyer-supplied URL with the Google User ID (the google_gid parameter) and a new google_push parameter. The match tag is structured as follows:

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

The match tag causes the buyer to receive a request for the pixel (see item 1 in the diagram below). Upon receiving the request, the buyer must redirect to a URL structured as follows:

https://cm.g.doubleclick.net/pixel?google_nid=1234&google_push=<push_data>

This URL is similar to the one used in buyer-initiated cookie matching, except that the google_push parameter replaces the google_cm parameter. The <push_data> value passed in the redirect must be identical to the value provided by Google in the match tag. The buyer also has the option of adding parameters such as google_ula or google_hm.

The google_push parameter and the google_cm parameter should never appear in the same request.

The reply that the buyer sends to the browser is depicted by item 2 in the diagram below, and the redirect that the browser then sends to Google is depicted by item 3.

Upon receiving the redirect, Google returns an invisible pixel (item 4 in the diagram). Google then logs that a match has been created for the user. Google also handles any other requested operations, such as storing hosted data or adding the user to a user list. Google waits 14 days, until the user-buyer match has expired, before introducing the match again.

In the diagram below, each request or response is represented by an arrow, and the data items that accompany the request or response are listed in parentheses.

Cookie Match Assist

Open Bidding allows exchanges to use existing features already described in this guide, such as Cookie Matching and Pixel Matching, 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.

Prerequisites

In order to use Cookie Match Assist, exchanges must request for the feature to be enabled by contacting their Technical Account Manager and providing the following information:

• Cookie Match Assist URL: a URL dedicated to Cookie Match Assist, that directs to an endpoint the exchange has configured for CMA. This endpoint is intended to implement a service that selects and redirects a pixel request to one of the exchange's bidders in order to match the user ID with their cookie.
• Quota: the maximum number of Cookie Match Assist requests that the exchange can receive every second. This is intended to prevent CMA requests from overloading the exchange's server with requests.

How it works

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=abcdef&google_cver=1"/>

2. The match tag causes the exchange's Cookie Match Assist URL to receive a pixel request.
3. The exchange's Cookie Match Assist 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.

Note: Depending on the exchange's implementation, an additional redirect from the bidder to the exchange could be used to set the cookie in a match table hosted by the exchange.

Restrictions

This section describes the restrictions that Google has put in place to protect user privacy and ensure a pleasant user experience.

Respects user privacy

The Cookie Matching Service respects user privacy by adhering to the following principles:

• Google does not accept any user information provided by the buyer (such as the cookie, user demographics, etc.)
• Google prohibits multiple buyers from joining their match tables.
• The Cookie Matching Service does not expose Google's Ad Manager cookie.
• The purpose of the match table is to allow buyers to use the information they own about the user in transacting with Google. The use of the Cookie Matching Service for the purpose of data harvesting is strictly prohibited by the Authorized Buyers contract and policies.

Bidders are expected to support the above principles, and to safeguard user privacy in their implementations.

Cap frequency

You, as the buyer, are responsible for frequency capping the Cookie Matching Service so that it is not used for users who already have a fresh entry in the match table. You should not serve the Cookie Matching tag unless the match table does not have an entry for the user in question, or the entry is stale. After 14 days, you may consider the Match entry expired, and refresh it.

Google does not enforce frequency capping at serving time. However, it does periodically monitor that you are respecting the frequency capping policy, and reserves the right to interrupt the free service in case of violation.

Respond to all pixel match requests

If you sign up to use the Pixel Matching service you are expected to respond to all Pixel Match requests. This allows us to monitor various policies of how you are using this service. If your response rate drops below a 90% response rate we will throttle the number of Pixel Match requests we send to your account.

Use HTTPS endpoints

It is required that endpoints used with the Cookie Matching Service, Pixel Matching, and Cookie Match Assist 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 and redirects to bidders must also use HTTPS. If you redirect HTTPS requests to us over HTTP more often than once every 2 minutes, we will throttle the number of match requests we send to your account.

Adhere to maximum request rate

When you sign up for the Cookie Matching Service, Google provides a maximum request rate. Google monitors your transactions to ensure that you adhere to this request rate.

API specifications

Match tag

The match tag must contain the buyer ID (passed through the google_nid parameter), as well as the Cookie Matching Service URL. The following is an example of a valid match tag URL:

https://cm.g.doubleclick.net/pixel?google_nid=my_nid

Google reserves all URL parameters for the Cookie Matching Service that start with the prefix google_ for future API expansion. Any other URL parameters added to the match tag pass into the redirect URL uninterpreted.

The Cookie Matching service supports several operations:

• Perform cookie matching -- the basic cookie matching operation described above.
• Add the user to a user list -- adds the user to a user list, avoiding the need for a separate tag.
• Set cookie if missing -- normally the Cookie Matching Service does not set a doubleclick.net cookie on the user's browser if one is not already present. When this option is set, the Cookie Matching Service sets the doubleclick.net cookie.

These operations are supported through the following URL parameters:

Parameter	Description
google_nid	Network ID. This is a buyer ID. Here, "network" refers to the typical buyer, an ad network. This ID can be retrieved through the Buyer REST API Accounts resource's cookieMatchingNid field.
google_cm	Perform cookie matching. The value the parameter is ignored and may be omitted.
google_sc	Sets the cookie 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 Ad Manager cookie is present.
google_no_sc	Does not set the cookie if one is not present. The value of the parameter is ignored and may be omitted.
google_ula	Adds to the user list. The value is in the format 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.

All other parameters that start with the google_ prefix are ignored by the Cookie Matching service and are not passed through to the redirect URL. Parameters that do not begin with the google_ prefix are added to the redirect URL together with the response google_ parameters.

The order of parameters is not important. See the Examples section for illustrations of valid and invalid URLs.

Redirect URL

All URL parameters starting with the prefix google_ are reserved for future API expansion.

The redirect URL is built from several parts:

• The protocol, specified as https.
• The base redirect URL supplied by you to Google (including any hard-coded URL parameters).
• Response google_ parameters (depending on the request google_ parameters supplied by you in the match tag).
• Extra URL parameters sent in the match tag that do not start with the google_ prefix.

The following google_ response parameters are defined:

Parameter	Description
google_error	Overall request error. No operations have been performed and no other google_ response parameters will be set. Error codes are integral values. Possible values are: 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 Pixel Matching Service request. Your redirect must set google_push to the same value passed to you in the initial pixel request.
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_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.

Hosted match table

You can choose to have Google host your match table. This may improve reporting of table size and match rates, and reduce the amount of infrastructure you need to support.

A Google-hosted match table offers a mechanism whereby data which you pass to Google for storage is later passed back to you in bid requests. Typically, when you have placed a match tag for a user whom you have identified with your own internal cookie ID, you include that cookie ID in the cookie match request that you send to Google. Google hosts the data you sent, and includes it in subsequent bid requests for impressions viewed by the same user. This enables you to:

• Skip the step of storing the mapping between the Google User ID and your cookie space.
• Opt to receive a bid request only when the user is one for whom you have a match table entry.

The google_hm parameter serves as a container for data that you pass to Google in the cookie match request. When Google responds with the 302 redirect, the google_hm parameter may be present with an error code.

When Google needs to pass the data back to you, it does so in the hosted_match_data field of the bid request. See the realtime-bidding-proto file for a description of the hosted_match_data field.

google_hm as a cookie match request parameter
google_hm	Contains data which the buyer wants Google to store in the hosted match table. The value is a URL-safe base64 string (padding optional).
google_hm as a redirect parameter
google_hm	Only appears if the attempt to write data to the 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_hm with an explicit redirect URL
google_hm	Base64-encoded user ID, under 23 bytes. For example: Q29va2llIG51bWJlciAxIQ==
google_redir	The encoded URL of where the buyer wants Google to send a 302 redirect. This allows Authorized Buyers to be placed at the front in a chained call to partners.

Example:

https://cm.g.doubleclick.net/pixel?google_nid=<my_nid> \
    &google_hm=<user_id_base64>&google_redir=<encoded_URL>

Cookie matching macros

You can now optionally configure your URLs with one or more macros in the form of either %%GOOGLE_GID%% or %%GOOGLE_GID_PAIR%%. The %%GOOGLE_GID%% will be substituted for the google_gid value directly, while the %%GOOGLE_GID_PAIR%% will be substituted with a google_gid=value.

The supported macros are:

Macro	Expands to
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>

Examples

Simple request

The simplest form of a Cookie Match request is one with no extra parameters. The match tag URL in this case would be:

• https://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_cm

Assuming your configured redirect URL is:

• https://ad.network.com/pixel?id=

An example of a successful response is:

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

If the user does not have a doubleclick.net cookie, the response is:

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

In the case where the user has a doubleclick.net cookie, but has opted out from behavioral targeting, the error code would be 1.

Extra parameters in match tag

If you use extra parameters in the match tag that do not begin with google_, they are passed on to your server. For example, let's take the two extra parameters p1=v1 and p2=v2.

The match tag URL in this case is:

• https://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_cm&p1=v1&p2=v2

An example of a successful response is:

• https://ad.network.com/pixel?id=&p1=v1&p2=v2&google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1

The extra parameters are not guaranteed to appear at the end, and the order of the parameters is also not guaranteed.

An error response would add the extra parameters in a similar way, while reporting the error as in the first example.

Extra parameters in configured redirect URL

Suppose your configured URL is:

• https://ad.network.com/pixel?id=&p1=v1&p2=v2

And you use the simple version of the match tag URL:

• https://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_cm

An example of a successful response is:

• https://ad.network.com/pixel?id=&p1=v1&p2=v2&google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1

google_ parameters

If you pass an extra parameter in the match tag URL or in your configured redirect URL which begins with google_, the parameter is not passed in the redirect to your server.

For instance, if you use the following two match tag URLs with the simple configured redirect URL:

• https://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_cm&google_p1=v1&p2=v2

An example of a successful response is:

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

Note that the google_p1 parameter is not passed in the redirect to your server.

google_ula

Assuming your configured redirect URL is:

• https://ad.network.com/pixel?id=

And you use the following match tag URL:

• https://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_ula=12345

Upon success the user is redirected to

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

If there is an overall error (e.g., the user has no doubleclick.net cookie), the redirect URL is:

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

You can also specify a timestamp:

• https://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_ula=12345,7654321

The redirect URL upon success would be the same.

The redirect URL in case of error is similar, but the status code would be different. Suppose you don't have permission to add users to user list 12345, the redirect URL would be:

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

You can also specify multiple lists using multiple google_ula request parameters. Note that you can specify a timestamp on each independently:

• https://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_ula=12345,7654321&google_ula=45678

The status of each operation is reported separately in the redirect URL:

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

Here the user has been added to the list 45678, but there was a permission error for list 12345.

You can combine the google_ula and google_cm request parameters to perform cookie matching and add the user to a user list in a single request:

• https://ad.network.com/pixel?id=&google_ula=12345&google_cm

The redirect URL is:

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

google_sc and google_no_sc

google_sc

The google_sc request parameter causes the Cookie Matching service to set the doubleclick.net cookie if the user does not currently have it set.

google_no_sc

The google_no_sc request parameter prevents the Cookie Matching service from setting the doubleclick.net cookie if the user does not currently have it set. The default behavior is to set the cookie.

These parameters do not otherwise modify the result of the request. The Cookie Matching Service may not always succeed in setting the cookie if, for example, the user has disallowed cookies generally or the doubleclick.net cookie in particular.

If the Cookie Matching service needs to set a cookie, it verifies that the user's browser has accepted the cookie by issuing a self-redirect with the Set-Cookie header. If the user's browser does not send the cookie in the self-redirect, it is classified as not accepting the doubleclick.net cookie and the redirect to you contains google_error=3.

Assuming your configured redirect URL is:

• https://ad.network.com/pixel?id=

And you use the following match tag URL:

• https://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_ula=12345

If the user does not have the doubleclick.net cookie, and you used google_no_sc, the redirect URL is:

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

If instead, you specify the google_cm request parameter and the cookie is successfully set, then the redirect URL is:

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

There is no way to tell whether the doubleclick.net cookie has just been set, or the user had one all along.

If the cookie cannot be set, the redirect URL is identical to the regular error redirect URL:

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

Hosted match table

Successful write

Values to use in the example:

• for the google_hm parameter, Cookie number 1! encoded in URL-safe base64 as Q29va2llIG51bWJlciAxIQ==
• for the configured redirect URL, https://cookie-monster.com/pixel?id=

The Cookie Match Request is:

• https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=Q29va2llIG51bWJlciAxIQ%3D%3D

The 302 redirect is:

• https://cookie-monster.com/pixel?id=

Because the google_hm parameter has been set with the encoded value Cookie number 1!, subsequent bid requests for impressions viewed by the same user contain that value in the hosted_match_data field:

BidRequest <
  ...
  hosted_match_data: "Cookie number 1!"
>

Here's what happens:

• Because google_cm was not set in the request, google_gid is not in the response.
• Because the hosted write was successful, google_hm is not in the response.
• Because the write was successful, the hosted data becomes available in subsequent bid requests.

Decode error

For this example, assume that the configured redirect URL is:

• https://cookie-monster.com/pixel?id=

The Cookie Match Request is:

• https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=chocolate_chunk!

Note that the buyer has added the google_hm parameter but has neglected to encode its value, and instead attempted to set the parameter with the unencoded value chocolate_chunk!.

The 302 redirect is:

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

Here's what happens:

• Because google_cm was not set in the request, google_gid is not in the response.
• The Cookie Matching Service tries to decode the value of the google_hm parameter as URL-safe base64, but chocolate_chunk! cannot be successfully decoded as base64, and this causes the hosted write to fail.
• Because the hosted write fails, google_hm appears in the response with error code 2—a decode error.
• Since the write was unsuccessful, no new hosted match data becomes available in bid requests (although old data is still sent).

No-cookie error

For a variety of reasons, not every user has a doubleclick.net cookie at any given time.

For this example, assume that there is no doubleclick.net cookie in the user's browser. We'll also assume that the configured redirect URL is:

• https://cookie-monster.com/pixel?id=

The Cookie Match Request is:

• https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=chocolate_chunk!

Note that the buyer has added the google_hm parameter but has neglected to encode its value, and instead attempted to set the parameter with the unencoded value chocolate_chunk!.

The 302 redirect is:

• https://cookie-monster.com/pixel?id=&google_error=3

Here's what happens:

• The lack of a cookie causes the overall request to fail, so google_error is set in the response.
• Although the buyer set the google_hm with an unencoded value, which would fail when the Cookie Matching Service tried to decode it, there is no attempt to decode google_hm because the failure of the overall request is a higher-level error that takes precedence. Therefore google_hm is not set with a decode error in the response.
• Since the write was unsuccessful, no new hosted match data becomes available in bid requests (although old data is still sent).

Putting it all together

Values to use in the example:

• for the google_hm parameter, Cookie number 1! encoded in base64 as Q29va2llIG51bWJlciAxIQ==
• for the google_ula parameter, the value 12345
• for the configured redirect URL, https://cookie-monster.com/pixel?id=
• for the extra parameter my_extra_param, no value
• for the extra parameter my_other_extra_param, value 7

The Cookie Match Request is:

• https://cm.g.doubleclick.net/pixel? google_nid=cookie-monster&google_cm&google_hm=Q29va2llIG51bWJlciAxIQ%3D%3D &google_ula=12345&my_extra_param=&my_other_extra_param=7

The 302 redirect is:

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

Here's what happens:

• The extra parameters pass through first untouched.
• The google_ula parameter contains the status of the userlist add attempt (0: OK).
• Because the hosted match table write was successful, the hosted match data becomes available in subsequent bid requests.
• Because the google_hm parameter has been set with the encoded value Cookie number 1!, subsequent bid requests for impressions viewed by the same user contain that value in the hosted_match_data field:

BidRequest <
  ...
  hosted_match_data: "Cookie number 1!"
>

Cookie matching macros

Without macros

Typically the buyer supplies Google with a base cookie matching URL to which cookie matching parameters are appended. For example, a URL configured for cookie matching could be as follows:

• https://user.buyer.com/cookies?x=0&y=1

This is appended with parameters when calling it:

• https://user.buyer/cookies? x=0&y=1&google_push=456&google_gid=1&google_cver=1

With macros

If the buyer needs the parameters in a specific order, they could provide the following URL:

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

Google would expand the macro and append the rest of the parameters:

• https://user.buyer.com/cookies? w=0&google_push=456&x=1&google_gid=1&y=2&google_cver=1&z=3

Note that, because the _PAIR style macro was used, the macro expansion also included the parameter name. The following URL would produce the same result:

• https://user.buyer.com/cookies? w=0&google_push=%%GOOGLE_PUSH%%&x=1&google_gid=%%GOOGLE_GID%%&y=2 &google_cver=%%GOOGLE_CVER%%&z=3%%GOOGLE_ERROR_PAIR%%

Cookie Matching Status Codes

The following cookie matching status codes are available:

• 0 COOKIE_MATCHER_OK - Cookie is ok to be matched.
• 1 COOKIE_MATCHER_OPTOUT - User opted out from being matched.
• 2 COOKIE_MATCHER_NO_VALID_OPS - Cookie matching request does not contain any operation other than google_sc.
• 3 COOKIE_MATCHER_NO_COOKIE - No cookie is available. Note that this can be because a cookie cannot be generated or setting a cookie is not allowed.
• 4 COOKIE_MATCHER_CONFLICTING_OPS - Returned if a request has both google_cm and google_push operations specified.
• 5 COOKIE_MATCHER_BAD_PUSH_PARAM - the google_push parameter is present in the request.
• 6 COOKIE_MATCHER_INVALID_NID - Invalid NID supplied in cookie matching pixel.
• 7 COOKIE_MATCHER_INVALID_COOKIE_TYPE - cookie type is other than OPT_OUT, TEST, or INVALID.
• 8 COOKIE_MATCHER_NO_BISCOTTI - Deprecated. No cookie (mobile or desktop).
• 9 COOKIE_MATCHER_SET_TEST_COOKIE - Request does not have a Biscotti cookie so an attempt to set a TEST cookie is made.
• 10 COOKIE_MATCHER_INVALID_REDIRECT_OPS - The query parameter google_redir must be used with a google_hm parameter. In addition, google_redir cannot be used with google_cm. If google_redir is used but google_hm is not OR google_redir is used and google_cm is also used, this error is returned.