Google上的CookieMatching-飞外

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:

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.

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 thedoubleclick.netdomain under which Google serves ads. For buyers, Google identifies users using a buyer-specific Google User ID consisting of an encrypted version of thedoubleclick.netcookie, derived from but not 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 inremarketingcampaigns, 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.

Important:Contact your account representative for access to this service.

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

To build an association in the match table, the buyer must serve a tag provided by Google, called thematch 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" / 

Here1234would 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 a302redirect to the buyer. This302redirect 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.

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 thegoogle_gidparameter is an unpadded URL-safe base64-encoded string. We recommend storing the exact string returned by the Cookie Matching Service in the match table.

Thegoogle_cverparameter indicates a numeric version number for the Google User ID. Google may infrequently change the cookie obfuscation scheme, at which point thegoogle_cvervalue 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 a204No Contentresponse.

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 thegoogle_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.

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 makehttpsrather thanhttprequests to the cookie matching service. In this case the protocol of the redirect URL is likewisehttpsrather thanhttp.

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.

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

Here's what happens:

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.

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

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

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 inHow cookie matching worksabove.

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 anAccounts resource.

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.

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.

The Cookie Matching Service communicates errors in thegoogle_errorspecial 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 thegoogle_errorURL parameter is present. If you receive an error, you may show a match tag for the related buyer cookie again.

To do cookie matching without using the Cookie Matching Service, embed thegoogle_user_idfield in theBidRequest. This way, thegoogle_user_idcan be extracted from theBidRequestand not from the redirect URL to which the Cookie Matching Service inserts thegoogle_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.

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:

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

Google places the match tag on the page, which combines a buyer-supplied URL with the Google User ID (thegoogle_gidparameter) and a newgoogle_pushparameter. 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 buyermustredirect 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 thegoogle_pushparameter replaces thegoogle_cmparameter. 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 asgoogle_ulaorgoogle_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.

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

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

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

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.

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.

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.

The match tag must contain the buyer ID (passed through thegoogle_nidparameter), as well as the Cookie Matching Service URL. The protocol may be eitherhttporhttps. The following are examples of valid match tag URLs:

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

Google reserves all URL parameters for the Cookie Matching Service that start with the prefixgoogle_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:

These operations are supported through the following URL parameters:

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

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

The order of parameters is not important. See theExamplessection for illustrations of valid and invalid URLs.

All URL parameters starting with the prefixgoogle_are reserved for future API expansion.

The redirect URL is built from several parts:

The followinggoogle_response parameters are defined:

Overall request error. No operations have been performed and no othergoogle_response parameters will be set. Error codes are integral values. Possible values are:

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

Ex:google_ula=1234567890,0

Thegoogle_ulaoperation can return any of the following status codes:

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:

Thegoogle_hmparameter serves as a container for data that you pass to Google in the cookie match request. When Google responds with the302redirect, thegoogle_hmparameter may be present with an error code.

When Google needs to pass the data back to you, it does so in thehosted_match_datafield of the bid request. See therealtime-bidding-protofile for a description of thehosted_match_datafield.

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:

http://cm.g.doubleclick.net/pixel?google_nid= my_nid  google_hm= user_id_base64 google_redir= encoded_URL 

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 thegoogle_gidvalue directly, while the %%GOOGLE_GID_PAIR%% will be substituted with agoogle_gid=value.

The supported macros are:

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

Assuming your configured redirect URL is:

An example of a successful response is:

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

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

If you use extra parameters in the match tag that do not begin withgoogle_, they are passed on to your server. For example, let's take the two extra parametersp1=v1andp2=v2.

The match tag URL in this case is:

An example of a successful response is:

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

Suppose your configured URL is:

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

An example of a successful response is:

If you pass an extra parameter in the match tag URL or in your configured redirect URL which begins withgoogle_, 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:

An example of a successful response is:

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

Assuming your configured redirect URL is:

And you use the following match tag URL:

Upon success the user is redirected to

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

You can also specify a timestamp:

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 list12345, the redirect URL would be:

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

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

Here the user has been added to the list45678, but there was a permission error for list12345.

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

The redirect URL is:

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 theSet-Cookieheader. 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 containsgoogle_error=3.

Assuming your configured redirect URL is:

And you use the following match tag URL:

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

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

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

Values to use in the example:

TheCookie Match Requestis:

The302redirect is:

Because thegoogle_hmparameter 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_datafield:

BidRequest  hosted_match_data: "Cookie number 1!"

Here's what happens:

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

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

The302redirect is:

Here's what happens:

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:

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

The302redirect is:

Here's what happens:

Values to use in the example:

TheCookie Match Requestis:

The302redirect is:

Here's what happens:

BidRequest  hosted_match_data: "Cookie number 1!"

Typically the user supplies Google with a base cookie matching URL to which cookie matching parameters are appended. For example, this URL is passed to be stored as rtb-keys:

This is appended with parameters when calling it:

If the buyer needs the parameters in a specific order, they could provide the following for rtb-keys:

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

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

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 3.0 License, and code samples are licensed under theApache 2.0 License. For details, see ourSite Policies. Java is a registered trademark of Oracle and/or its affiliates.

上次更新日期：七月 6, 2016

原文地址：https://developers.google.com/ad-exchange/rtb/cookie-guide