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:
- One that identifies a user within the buyer domain.
- A
doubleclick.net
cookie that identifies a Google user.
(We share a buyer-specific encrypted user 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.
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 butnot equal to that cookie. Google passes the user ID to the buyer (raw
DoubleClick 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="http://cm.g.doubleclick.net/pixel?google_nid=1234&google_cm" />
Here
1234
would be replaced by the buyer identifier supplied byGoogle.
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
redirectincludes 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.(Google收到请求以后,会进行302跳转,302请求中包含gid,请求Header中包含购买方Cookie,该302请求URL由购买方提供,Google会在该URL后追加参数)
For example, the buyer could supply this base URL:
http://ad.network.com/pixel
Google could then redirect to a URL like this:
http://ad.network.com/pixel?google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1
The Google User ID passed through the
google_gid
parameter isan 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_cver
parameter indicates a numeric version numberfor 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
NoContent 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="http://cm.g.doubleclick.net/pixel?google_nid=1234&google_cm&extra1=xx&extra2=yy" />
All parameters that do not start with the
google_
prefix arecopied 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.
http://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.
It is also possible to make
https
rather thanhttp
requests to the cookie matching service. In this case theprotocol of the redirect URL is likewise
https
rather thanhttp
.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:
- ExampleNews.com renders, and calls ads from Google (DFP).
- Because the ad unit is eligible for dynamic allocation, Ad Exchange sends
bid requests to FinestDSP (among other DSPs). - FinestDSP processes the bid request in its bid engine, and sends its bid
response to Ad Exchange - FinestDSP wins the auction, and sends an ad with a match tag (pixel) to Ad
Exchange. - Ad Exchange serves FinestDSP's ad and match tag to Jane, and also sets
Jane's DoubleClick cookie. - The match tag calls Google's Cookie Match Service.
- The Cookie Match Service reads Jane's DoubleClick cookie, and sends a
redirect to FinestDSP withgoogle_user_id
set. - The browser loads FinestDSP's URL.
- FinestDSP generates a cookie, which it stores against Jane's
google_user_id
in its match table. - FinestDSP drops its cookie in Jane's browser and responds to the redirect
with an invisible 1x1 pixel.
Scenario 2: Buyer and DoubleClick cookies
A week after Scenario 1, Jane visits ExampleNews.com again. Now that Jane
has both buyer and DoubleClick cookies on her machine, let's see how matching
works.
- The web page renders, executing the HTML code's call to Google for ads.
- During the ad auction, Ad Exchange sends a bid request to an
RTB buyer, FinestDSP, giving that buyer the option of bidding on the
impression. - The buyer receives the bid request with impression information and the
google_user_id
. - FinestDSP looks up the
google_user_id
in its match table to
find the cookie created a week earlier (in Scenario 1). - Based on the information associated with its cookie, FinestDSP decides to
bid on the impression, and wins the auction. - 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 Ad Exchange 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 Ad Exchange
account representative. Or, if you have access to the Ad Exchange Buyer REST
API, 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 ofthis 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 thelikelihood 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:
- 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:
- You receive your own cookie along with the Google User ID, enabling
you to associate the two in your match table. - You must redirect the request back to Google.
- You receive your own cookie along with the Google User ID, enabling
- If you are the chosen buyer:
- The chosen buyer responds with a redirect.
- Google receives the redirect and stores the match between user and buyer.
- 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 URLwith the Google User ID (the
google_gid
parameter) and a newgoogle_push
parameter. The match tag is structured as follows:<img src="http://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:
http://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 thegoogle_cm
parameter. The <push_data>
valuepassed 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 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.
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 thefollowing 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 DoubleClick 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 Ad Exchange 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 when responding to HTTPS pixel match requests
When responding to a Pixel Match request sent to you over HTTPS, you are
required to redirect to the Cookie Matching Service over HTTPS. Redirections
sent over HTTP will cause the user to receive mixed-content warnings. If you
redirect HTTPS requests to us over HTTP more often than once every 2 minutes,
we will throttle the number of Pixel Match requests we send to your
account.
Please note that there are no requirements concerning which protocol to use
for Pixel Match requests sent over HTTP. It is therefore acceptable to respond
to all requests over HTTPS.
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 thegoogle_nid
parameter), as well as the Cookie Matching Service URL.The protocol may be either
http
or https
. Thefollowing are examples of valid match tag URLs:
http://cm.g.doubleclick.net/pixel?google_nid=my_nid 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 otherURL 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 doubleclick 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 formatuserlistid[,
This URL parameter may be repeated to add the user to multiple lists. |
All other parameters that start with the
google_
prefix areignored by the Cookie Matching service and are not passed through to the
redirect URL. Parameters that do not begin with the
google_
prefixare 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_
arereserved for future API expansion.
The redirect URL is built from several parts:
- The protocol,
http
orhttps
, as determined
by the protocol with which the match tag was called. - The base redirect URL supplied by you to Google (including any hard-coded
URL parameters). - Response
google_
parameters (depending on the requestgoogle_
parameters supplied by you in the match tag). - Extra URL parameters sent in the match tag that do not start with the
google_
prefix.
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 areintegral values. Possible values are:
|
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 multiplegoogle_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:
|
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.
google_hm
parameter serves as a container for data that youpass to Google in the cookie match request. When Google responds with the
302
redirect, the google_hm
parameter may be presentwith 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 therealtime-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:
|
google_hm with an explicit redirect URL | |
google_hm | Base64-encoded user ID. |
google_redir | The encoded URL of where the buyer wants Google to send a302 redirect. This allows Ad Exchange to be placed at thefront in a chained call to partners. |
Example:
http://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:
http://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_cm
http://ad.network.com/pixel?id=
http://ad.network.com/pixel?id=&google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1
http://ad.network.com/pixel?id=&google_error=3
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 withgoogle_
, they are passed on to your server. For example, let'stake the two extra parameters
p1=v1
and p2=v2
.The match tag URL in this case is:
http://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_cm&p1=v1&p2=v2
http://ad.network.com/pixel?id=&p1=v1&p2=v2&google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1
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:http://ad.network.com/pixel?id=&p1=v1&p2=v2
http://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_cm
http://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 notpassed in the redirect to your server.
For instance, if you use the following two match tag URLs with the simple
configured redirect URL:
http://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_cm&google_p1=v1&p2=v2
http://ad.network.com/pixel?id=&p2=v2&google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1
google_p1
parameter is not passed in the redirectto your server.
google_ula
Assuming your configured redirect URL is:http://ad.network.com/pixel?id=
http://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_ula=12345
http://ad.network.com/pixel?id=&google_ula=12345,0
the redirect URL is:
http://ad.network.com/pixel?id=&google_error=3
http://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_ula=12345,7654321
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:http://ad.network.com/pixel?id=&google_ula=12345,2
google_ula
requestparameters. Note that you can specify a timestamp on each independently:
http://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_ula=12345,7654321&google_ula=45678
http://ad.network.com/pixel?id=&google_ula=12345,2&google_ula=45678,0
45678
, but there was apermission 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:
http://ad.network.com/pixel?id=&google_ula=12345&google_cm
http://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.
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 thecookie 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:
http://ad.network.com/pixel?id=
http://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_ula=12345
google_no_sc
, the redirect URL is:http://ad.network.com/pixel?id=&google_error=3
google_cm
request parameter and thecookie is successfully set, then the redirect URL is:
http://ad.network.com/pixel?id=&google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1
If the cookie cannot be set, the redirect URL is identical to the regular error redirect URL:
http://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 asQ29va2llIG51bWJlciAxIQ==
- for the configured redirect URL,
http://cookie-monster.com/pixel?id=
The Cookie Match Request is:
http://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=Q29va2llIG51bWJlciAxIQ%3D%3D
302
redirect is:http://cookie-monster.com/pixel?id=
google_hm
parameter has been set with the encodedvalue
Cookie number 1!
, subsequent bid requests forimpressions 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:http://cookie-monster.com/pixel?id=
http://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=chocolate_chunk!
google_hm
parameter but hasneglected to encode its value, and instead attempted to set the parameter with
the unencoded value
chocolate_chunk!
.The
302
redirect is:http://cookie-monster.com/pixel?id=&google_hm=2
- 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, butchocolate_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 code2
—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.netcookie 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:
http://cookie-monster.com/pixel?id=
http://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=chocolate_chunk!
google_hm
parameter but hasneglected to encode its value, and instead attempted to set the parameter with
the unencoded value
chocolate_chunk!
.The
302
redirect is:http://cookie-monster.com/pixel?id=&google_error=3
- 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 decodegoogle_hm
because the failure of the
overall request is a higher-level error that takes precedence. Thereforegoogle_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 asQ29va2llIG51bWJlciAxIQ==
- for the
google_ula
parameter, the value12345
- for the configured redirect URL,
http://cookie-monster.com/pixel?id=
- for the extra parameter
my_extra_param
, no value - for the extra parameter
my_other_extra_param
, value7
http://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
302
redirect is:http://cookie-monster.com/pixel?
id=&my_extra_parameter=&my_other_extra_param=7
&google_gid=ABCDETC&google_cver=1&google_ula=12345,0
- 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 valueCookie number 1!
, subsequent bid
requests for impressions viewed by the same user contain that value in thehosted_match_data
field:
BidRequest <
...
hosted_match_data: "Cookie number 1!"
>
Cookie matching macros
Without macros
Typically the user supplies Google with a base cookie matching URL to whichcookie matching parameters are appended. For example, this URL is passed to be
stored as rtb-keys:
http://user.buyer.com/cookies?x=0&y=1
http://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 providethe following for rtb-keys:
http://user.buyer.com/cookies?
w=0%%GOOGLE_PUSH_PAIR%%&x=1%%GOOGLE_GID_PAIR
&y=2%%GOOGLE_CVER_PAIR%%&z=3%%GOOGLE_ERROR_PAIR%%
http://user.buyer.com/cookies?
w=0&google_push=456&x=1&google_gid=1&y=2&google_cver=1&z=3
_PAIR
style macro was used, the macroexpansion also included the parameter name. The following URL would produce the
same result:
http://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%%