Zestawy powiązanych witryn to mechanizm platformy internetowej, który pomaga przeglądarkom zrozumieć relacje między zbiorem domen. Umożliwia to przeglądarkom podejmowanie kluczowych decyzji dotyczących włączania określonych funkcji witryny (np. zezwalania na dostęp do plików cookie w wielu witrynach) i prezentowanie tych informacji użytkownikom.
Chrome wycofuje obsługę plików cookie innych firm, aby zachować kluczowe przypadki użycia w internecie, a jednocześnie zwiększyć prywatność użytkowników. Na przykład wiele witryn korzysta z wielu domen, aby zapewnić użytkownikom wygodę. Organizacje mogą chcieć utrzymywać różne domeny najwyższego poziomu na potrzeby różnych zastosowań, takich jak domeny dla poszczególnych krajów lub domeny usług do hostowania obrazów lub filmów. Zestawy powiązanych witryn umożliwiają witrynom udostępnianie danych w różnych domenach z możliwością stosowania określonych ustawień.
Co to jest zestaw powiązanych witryn?
Ogólnie rzecz biorąc, zestaw powiązanych witryn to zbiór domen, w których przypadku istnieje jedna „witryna główna” i potencjalnie wiele „witryn członkowskich”.
W tym przykładzie primary
to domena główna, a associatedSites
to domeny, które spełniają wymagania powiązanego podzbioru.
{
"primary": "https://primary.com",
"associatedSites": ["https://associate1.com", "https://associate2.com", "https://associate3.com"]
}
Kanoniczna lista zestawów powiązanych witryn to publicznie dostępna lista w formacie pliku JSON hostowana w repozytorium GitHub zestawów powiązanych witryn, która służy jako źródło informacji o wszystkich zestawach. Chrome używa tego pliku do określenia sposobu działania.
Tylko osoby z kontrolą administracyjną nad domeną mogą tworzyć zestawy z tą domeną. Zgłaszający muszą zadeklarować relację między każdym „elementem zbioru” a jego „elementem głównym zbioru”. Członkowie zbioru mogą należeć do różnych typów domen i muszą być częścią podzbioru na podstawie przypadku użycia.
Jeśli Twoja aplikacja wymaga dostępu do plików cookie w wielu witrynach (zwanych też plikami cookie innych firm) w ramach tego samego zestawu powiązanych witryn, możesz użyć interfejsu Storage Access API (SAA) i interfejsu requestStorageAccessFor API, aby poprosić o dostęp do tych plików cookie. W zależności od podzbioru, do którego należy dana witryna, przeglądarka może inaczej obsługiwać żądanie.
Więcej informacji o procesie i wymaganiach dotyczących przesyłania zestawów znajdziesz w wytycznych dotyczących przesyłania treści. Przesłane zestawy zostaną poddane różnym weryfikacjom technicznym.
Przypadki użycia zestawów powiązanych witryn
Zestawy powiązanych witryn są dobrym rozwiązaniem, gdy organizacja potrzebuje wspólnej tożsamości w różnych witrynach najwyższego poziomu.
Oto kilka przykładowych zastosowań zestawów powiązanych witryn:
- Dostosowywanie kraju. Korzystanie z lokalizowanych witryn przy użyciu wspólnej infrastruktury (example.co.uk może korzystać z usługi hostowanej przez example.ca).
- Integracja z domeną usługi. Korzystanie z domen usług, z którymi użytkownicy nigdy nie wchodzą w bezpośrednią interakcję, ale które zapewniają usługi w ramach witryn tej samej organizacji (example-cdn.com).
- oddzielenie treści użytkowników. Dostęp do danych w różnych domenach, które ze względów bezpieczeństwa oddzielają treści przesłane przez użytkowników od innych treści witryny, a jednocześnie umożliwiają domenie w piaskownicy dostęp do plików cookie uwierzytelniających (i innych). Jeśli wyświetlasz nieaktywne treści przesłane przez użytkowników, możesz je bezpiecznie hostować w tej samej domenie, postępując zgodnie ze sprawdzonymi metodami.
- Umieszczone treści uwierzytelnione. Obsługa treści umieszczonych z różnych usług powiązanych (filmów, dokumentów lub zasobów ograniczonych do użytkownika zalogowanego w witrynie najwyższego poziomu).
- Logowanie. Obsługa logowania w powiązanych usługach. W niektórych przypadkach odpowiedni może być też interfejs FedCM API.
- Analytics. wdrażanie analiz i pomiarów ścieżek użytkowników w powiązanych usługach w celu poprawy jakości usług;
Szczegóły integracji zestawów powiązanych witryn
Interfejs Storage Access API
Interfejs Storage Access API (SAA) umożliwia zaszytym treściom z innych źródeł dostęp do pamięci, do której normalnie mają dostęp tylko w kontekście własnych zasobów.
Zasoby osadzone mogą używać metod SAA do sprawdzania, czy mają obecnie dostęp do pamięci, oraz do wysyłania do agenta użytkownika żądania dostępu.
Gdy pliki cookie innych firm są zablokowane, ale zestawy powiązanych witryn są włączone, Chrome automatycznie przyznaje uprawnienia w kontekście zestawów powiązanych witryn, a w innych przypadkach wyświetla użytkownikowi odpowiedni komunikat. („Kontekst w ramach RWS” to kontekst, np. element iframe, którego witryna osadzona i witryna najwyższego poziomu znajdują się w tym samym RWS).
Sprawdzanie i proszenie o dostęp do pamięci masowej
Aby sprawdzić, czy mają obecnie dostęp do pamięci, umieszczone witryny mogą użyć metody Document.hasStorageAccess()
.
Metoda zwraca obietnicę, która zwraca wartość logiczną wskazującą, czy dokument ma już dostęp do swoich plików cookie. Obiet na obietnicy zwraca też wartość „prawda”, jeśli element iframe ma ten sam element docelowy co element nadrzędny.
Aby żądać dostępu do plików cookie w kontekście wielu witryn, witryny umieszczone mogą używać Document.requestStorageAccess()
(rSA).
Interfejs API requestStorageAccess()
należy wywoływać z poziomu elementu iframe. Element iframe musi zostać właśnie aktywowany przez użytkownika (gestura użytkownika, która jest wymagana przez wszystkie przeglądarki), ale Chrome wymaga dodatkowo, aby w jakimś momencie w ciągu ostatnich 30 dni użytkownik odwiedził witrynę, do której należy ten element iframe, i wszedł z nią w interakcję – jako dokument najwyższego poziomu, a nie w ramach elementu iframe.
requestStorageAccess()
zwraca obietnicę, która zwraca wartość wskazującą, czy dostęp do pamięci został przyznany. Obietnica jest odrzucana z wspomnianym powodem, jeśli dostęp został odrzucony z jakiegokolwiek powodu.
requestStorageAccessFor w Chrome
Interfejs Storage Access API zezwala tylko osadzonym witrynom na żądanie dostępu do pamięci z poziomu elementów <iframe>
, które zostały wywołane przez użytkownika.
To powoduje problemy z zastosowaniem interfejsu Storage Access API w przypadku witryn najwyższego poziomu, które używają obrazów w wielu witrynach lub tagów skryptu wymagających plików cookie.
Aby rozwiązać ten problem, w Chrome udostępniliśmy witrynom najwyższego poziomu możliwość żądania dostępu do pamięci masowej w imieniu określonych źródeł za pomocą Document.requestStorageAccessFor()
(rSAFor).
document.requestStorageAccessFor('https://target.site')
Interfejs API requestStorageAccessFor()
ma być wywoływany przez dokument najwyższego poziomu. Dokument musi też zostać właśnie wyświetlony użytkownikowi. W przeciwieństwie do requestStorageAccess()
Chrome nie sprawdza interakcji w dokumentach najwyższego poziomu z ostatnich 30 dni, ponieważ użytkownik jest już na stronie.
Sprawdzanie uprawnień dostępu do pamięci
Dostęp do niektórych funkcji przeglądarki, takich jak aparat czy geolokalizacja, zależy od udzielonych przez użytkownika uprawnień. Interfejs Permissions API umożliwia sprawdzenie stanu uprawnień dostępu do interfejsu API – czy zostały one przyznane, odrzucone czy wymagają interakcji użytkownika, np. kliknięcia promptu lub interakcji ze stroną.
Stan uprawnień możesz sprawdzić za pomocą funkcji navigator.permissions.query()
.
Aby sprawdzić uprawnienia dostępu do miejsca na dane w bieżącym kontekście, musisz podać ciąg 'storage-access'
:
navigator.permissions.query({name: 'storage-access'})
Aby sprawdzić uprawnienia dostępu do miejsca na dane dla określonego punktu początkowego, musisz podać ciąg znaków 'top-level-storage-access'
:
navigator.permissions.query({name: 'top-level-storage-access', requestedOrigin: 'https://target.site'})
Aby chronić integralność zaszyfrowanego źródła, sprawdzane są tylko uprawnienia przyznane przez dokument najwyższego poziomu za pomocą document.requestStorageAccessFor
.
W zależności od tego, czy uprawnienie może być przyznane automatycznie, czy wymaga interakcji użytkownika, zwróci wartość prompt
lub granted
.
Model na ramkę
Przyznawanie uprawnień rSA odbywa się na podstawie ramki. Przyznawanie uprawnień rSA i rSAFor jest traktowane jako oddzielne uprawnienia.
Każda nowa ramka będzie musiała osobno prosić o dostęp do pamięci masowej, który zostanie automatycznie przyznany. Tylko pierwsze żądanie wymaga działania użytkownika. Kolejne żądania inicjowane przez iframe, takie jak nawigacja czy podresury, nie muszą czekać na działanie użytkownika, ponieważ zostało ono już wykonane w ramach sesji przeglądania przez pierwsze żądanie.
Odświeżanie, ponowne wczytywanie lub ponowne tworzenie iframe wymaga ponownego wysłania prośby o dostęp.
Wymagania dotyczące plików cookie
Pliki cookie muszą zawierać atrybuty SameSite=None
i Secure
, ponieważ rSA daje dostęp tylko do plików cookie, które są już oznaczone do użycia w kontekście wielu witryn.
Pliki cookie z atrybutem SameSite=Lax
, SameSite=Strict
lub bez atrybutu SameSite
są przeznaczone tylko do użytku własnego i nigdy nie będą udostępniane w kontekście wielu stron niezależnie od atrybutu rsa.
Bezpieczeństwo
W przypadku rSAFor żądania dotyczące podzasobów wymagają nagłówków współdzielenia zasobów pomiędzy serwerami z różnych domen (CORS) lub atrybutu crossorigin
w zasobach, co zapewnia wyraźną zgodę.
Przykłady implementacji
Prośba o dostęp do pamięci z poziomu osadzonego międzyźródłowego elementu iframe

requestStorageAccess()
w umieszczonym filmie w innej witrynieSprawdzanie, czy masz dostęp do pamięci
Aby sprawdzić, czy masz już dostęp do pamięci masowej, użyj document.hasStorageAccess()
.
Jeśli obietnica zwróci wartość true, możesz uzyskać dostęp do pamięci w kontekście międzywitrynowym. Jeśli zwróci wartość false, musisz poprosić o dostęp do miejsca na dane.
document.hasStorageAccess().then((hasAccess) => {
if (hasAccess) {
// You can access storage in this context
} else {
// You have to request storage access
}
});
Poproś o dostęp do pamięci
Jeśli musisz poprosić o dostęp do pamięci, najpierw sprawdź uprawnienia dostępu do pamięci navigator.permissions.query({name: 'storage-access'})
, aby dowiedzieć się, czy wymagają one działania użytkownika czy mogą być przyznane automatycznie.
Jeśli uprawnienie to granted
, możesz wywołać document.requestStorageAccess()
, a zapytanie powinno się powieść bez interakcji użytkownika.
Jeśli stan uprawnień to prompt
, musisz zainicjować wywołanie document.requestStorageAccess()
po wykonaniu przez użytkownika jakiejś czynności, np. kliknięciu przycisku.
Przykład:
navigator.permissions.query({name: 'storage-access'}).then(res => {
if (res.state === 'granted') {
// Permission has already been granted
// You can request storage access without any user gesture
rSA();
} else if (res.state === 'prompt') {
// Requesting storage access requires user gesture
// For example, clicking a button
const btn = document.createElement("button");
btn.textContent = "Grant access";
btn.addEventListener('click', () => {
// Request storage access
rSA();
});
document.body.appendChild(btn);
}
});
function rSA() {
if ('requestStorageAccess' in document) {
document.requestStorageAccess().then(
(res) => {
// Use storage access
},
(err) => {
// Handle errors
}
);
}
}
Kolejne żądania z ramki, nawigacji lub zasobów podrzędnych będą automatycznie miały uprawnienia do dostępu do plików cookie w wielu witrynach. hasStorageAccess()
zwraca wartość Prawda, a pliki cookie z innych witryn z tego samego zestawu powiązanych witryn będą wysyłane w ramach tych żądań bez dodatkowych wywołań kodu JavaScript.
Witryny najwyższego poziomu żądające dostępu do plików cookie w imieniu witryn w różnych domenach

requestStorageAccessFor()
w witrynie najwyższego poziomu dla innego źródłaStrony najwyższego poziomu mogą używać zasady requestStorageAccessFor()
, aby żądać dostępu do miejsca na dane w imieniu określonych źródeł.
hasStorageAccess()
sprawdza tylko, czy wywołująca go witryna ma dostęp do pamięci, więc witryna najwyższego poziomu może sprawdzić uprawnienia dla innego źródła.
Aby sprawdzić, czy użytkownik otrzyma prośbę o dostęp lub czy dostęp do pamięci został już przyznany określonemu źródłu, wywołaj funkcję navigator.permissions.query({name: 'top-level-storage-access', requestedOrigin: 'https://target.site'})
.
Jeśli uprawnienia to granted
, możesz wywołać funkcję document.requestStorageAccessFor('https://target.site')
. Powinien on działać bez gestu użytkownika.
Jeśli uprawnienie to prompt
, musisz wywołać funkcję document.requestStorageAccessFor('https://target.site')
w reakcji na gest użytkownika, np. kliknięcie przycisku.
Przykład:
navigator.permissions.query({name:'top-level-storage-access',requestedOrigin: 'https://target.site'}).then(res => {
if (res.state === 'granted') {
// Permission has already been granted
// You can request storage access without any user gesture
rSAFor();
} else if (res.state === 'prompt') {
// Requesting storage access requires user gesture
// For example, clicking a button
const btn = document.createElement("button");
btn.textContent = "Grant access";
btn.addEventListener('click', () => {
// Request storage access
rSAFor();
});
document.body.appendChild(btn);
}
});
function rSAFor() {
if ('requestStorageAccessFor' in document) {
document.requestStorageAccessFor().then(
(res) => {
// Use storage access
},
(err) => {
// Handle errors
}
);
}
}
Po wywołaniu funkcji requestStorageAccessFor()
żądania między witrynami będą zawierać pliki cookie, jeśli zawierają CORS lub atrybut crossorigin, więc witryny mogą poczekać przed wywołaniem żądania.
Żądania muszą używać opcji credentials: 'include'
, a zasoby muszą zawierać atrybut crossorigin="use-credentials"
.
function checkCookie() {
fetch('https://related-website-sets.glitch.me/getcookies.json', {
method: 'GET',
credentials: 'include'
})
.then((response) => response.json())
.then((json) => {
// Do something
});
}
Jak przetestować lokalnie
Wymagania wstępne
Aby przetestować zestawy powiązanych stron lokalnie, uruchom Chrome w wersji 119 lub nowszej z wiersza poleceń i włącz test-third-party-cookie-phaseout
flagę Chrome.
Włącz flagę w Chrome
Aby włączyć odpowiednią flagę Chrome, na pasku adresu otwórz chrome://flags#test-third-party-cookie-phaseout
i zmień flagę na Enabled
. Po zmianie flag uruchom ponownie przeglądarkę.
Uruchom Chrome z lokalnym zestawem powiązanych witryn
Aby uruchomić Chrome z lokalnie zadeklarowanym zestawem powiązanych witryn, utwórz obiekt JSON zawierający adresy URL, które są elementami zestawu, i przekaż go do --use-related-website-set
.
Dowiedz się więcej o uruchamianiu Chromium z flagami.
--use-related-website-set="{\"primary\": \"https://related-website-sets.glitch.me\", \"associatedSites\": [\"https://rws-member-1.glitch.me\"]}" \
https://related-website-sets.glitch.me/
Przykład
Aby włączyć zestawy powiązanych witryn lokalnie, musisz włączyć test-third-party-cookie-phaseout
w chrome://flags
i uruchomić Chrome z linii poleceń z flagą --use-related-website-set
zawierającą obiekt JSON z adresami URL, które są elementami zestawu.
--use-related-website-set="{\"primary\": \"https://related-website-sets.glitch.me\", \"associatedSites\": [\"https://rws-member-1.glitch.me\"]}" \
https://related-website-sets.glitch.me/
Sprawdź, czy masz dostęp do plików cookie na wielu stronach
Wywołuj interfejsy API (rSA lub rSAFor) z witryn, które są testowane, i sprawdź dostęp do plików cookie w wielu witrynach.
Proces przesyłania zestawów powiązanych witryn
Aby zadeklarować relację między domenami i określić, do którego podzbioru należą, wykonaj te czynności:
1. Identyfikowanie RWS
Określ odpowiednie domeny, w tym witrynę główną zestawu i witryny członkowskie, które będą częścią zestawu powiązanych witryn. Określ też, do jakiego typu podzbioru należy każdy element zbioru.
2. Tworzenie zgłoszenia RWS
Utwórz lokalną kopię (klon lub rozwidlenie) repozytorium GitHub. W nowej gałęzi wprowadź zmiany w pliku related_website_sets.JSON, aby odzwierciedlały Twój zestaw. Aby mieć pewność, że zestaw ma prawidłowe formatowanie i strukturę JSON, możesz użyć narzędzia do generowania plików JSON.
3. Sprawdź, czy usługa RWS spełnia wymagania techniczne
Upewnij się, że są spełnione wymagania dotyczące tworzenia zestawów i wymagania weryfikacji zestawów.
4. Testowanie usługi RWS lokalnie
Zanim utworzysz pull request (PR), aby przesłać zestaw, przetestuj go lokalnie, aby upewnić się, że spełnia on wszystkie wymagania.
5. Przesyłanie zestawu powiązanych witryn
Prześlij zestaw powiązanych witryn, tworząc PR do pliku related_website_sets.JSON, w którym Chrome hostuje kanoniczną listę zestawów powiązanych witryn. (aby tworzyć PR, musisz mieć konto GitHub i przed dodaniem treści do listy musisz podpisać Umowę licencyjną dla współtwórców).
Po utworzeniu PR przeprowadzana jest seria kontroli, aby sprawdzić, czy są spełnione wymagania z kroku 3. Sprawdzamy na przykład, czy podpisano umowę CLA i czy plik .well-known
jest prawidłowy.
Jeśli proces się powiedzie, w zgłoszeniu PR zostanie wskazane, że wszystkie testy zostały zaliczone. Zatwierdzone zmiany zostaną ręcznie scalone w partiach z kanoniczną listą zestawów powiązanych witryn raz w tygodniu (we wtorek o 12:00 czasu wschodniego). Jeśli którykolwiek z testów zakończy się niepowodzeniem, osoba przesyłająca otrzyma powiadomienie w GitHubu. Osoba przesyłająca może poprawić błędy i zaktualizować PR. Pamiętaj, że:
- Jeśli proces przesyłania danych nie powiedzie się, pojawi się komunikat o błędzie z dodatkowymi informacjami o przyczynie niepowodzenia. (na przykład).
- Wszystkie kontrole techniczne dotyczące przesyłania zestawów są przeprowadzane w GitHubie, a zatem wszystkie błędy przesyłania wynikające z kontroli technicznych będą widoczne w GitHubie.
Zasady dotyczące firm
Chrome ma 2 zasady, które spełniają potrzeby użytkowników biznesowych:
- Systemy, które mogą nie być w stanie zintegrować się z zestawami powiązanych witryn, mogą wyłączyć funkcję zestawów powiązanych witryn we wszystkich instancjach Chrome Enterprise za pomocą zasady
RelatedWebsiteSetsEnabled
. - Niektóre systemy korporacyjne mają witryny tylko dla użytkowników wewnętrznych (np. intranet) z możliwością rejestracji domen, które różnią się od domen w zbiorze powiązanych witryn. Jeśli muszą traktować te witryny jako część zestawu powiązanych witryn bez ich publicznego wyświetlania (ponieważ domeny mogą być poufne), mogą uzupełnić lub zastąpić publiczną listę zestawów powiązanych witryn za pomocą zasady
RelatedWebsiteSetsOverrides
.
Chrome rozwiązuje dowolne przecięcie zbiorów publicznych i firmowych na jeden z 2 sposobów, w zależności od tego, czy podano wartość replacemements
czy additions
.
Na przykład w przypadku publicznego zbioru {primary: A, associated: [B, C]}
:
replacements seta: |
{primary: C, associated: [D, E]} |
Zestaw firmowy pochłania wspólną witrynę, tworząc nowy zestaw. | |
Utworzone zestawy: | {primary: A, associated: [B]} {primary: C, associated: [D, E]} |
additions seta: |
{primary: C, associated: [D, E]} |
Zestawy publiczne i Enterprise są łączone. | |
Utworzony zestaw: | {primary: C, associated: [A, B, D, E]} |
Rozwiązywanie problemów z zestawami powiązanych witryn
„Wezwanie użytkownika” i „Gest użytkownika”
„Prośba do użytkownika” i „gesty użytkownika” to różne rzeczy. Chrome nie wyświetla prośby o uprawnienia użytkownikom w przypadku witryn należących do tego samego zestawu powiązanych witryn, ale nadal wymaga, aby użytkownik wszedł w interakcję ze stroną. Zanim przyznasz uprawnienia, Chrome wymaga gestu użytkownika, zwanego też „interakcją użytkownika” lub „aktywacją użytkownika”. Wynika to z tego, że użycie interfejsu Storage Access API poza kontekstem zestawu powiązanych stron internetowych (czyli requestStorageAccess()
) wymaga również gestu użytkownika ze względu na zasady projektowania platformy internetowej.
Dostęp do plików cookie lub pamięci innych witryn
Powiązane zestawy witryn nie scalają miejsca na dane w przypadku różnych witryn: umożliwiają tylko łatwiejsze (bez prompta) requestStorageAccess()
wywoływanie. Zestawy powiązanych witryn zmniejszają tylko trudności związane z korzystaniem z interfejsu Storage Access API, ale nie określają, co należy zrobić po przywróceniu dostępu. Jeśli A i B to różne witryny w tym samym zestawie powiązanych witryn, a A zawiera w swojej treści witryny B, witryna B może wywołać funkcję requestStorageAccess()
i uzyskać dostęp do pamięci własnej bez wyświetlania prośby użytkownikowi. Zestawy powiązanych witryn nie wykonują żadnej komunikacji między witrynami. Na przykład skonfigurowanie zestawu powiązanych witryn nie spowoduje, że pliki cookie należące do witryny B zaczną być wysyłane do witryny A. Jeśli chcesz udostępnić te dane, musisz to zrobić samodzielnie, na przykład wysyłając window.postMessage
z ramki iframe B do ramki A.
Dostęp do plików cookie bez podziału na partycje domyślnie
Zestawy powiązanych witryn nie zezwalają na domyślny dostęp do plików cookie bez wywoływania interfejsu API. Pliki cookie w wielu witrynach nie są udostępniane domyślnie w ramach zestawu. Zestawy powiązanych witryn umożliwiają tylko witrynom w ramach zestawu pominięcie prośby o przyznanie uprawnień interfejsowi Storage Access API.
Element iframe musi wywołać funkcję document.requestStorageAccess()
, jeśli chce uzyskać dostęp do plików cookie. Może też wywołać funkcję document.requestStorageAccessFor()
na stronie najwyższego poziomu.
Podziel się opinią
Przesyłanie zestawu na GitHubie oraz korzystanie z interfejsów Storage Access API i requestStorageAccessFor
API to okazja do podzielenia się swoimi doświadczeniami związanymi z tym procesem i wszelkimi problemami, na które się natkniesz.
Aby dołączyć do dyskusji na temat zestawów powiązanych witryn:
- Dołącz do publicznej listy mailingowej zestawów powiązanych witryn.
- zgłaszaj problemy i śledź dyskusję w repozytorium GitHub zestawów powiązanych witryn.