You can access publisher first-party IDs for web and delete associated ads targeting data.
Access publisher first-party IDs on web
The publisher first-party IDs on the web can be accessed directly from JavaScript set first-party cookies under the publisher’s domain. The ID intended for external usage by our publishers and partners is found within the __gpi
cookie. The other cookie (named __gads
) is not intended for external usage by our publishers or partners, and is not allowed for personalization usages.
The value of the __gpi
cookie has the following form:
UID=<unique_user_ID>:T=<creation_unix_timestamp_in_seconds>:RT=<refresh_unix_timestamp_in_seconds>:S=<google_generated_authenticity_signature>
Example __gpi
value:
UID=00000a1b2c3def45:T=1709171636:RT=1709171636:S=ALNI_Ma_CBr2wmXJhLdNKG9z4FWhjVVIog
The value of the ID (UID) and the timestamp (T) are the only components intended for external usage by our publishers and partners:
- UID is currently a 16-character hexadecimal string, but the length should not be considered stable and may change over time.
- T is a base-10 integer representing the unix timestamp of the creation of the ID.
The other two components are internal implementation details which are subject to change and should not be relied on.
The __gpi
and __gads
cookies both currently have a max-age of 13 months, unless browser limitations wipe the cookie earlier (such as Safari ITP limits on JavaScript set cookies). If the cookie is wiped out, Google will attempt, when permitted, to re-populate it with new values.
In addition to __gpi
and __gads
, the cookie jar may also contain the user opt-out cookie __gpi_opt_out
. If it has a value of 1, the user has disabled the use of personalization for Google Ads on that domain (via Google’s Ad Options control).
Before accessing those cookies, you should ensure that your use of the cookies complies with all privacy, data security, and data protection laws, directives, regulations, and rules in any applicable jurisdiction.
View example JavaScript method to retrieve ID
/**
* Returns the Publisher First Party ID and Timestamp.
* @returns {{UID: string|undefined, T: string|undefined}} An object
* containing the UID and Timestamp strings, if available.
*/
function getPublisherFirstPartyIdAndCreationTimestamp() {
// Get the cookie key+value
const gpiCookie = document.cookie.split('; ').find(cookie => cookie.startsWith('__gpi='));
if (!gpiCookie) {
return {UID: undefined, T: undefined};
}
// Use a regular expression for parsing
const regex_match = gpiCookie.match(/UID=([^:]+):T=([^:]+)/);
if (!regex_match) {
return {UID: undefined, T: undefined};
}
// Return the extracted values
return {
UID: regex_match[1],
T: regex_match[2]
};
}
View example usage
try {
const parsedValues = getPublisherFirstPartyIdAndCreationTimestamp();
console.log(parsedValues);
console.log(parsedValues['UID']); // The value of the ID
console.log(parsedValues['T']); // The creation timestamp
} catch (error) {
console.error(error.message);
}
Delete user data associated with publisher first-party IDs on web
Publishers can request that user data associated with a given __gpi
be deleted from Google's internal ad targeting storage systems.
To request deletion for data associated with the UID component of a given __gpi
, the publisher should send an HTTP request of the following form:
https://securepubads.g.doubleclick.net/user_data_deletion?id={id_value}&iu={network_code}&idtype=sco
Note these values for the form:
- id is the value of the ID. It should be a 16-character hexadecimal number and is the UID component retrieved by the access method described above.
- iu is the publisher’s Ad Manager network code.
- idtype identifies the type of the ID. For publisher first-party IDs on the web, the value should be "sco" to indicate site scoped cookie.
Example:
https://securepubads.g.doubleclick.net/user_data_deletion?id=123456789012345&iu=12345&idtype=sco
Expected response
The HTTP response status code "200", indicating that the request was OK, will be returned if the three parameters are present with valid values:
- The "id" value is a 16-character hexadecimal value.
- The "iu" value is a valid Ad Manager network code
- The "idtype" value should be "sco" to indicate this is a publisher first-party ID on web
The HTTP response status code "400" will be returned if the request is not properly formatted.