Related Website Sets (RWS) is a web platform mechanism to help browsers understand the relationships amongst a collection of domains. This allows browsers to make key decisions to enable certain site functions (such as whether to allow access to cross-site cookies) and to present this information to users.
Many sites rely on multiple domains to serve a single user experience. Organizations may want to maintain different top-level domains for multiple use cases, such as country-specific domains or service domains for hosting images or video. Related Website Sets allows sites to share data across domains, with specific controls.
What is a Related Website Set?
At a high level, a Related Website Set is a collection of domains, for which there is a single "set primary" and potentially multiple "set members."
In the following example, primary lists the primary domain, and
associatedSites lists domains that meet the requirements of the associated
subset.
{
"primary": "https://primary.com",
"associatedSites": ["https://associate1.com", "https://associate2.com", "https://associate3.com"]
}
Related Website Sets are listed in a public JSON file hosted on GitHub. This is the canonical source for all approved sets. Browsers consume this file to determine whether or not sites belong to the same Related Website Set.
Only those with administrative control over a domain can create a set with that domain. Submitters are required to declare the relationship between each "set member" to its "set primary." Set members could include a range of different domain types and must be part of a subset based on a use case.
If your application depends on access to cross-site cookies (also called third-party cookies) across sites within the same Related Website Set, you can use Storage Access API (SAA) and the requestStorageAccessFor API to request access to those cookies. Depending on the subset that each site is part of, the browser may handle the request differently.
To learn more about the process and requirements for submitting sets, check out the submission guidelines. Submitted sets will go through various technical checks to validate the submissions.
Related Website Sets use cases
Related Website Sets are a good match for cases when an organization needs a form of shared identity across different top-level sites.
Some of the use cases for Related Website Sets are:
- Country customization. Leveraging localized sites while relying on shared infrastructure (example.co.uk may rely on a service hosted by example.ca).
- Service domain integration. Leveraging service domains that users never directly interact with, but provide services across the same organization's sites (example-cdn.com).
- User content separation. Accessing data on different domains that
separate user-uploaded content from other site content for security reasons,
while allowing the sandboxed domain access to authentication (and other)
cookies. If you are serving inactive user-uploaded content, you may also be
able to safely host it on the same domain by following best
practices.
- Embedded authenticated content. Supporting embedded content from across affiliated properties (videos, documents, or resources restricted to the user signed in on the top-level site).
- Sign-in. Supporting sign-in across affiliated properties. The FedCM API may also be appropriate for some use cases.
- Analytics. Deploying analytics and measurement of user journeys across affiliated properties to improve quality of services.
Related Website Sets integration details
Storage Access API
The Storage Access API (SAA) provides a way for embedded cross-origin content to access the storage that it would normally only have access to in a first-party context.
Embedded resources can use SAA methods to check whether they currently have access to storage, and to request access from the user agent.
When third-party cookies are blocked but Related Website Sets (RWS) is enabled, Chrome will automatically grant permission in intra-RWS contexts, and will show a prompt to the user otherwise. (An "intra-RWS context" is a context, such as an iframe, whose embedded site and top-level site are in the same RWS.)
Check and request storage access
To check whether they currently have access to storage, embedded sites can use
Document.hasStorageAccess()
method.
The method returns a promise that resolves with a boolean value indicating whether the document already has access to its cookies or not. The promise also returns true if the iframe is same-origin as the top frame.
To request access to cookies in a cross-site context embedded sites can use
Document.requestStorageAccess()
(rSA).
The requestStorageAccess() API is meant to be called from within an iframe.
That iframe has to have just received user interaction (a user
gesture,
which is required by all browsers), but Chrome additionally requires that at
some point in the last 30 days, the user has visited the site that owns that
iframe and has interacted with that site specifically—as a top-level document,
not in an iframe.
requestStorageAccess() returns a promise that resolves if the access to
storage was granted. The promise is rejected, citing the reason, if access was
denied for any reason.
requestStorageAccessFor in Chrome
The Storage Access API only allows embedded sites to request access to storage
from within