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:
FirstPartyOptOutPercentageThirdPartyOptOutPercentage
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.
- Explainer for the Third-party Cookie Grace Period Opt-Out
- The "tpcd/grace-period.json" Well-Known Resource Identifier
- Intent to Ship: Third-party Cookie Grace Period Opt-Out
- First-party deprecation trial
- Third-party deprecation trial
- Get started with origin trials
- Troubleshoot Chrome origin trials
- Well-known URI
- RFC 8615 - Well-Known Uniform Resource Identifiers (URIs)