Cookie Matching is a feature that lets you 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. > [!IMPORTANT] > **Key Point:** In order to access cookie matching features, you must contact your Account Manager to configure your account. The remainder of this guide assumes this has already been done. ## 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](https://tools.ietf.org/html/rfc4648#section-5)--- 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. Google will specify `BidRequest.user.buyeruid` as a web-safe base64-encoded string. > [!IMPORTANT] > **Key Point:** For users detected to originate from US states with privacy restrictions, the Google User ID won't be specified in the bid request. You will still receive your hosted match data, which can be used to inform your bidding logic. > [!CAUTION] > **Caution:** By default, the value in `buyeruid` is a web-safe base64-encoded string, and should be equivalent to what you send in `google_hm`. If you are receiving unexpected `buyeruid` values in the bid request, it may indicate that you are sending an unencoded `google_hm` value. To disable encoding in the bid request, contact your Technical Account Manager. - **[User Lists](https://developers.google.com/authorized-buyers/rtb/cookie-guide#user-lists)**: User lists can be populated with either Google User IDs or hosted match data. > [!CAUTION] > **Caution:** For users detected to originate from US states with privacy restrictions, using a Google User ID to populate user lists is deprecated, and will eventually be sunset. It is recommended that bidders populate user lists with their hosted match data for these users. - **[Pretargeting](https://developers.google.com/authorized-buyers/rtb/target-guide)**: 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](https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/buyers.userLists). Once created, you can populate these lists with the following Cookie Matching workflows, or through the [Bulk Uploader Service](https://developers.google.com/authorized-buyers/rtb/bulk-uploader). > [!IMPORTANT] > **Key Point:** User lists can be populated with both Google User IDs and hosted match data, and intermixing these is possible. Note that when specifying the latter, they must have already been added to a Google-hosted match table. For users from US states with privacy restrictions, you must use modified workflows that add hosted match data to user lists rather than the Google User ID. ## 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](https://developers.google.com/authorized-buyers/rtb/cookie-guide#cookie-matching-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](https://developers.google.com/authorized-buyers/rtb/cookie-guide#cookie-match-assist), 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](https://developers.google.com/authorized-buyers/rtb/cookie-guide#cookie-match-assist), 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. **Note:** Authorized Buyers can view the Cookie Matching NID and URL configured for their accounts with the [Bidders](https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/bidders) resource. ## Cookie matching macros In any of the supported [Cookie Matching workflows](https://developers.google.com/authorized-buyers/rtb/cookie-guide#cookie-matching-service-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 indicate their placement. #### Supported macros Bidders can optionally configure their Cookie Matching URL to include one or more macros in the form of either `%%GOOGLE_%%` or `%%GOOGLE__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](https://developers.google.com/authorized-buyers/rtb/cookie-guide#google-match-tag-request-parameters) 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 ``` > [!NOTE] > **Note:** The `google_error` parameter is not populated in Google's match tag for the Pixel Matching workflow, and so is excluded. ## Cookie Matching Service workflows Google's Cookie Matching Service supports the following three workflows. ### 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. The following is an 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 match tag that only returns the Google User ID to the bidder may be structured as follows: ``` ``` **Note:** The `BIDDER_ACCOUNT_NID` should be replaced by the NID for the bidder account. This is provided by Technical Account Managers during configuration of cookie matching for a bidder account, and can also be viewed with the Real-time Bidding API's [Bidders resource](https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/bidders). 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](https://developers.google.com/authorized-buyers/rtb/cookie-guide#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 previous match tag 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](https://en.wikipedia.org/wiki/Base64#URL_applications) 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.user.id`. 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 in the [description](https://developers.google.com/authorized-buyers/rtb/cookie-guide#redirect-url-parameters) of the `google_error` URL parameter. 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 following diagram, where requests and responses are represented by an arrow, and the data items that accompany them are listed in parentheses. ![](https://developers.google.com/static/authorized-buyers/rtb/images/cookie_matching.png) #### Match Tag URL Parameters | Parameter | Description | |---|---| | `google_nid` | Network ID (NID) for the bidder account. This ID can be retrieved through the [Bidders](https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/bidders) resource. | | `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 shouldn't 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, `Q29va2llIHRoYXQgaXMgdW5kZXIgNDAgdG90YWwgYnl0ZXMuLi4u`. | | `google_redir` | A URL-encoded string that a bidder can specify if they want to direct Google to send the `HTTP 302` redirect to the encoded URL for this match tag. This allows Google to be placed at the front in a chained call to partners. This will result in an error if specified without `google_hm`, or with `google_cm`. | | `google_ula` | A string used to add the user to an existing user list. The value's expected format is `userlistid[,timestamp]`: - `userlistid`: a single numerical user list ID. - `timestamp`: an optional timestamp in POSIX format, indicates when the user has been added to the user list. This URL parameter may be repeated to add the user to multiple lists. | | `gdpr` | Indicates that the request is subject to GDPR restrictions on data usage. For more detail, see [EU user consent requirements](https://developers.google.com/authorized-buyers/rtb/cookie-guide#eu-user-consent-requirements), or **Impact on cookie match eligibility** in the [Authorized Buyers IAB TCF v2.0 documentation](https://support.google.com/authorizedbuyers/answer/9789378). Example: `gdpr=1` | | `gdpr_consent` | A TC string that represents the end-user consent. For more detail, see [EU user consent requirements](https://developers.google.com/authorized-buyers/rtb/cookie-guide#eu-user-consent-requirements), or **How will the TC string be passed?** in the [Authorized Buyers IAB TCF v2.0 documentation](https://support.google.com/authorizedbuyers/answer/9789378). | | `process_consent` | Indicates that the bidder has obtained end-user consent for the data uses specified in [Google's EU User Consent Policy](https://www.google.com/about/company/user-consent-policy/). If the request is not subject to the EU User Consent Policy, or if there are other consent parameters available on the request (`gdpr_consent`), this parameter is ignored. Example: `process_consent=T` | In addition to the earlier 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: ``` ``` #### Redirect URL Parameters The redirect URL is built from the base Cookie Matching URL configured for a bidder's account, including `google_` and bidder-defined parameters depending on those specified in the match tag. The following `google_` response parameters are defined: | Parameter | Description | |---|---| | `google_gid` | Google User ID. Set if `google_cm` is specified in the request and the request was successful. | | `google_cver` | Cookie version. Set if `google_cm` is specified in the request and the request was successful. | | `google_error` | An integer value indicating the overall request error. When received, it indicates that no operations have been performed, and no other `google_` response parameters will be set. The supported error values include the following: - `1`: User has a Google cookie, but has opted out of any tracking using this cookie. - `2`: No valid operations specified. for example, a no-op request was received. - `3`: User does not have a Google cookie. Google won't set the cookie through the Cookie Matching Service. - `4`: Conflicting operations specified. You are not allowed to specify both the `google_push` and `google_cm` flags on the same request since they have conflicting purposes. - `5`: An invalid `google_push` parameter was passed in a redirect to a Google server as part of a [bidirectional](https://developers.google.com/authorized-buyers/rtb/cookie-guide#google-initiated:-bidirectional-pixel-matching) Pixel Matching request. Your redirect must set `google_push` to the same value passed to you in the initial pixel request. - `6`: An invalid NID was supplied in the match tag. - `7`: An invalid cookie was detected. - `8`: **Deprecated.** No cookie found. - `9`: No cookie found, an attempt to set a test cookie is made. - `10`: The `google_redir` parameter was used without `google_hm` being specified, or was used in addition to `google_cm`. - `15`: The request comes from a region where Google requires the match table to be hosted by Google. As a result, this response does not contain a Google User ID. | | `google_hm` | Only appears if the attempt to write to the Google-hosted match table fails. When that happens, its value is one of the following status codes: - `1` - Forbidden: The customer doesn't have access to write hosted match table entries. - `2` - Decode error: The parameter value couldn't be decoded. - `3` - Payload too long: The parameter value decoded into more than 40 bytes of data. - `4` - Internal error: There was an internal error storing the data. - `5` - Throttled: This write was not processed due to throttling. | | `google_ula` | Status of user list add operation, repeated if multiple `google_ula` were specified in the request. The format is: `userlistid,status code` Ex: `google_ula=1234567890,0` The `google_ula` operation can return any of the following status codes: - `0` - No error. The user has been added to the user list. - `2` - Permission denied. You don't have permission to add users to the given user list. - `5` - Bad user list ID. The supplied user list ID is invalid. - `6` - Closed attribute ID. The supplied user list ID is closed. - `10` - Internal error. The Cookie Matching service has encountered an internal error; you can try re-matching the user again. | #### 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: 1. ExampleNews.com renders, and calls ads from Google (Ad Manager). 2. Because the ad unit is eligible for dynamic allocation, Google sends bid requests to FinestDSP and other bidders through the Real-Time Bidding service. 3. FinestDSP's bidder application receives and processes the bid request, and sends its bid response. 4. Google receives bid responses from bidders, including FinestDSP's response that specifies an ad with a match tag (pixel). 5. FinestDSP wins the auction. Google serves FinestDSP's ad and match tag to Jane. 6. The match tag calls Google's Cookie Match Service, specifying the `google_nid` and `google_cm` parameters. 7. The Cookie Match Service reads Jane's Google cookie, and sends Jane's browser a redirect to FinestDSP's Cookie Matching URL with the `google_gid` and `google_cver` parameters set. 8. Jane's browser loads the redirect to FinestDSP's Cookie Match URL. 9. FinestDSP's cookie matching endpoint processes the redirect request, which includes URL parameters set by Google, and their cookie for Jane in the HTTP headers. FinestDSP can now store the mapping of their cookie to the `google_gid` in their match table. 10. FinestDSP responds to the redirect with an invisible 1x1 pixel. ![](https://developers.google.com/static/authorized-buyers/rtb/images/cookie-matching-schematic.png) ##### 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. 1. The web page renders, causing Google (Ad Manager) to request ads that will be rendered on the page. 2. During the ad auction, Google sends a bid request to applicable bidders, including FinestDSP. 3. FinestDSP receives the bid request, including signals such as the `google_gid`. 4. FinestDSP looks up the `google_gid` in its match table, and finds the cookie associated with Jane that was created a week earlier (in Scenario 1). 5. Based on information associated with the cookie, FinestDSP's bidding logic places a bid on the impression, and wins the auction. 6. Jane might see an ad tailored to 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. An example of the revised workflow is summarized in the following steps. > [!WARNING] > **Note**: This workflow is required for users from US states with privacy restrictions, but bidders may optionally adopt this workflow for other regions as well. #### 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: ``` ``` 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.user.buyeruid`. 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: ``` ``` > [!WARNING] > **Note:** Bidders may request that their account always receive redirects to their Cookie Matching Report URL, even for successful operations. To enable this, they may contact their Technical Account Manager. #### 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](https://developers.google.com/authorized-buyers/rtb/cookie-guide#redirect-url-parameters). > [!NOTE] > **Note**: This step will only occur if the bidder's account is configured to send information about the operation's failure or success to a Cookie Matching Report URL. #### Step 6: Bidder serves 1x1 transparent pixel The bidder must respond by serving a 1x1 transparent pixel to the user's browser. > [!NOTE] > **Note**: This step will only occur if the bidder's account is configured to send information about the operation's failure or success to a Cookie Matching Report URL. #### 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 following diagram, where requests and responses are represented by an arrow, and the data items that accompany them are listed in parentheses. ![](https://developers.google.com/static/authorized-buyers/rtb/images/cookie_matching_ca.png) #### 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 [Bidders](https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/bidders) resource. | | `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 shouldn't 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. > [!NOTE] > Note: The value is a web-safe base64-encoded string (padding optional) that must not exceed 40 bytes. For example, this might look like: `Q29va2llIG51bWJlciAxIQ==`. | | `google_redir` | An encoded URL that you want Google to send an HTTP 302 redirect. The specified URL will receive redirects with the `google_error` parameter for both errors and successful operations. | | `google_ula` | A string used to add the user to an existing user list. The value's expected format is `userlistid[,timestamp]`: - `userlistid`: a single numerical user list ID. - `timestamp`: an optional timestamp in POSIX format, indicates when the user has been added to the user list. This URL parameter may be repeated to add the user to multiple lists. | | `gdpr` | Indicates that the request is subject to GDPR restrictions on data usage. For more detail, see [EU user consent requirements](https://developers.google.com/authorized-buyers/rtb/cookie-guide#eu-user-consent-requirements), or **Impact on cookie match eligibility** in the [Authorized Buyers IAB TCF v2.0 documentation](https://support.google.com/authorizedbuyers/answer/9789378). Example: `gdpr=1` | | `gdpr_consent` | A TC string that represents the end-user consent. For more detail, see [EU user consent requirements](https://developers.google.com/authorized-buyers/rtb/cookie-guide#eu-user-consent-requirements), or **How will the TC string be passed?** in the [Authorized Buyers IAB TCF v2.0 documentation](https://support.google.com/authorizedbuyers/answer/9789378). | | `process_consent` | Indicates that the bidder has obtained end-user consent for the data uses specified in [Google's EU User Consent Policy](https://www.google.com/about/company/user-consent-policy/). If the request is not subject to the EU User Consent Policy, or if there are other consent parameters available on the request (`gdpr_consent`), this parameter is ignored. Example: `process_consent=T` | #### 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_` response parameters will be set. The supported error values include the following: - `1`: User has a Google cookie, but has opted out of any tracking using this cookie. - `2`: No valid operations specified. for example, a no-op request was received. - `3`: User does not have a Google cookie. Google won't set the cookie through the Cookie Matching Service. - `4`: Conflicting operations specified. You are not allowed to specify both the `google_push` and `google_cm` flags on the same request since they have conflicting purposes. - `5`: An invalid `google_push` parameter was passed in a redirect to a Google server as part of a [bidirectional](https://developers.google.com/authorized-buyers/rtb/cookie-guide#google-initiated:-bidirectional-pixel-matching) Pixel Matching request. Your redirect must set `google_push` to the same value passed to you in the initial pixel request. - `6`: An invalid NID was supplied in the match tag. - `7`: An invalid cookie was detected. - `8`: **Deprecated.** No cookie found. - `9`: No cookie found, an attempt to set a test cookie is made. - `10`: The `google_redir` parameter was used without `google_hm` being specified, or was used in addition to `google_cm`. - `15`: The request comes from a region where Google requires the match table to be hosted by Google. As a result, this response does not contain a Google User ID. | ### 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. The following is an 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](https://developers.google.com/authorized-buyers/rtb/cookie-guide#google-match-tag-request-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: ``` ``` #### 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 preceding redirect URL is similar to that of the URL used in the match tag for the [Bidder-Initiated Cookie Matching Workflow](https://developers.google.com/authorized-buyers/rtb/cookie-guide#step-1:-place-the-match-tag). 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](https://developers.google.com/authorized-buyers/rtb/cookie-guide#bidder-pixel-matching-redirect-parameters) can be specified to fulfill additional use cases. > [!WARNING] > **Warning:** the `google_cm` and `google_push` parameters should never appear in the same request to Google's Cookie Matching Service. #### 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 following diagram, where requests and responses are represented by an arrow, and the data items that accompany them are listed in parentheses. ![](https://developers.google.com/static/authorized-buyers/rtb/images/pixel_matching.png) #### 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. | | `gdpr_consent` | A TC string that represents the end-user consent. For more detail, see \[EU user consent requirements\](/authorized-buyers/rtb/cookie-guide#eu-user-consent-requirements), or \*\*How will the TC string be passed?\*\* in the \[Authorized Buyers IAB TCF v2.0 documentation\](//support.google.com/authorizedbuyers/answer/9789378). | #### Bidder Pixel Matching redirect parameters | Parameter | Description | |---|---| | `google_nid` | Network ID (NID) for the bidder account. This ID can be retrieved through the [Bidders](https://developers.google.com/authorized-buyers/apis/realtimebidding/reference/rest/v1/bidders) resource. | | `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. > [!NOTE] > Note: The value is a web-safe base64-encoded string (padding optional) that must not exceed 40 bytes. For example, this might look like: `Q29va2llIG51bWJlciAxIQ==`. | | `google_ula` | A string used to add the user to an existing user list. The value's expected format is `userlistid[,timestamp]`: - `userlistid`: a single numerical user list ID. - `timestamp`: an optional timestamp in POSIX format, indicates when the user has been added to the user list. This URL parameter may be repeated to add the user to multiple lists. | | `gdpr_consent` | A TC string that represents the end-user consent. For more detail, see \[EU user consent requirements\](/authorized-buyers/rtb/cookie-guide#eu-user-consent-requirements), or \*\*How will the TC string be passed?\*\* in the \[Authorized Buyers IAB TCF v2.0 documentation\](//support.google.com/authorizedbuyers/answer/9789378). | ### 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. An example of the revised workflow is summarized in the following steps. > [!WARNING] > **Note**: This workflow is required for users from US states with privacy restrictions, but bidders may optionally adopt this workflow for other regions as well. #### 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: ``` ``` #### 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&google_push=PUSH_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.user.buyeruid`. 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](https://developers.google.com/authorized-buyers/rtb/cookie-guide#bidder-initiated:-bidirectional-cookie-matching) and [Google initiated](https://developers.google.com/authorized-buyers/rtb/cookie-guide#google-initiated:-bidirectional-pixel-matching) 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 > [!WARNING] > **Note:** The Cookie Match Assist feature will be deprecated starting on October 28th, 2025. 1. When placing an ad, Google algorithmically selects a participating exchange and places a Cookie Match Assist tag that has the following structure: ``` ``` > [!CAUTION] > **Caution:** For users from US states with privacy restrictions, Cookie Match Assist won't include the `google_gid` parameter. 2. Google's CMA match tag causes the exchange's Cookie Matching URL to receive a pixel request. > [!NOTE] > **Note:** Unlike the Google-initiated workflows, this excludes the `google_push` parameter. 3. The exchange's Cookie Matching endpoint receives the request, where its own cookie matching service is responsible for matching the user ID with one of its bidders. In the following diagram, 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. ![](https://developers.google.com/static/authorized-buyers/rtb/images/cookie_match_assist_diagram.png) ## 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. > [!WARNING] > **Warning:** 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 service in case of violation. #### 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 is less than 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. #### EU user consent requirements Cookie Matching requests that are subject to [Google's EU User Consent Policy](https://www.google.com/about/company/user-consent-policy/) should indicate end-user consent. Such requests are required to indicate that consent has been gathered using one of the following ways: - TCFv2: This includes `gdpr` and `gdpr_consent` parameters. For details, consult the [Authorized Buyers IAB TCF v2.0 documentation](https://support.google.com/authorizedbuyers/answer/9789378). - `process_consent`: a declaration that the bidder has obtained necessary user consent. ## Examples The following examples 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: ``` ``` 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](https://developers.google.com/authorized-buyers/rtb/cookie-guide#redirect-url-parameters). > [!NOTE] > **Note:** The bidder-defined parameter `id` seen in the match tag is passed along as-is when Google redirects to the bidder's Cookie Matching URL. ### 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](https://developers.google.com/authorized-buyers/rtb/cookie-guide#cap-frequency-of-requests-for-fresh-matches) on invoking the Cookie Matching Service for more deails. The corresponding match tag may look like: ``` ``` 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 ``` > [!IMPORTANT] > **Key Point:** The value of `google_ula` is `12345,0`, indicating that the user should be added to a user list with ID `12345`, and in this case the timestamp is set to `0` to indicate that it is being left unspecified. Alternatively, just the user list ID could have been provided. 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 multiple user lists by including multiple `google_ula` parameters in the match tag. In practice, this may look like: ``` ``` 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 preceding redirect, 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`: ``` ``` 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 ``` ### Store 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: ``` ``` 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.user.buyeruid`. 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 preceding redirect URL includes a `google_hm` value of `2`, suggesting that the operation failed because the value couldn't 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: ``` ``` 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.user.buyeruid`.