An opt-out mechanism for the third-party cookie deprecation trial grace period

For sites taking part in either of the third-party cookie deprecation trials, Chrome provides a grace period to temporarily re-enable third-party cookies. During the grace period, sites can access third-party cookies in Chrome, even if they haven't yet deployed trial tokens.

Chrome is also providing a mechanism to allow sites to opt out of the grace period for a percentage of users. The opt-out mechanism will enable sites to run their own staged rollouts to help them transition away from relying on the grace period, in order to test deprecation trial token deployment and move towards long-term solutions.

Why developers need the opt-out mechanism

When a site or service is approved for the first-party or third-party deprecation trials, Chrome provides a trial token and initiates a grace period to allow time for tokens to be deployed. The grace period continues to remain in effect until its expiration—even after tokens are deployed. This can be problematic for testing whether deprecation trial token deployment has been successful.

Developers can set a Chrome flag to disable the grace period to locally test token deployment, but this is not appropriate for testing at scale. To enable sites to production-test token deployment, Chrome is now providing a mechanism to opt out of the grace period for a percentage of users.

Configure grace period opt-out percentages

To take part in the opt-out, provide a publicly accessible configuration file in the .well-known directory of your site at /.well-known/tpcd/grace-period.json. The grace-period.json file provides opt-out percentages for either or both of the deprecation trial grace periods:

  • FirstPartyOptOutPercentage
  • ThirdPartyOptOutPercentage

These can have values of 0, 25, 50, or 100. For example:

{
  "ThirdPartyOptOutPercentage": 25
}

Changing the grace period opt-out percentage does not affect the proportion of Chrome clients subject to Chrome's Tracking Protection mechanism, which restricts third-party cookies for 1% of Chrome clients.

For example: if grace period opt-out is set to 50% for a website, then 0.5% (1% * 50%) of Chrome clients will have third-party cookies restricted on the site.

Test deployment

If you want to take advantage of the grace period opt-out, we recommend you begin by deploying grace-period.json as soon as possible, with a value of 0 for one or both of the keys. This will allow you to validate if Chrome is processing the file as expected, without affecting grace period activation. You can then begin to increase the percentage when you're ready. In future we plan to provide tools for developers to query grace period activation status for sites accessed by their browser.

The grace-period.json file must be well formed in order to take effect. To avoid errors, check your file with the grace period opt-out validation tool.

Subdomains

As shown in the following examples, the scope of the opt-out is the same as the scope of the origin registered for the deprecation trial. If the deprecation trial registration has subdomain matching enabled, then grace period opt-out applies to the registered origin and its subdomains.

The .well-known/tpcd/grace-period.json configuration file must be hosted at the origin registered for the deprecation trial.

Registered origin Subdomain matching? Configuration file Opt-out scope
https://foo.example No https://foo.example/.well-known/tpcd/grace-period.json https://foo.example
https://sub.foo.example No https://sub.foo.example/.well-known/tpcd/grace-period.json https://sub.foo.example
https://foo.example Yes https://foo.example/.well-known/tpcd/grace-period.json https://*.foo.example

Debug the opt-out mechanism

Google servers regularly check the grace-period.json file (if it exists) on each site for which the grace period is active. Opt-out percentages can then be distributed to all Chrome clients, though this process may take 24 to 48 hours to complete. Chrome will be providing a tool so site developers can check grace period activation status from the Chrome DevTools Issues panel to understand when an opt-out is in effect.

Examples

Third-party example

In the following example, third-party.example has registered for the third-party deprecation trial and the grace period has been activated for them. They host the following file at third-party.example/well-known/tpcd/grace-period.json:

{
  "ThirdPartyOptOutPercentage": 25
}

With this file in place, the grace period will be deactivated for 25% of Chrome clients that access sites or services from third-party.example. For Chrome clients subject to Tracking Protection, third-party cookies from third-party.example will be restricted unless the third-party deprecation trial is active.

First-party example

In the following example, first-party.example has registered for the first-party deprecation trial and the grace period has been activated for them. They host the following file at first-party.example/well-known/tpcd/grace-period.json:

{
  "FirstPartyOptOutPercentage": 50
}

With this in place, the grace period will be deactivated for 50% of Chrome clients that visit their site. For any of these Chrome clients that are part of the Tracking Protection group, third-party cookies will be restricted

Find out more

If you have questions regarding the opt-out mechanism, file an issue on the Privacy Sandbox support repository.