Powiązane zestawy witryn: przewodnik dla programistów

Zestawy powiązanych witryn to mechanizm platformy internetowej, który pomaga przeglądarkom rozpoznawać relacje między grupami domen. Dzięki temu przeglądarki mogą podejmować kluczowe decyzje dotyczące włączania określonych funkcji witryny (np. zezwalania na dostęp do plików cookie pochodzących z różnych stron) i wyświetlania tych informacji użytkownikom.

Wycofywanie plików cookie innych firm w Chrome ma na celu utrzymanie kluczowych przypadków użycia w internecie przy jednoczesnej poprawie prywatności użytkowników. Na przykład wiele witryn używa wielu domen w celu obsługi jednego użytkownika. Organizacje mogą chcieć utrzymać różne domeny najwyższego poziomu do różnych zastosowań, takich jak domeny krajowe lub domeny usług do hostowania obrazów lub filmów. Zestawy powiązanych witryn umożliwiają witrynom udostępnianie danych między domenami z wykorzystaniem określonych ustawień.

Ogólnie zestaw powiązanych witryn to zbiór domen, dla których istnieje 1 „ustawienie podstawowe” i potencjalnie większa liczba „elementów zestawu”.

W poniższym przykładzie kolumna primary zawiera domenę podstawową, a associatedSites zawiera domeny spełniające wymagania powiązanego podzbioru.

{
  "primary": "https://primary.com",
  "associatedSites": ["https://associate1.com", "https://associate2.com", "https://associate3.com"]
}

Lista zestawów powiązanych witryn kanonicznych to dostępna publicznie lista w formacie pliku JSON hostowanym w repozytorium zestawów powiązanych witryn na GitHubie, który jest źródłem informacji dla wszystkich zbiorów. Chrome przetwarza ten plik, aby zastosować go do swojego działania.

Tylko osoby posiadające kontrolę administracyjną nad domeną mogą tworzyć zestawy przy użyciu tej domeny. Osoby przesyłające muszą zadeklarować relację między każdym „elementem zestawu” ze swoim „elementem głównym”. Elementy zestawu mogą obejmować zakres różnych typów domen i muszą należeć do podzbioru w zależności od przypadku użycia.

Jeśli Twoja aplikacja wymaga dostępu do plików cookie innych firm (nazywanych też plikami cookie innych firm) w witrynach w tym samym zestawie powiązanych witryn, możesz poprosić o dostęp do tych plików za pomocą interfejsu Storage Access API (SAA) i requestStorageAccessFor. W zależności od podzbioru, do którego należy dana witryna, przeglądarka może inaczej obsłużyć żądanie.

Aby dowiedzieć się więcej o procesie i wymaganiach dotyczących przesyłania zestawów, przeczytaj wskazówki na temat przesyłania zestawów. Przesłane zestawy przechodzą przez różne testy techniczne w celu sprawdzenia ich poprawności.

Zestawy powiązanych witryn dobrze sprawdzają się w przypadkach, gdy organizacja potrzebuje formy wspólnej tożsamości obejmujących różne witryny najwyższego poziomu.

Oto niektóre przypadki użycia zestawów powiązanych witryn:

  • Dostosowywanie kraju. Wykorzystanie zlokalizowanych witryn w oparciu o infrastrukturę współdzieloną (example.co.uk może korzystać z usługi hostowanej w domenie example.ca).
  • Integracja z domeną usługi Wykorzystanie domen usług, z którymi użytkownicy nigdy nie wchodzą w bezpośrednią interakcję, ale świadczą usługi w witrynach tej samej organizacji (example-cdn.com).
  • Rozdzielanie treści użytkowników. Uzyskiwanie dostępu 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 pozwalają domenie piaskownicy na dostęp do uwierzytelniania (i innych) plików cookie. Jeśli wyświetlasz nieaktywne treści przesłane przez użytkowników, możesz też bezpiecznie przechowywać je w tej samej domenie, stosując sprawdzone metody.
  • Umieszczona uwierzytelniona treść. Obsługa umieszczonych treści z powiązanych usług (filmów, dokumentów lub zasobów dostępnych tylko dla użytkownika zalogowanego w witrynie najwyższego poziomu).
  • Zaloguj się. Obsługa logowania się w powiązanych usługach. W niektórych przypadkach może się też przydać interfejs FedCM API.
  • Statystyki Wdrażanie analiz i pomiarów ścieżek użytkowników w powiązanych usługach w celu poprawy jakości usług.

Interfejs Storage Access API

Obsługa przeglądarek

  • 119
  • 85
  • 65
  • 11.1

Źródło

Interfejs Storage Access API (SAA) zapewnia umieszczonym treściom z różnych domen dostęp do pamięci, do której normalnie nie mieliby dostępu tylko w kontekście własnym.

Zasoby osadzone mogą używać metod SAA, aby sprawdzać, czy obecnie mają dostęp do pamięci, i prosić klienta użytkownika o dostęp.

Jeśli pliki cookie innych firm są zablokowane, ale włączone są zestawy powiązanych witryn (RWS), Chrome automatycznie przyznaje uprawnienia w kontekstach wewnątrz systemu RWS. W przeciwnym razie wyświetla użytkownikowi odpowiedni komunikat. („Kontekst w ramach RWS” to kontekst, np. element iframe, którego witryna umieszczona i witryna najwyższego poziomu znajdują się w tym samym RWS).

Sprawdź i poproś o dostęp do pamięci

Aby sprawdzić, czy użytkownik ma obecnie dostęp do pamięci, umieszczone witryny mogą użyć metody Document.hasStorageAccess().

Metoda zwraca obietnicę, która kończy się wartością logiczną wskazującą, czy dokument ma już dostęp do plików cookie. Obietnica zwraca też wartość „prawda”, jeśli element iframe jest z tego samego źródła co górna ramka.

Aby poprosić o dostęp do plików cookie w umieszczonych witrynach w kontekście innych stron, możesz użyć narzędzia Document.requestStorageAccess() (rSA).

Interfejs API requestStorageAccess() powinien być wywoływany z elementu iframe. Ten element iframe musi właśnie otrzymać interakcję z użytkownikiem (gest użytkownika, co jest wymagane przez wszystkie przeglądarki), ale Chrome dodatkowo wymaga, aby w ciągu ostatnich 30 dni użytkownik odwiedził witrynę, która jest właścicielem elementu iframe, i weszła z nią w interakcję – w postaci dokumentu najwyższego poziomu, a nie elementu iframe.

requestStorageAccess() zwraca obietnicę, która zniknie, jeśli dostęp do miejsca na dane zostanie przyznany. Jeśli z jakiegokolwiek powodu dostęp zostanie odmówiony, obietnica zostanie odrzucona wraz z podaniem przyczyny.

requestStorageAccessFor w Chrome

Obsługa przeglądarek

  • 119
  • 119
  • x
  • x

Źródło

Interfejs Storage Access API zezwala witrynom umieszczonym na wysyłanie próśb o dostęp do pamięci tylko z poziomu elementów <iframe>, które wywołały interakcję użytkownika.

Stanowi to wyzwanie przy wdrażaniu interfejsu Storage Access API w witrynach najwyższego poziomu, które używają obrazów z innych witryn lub tagów skryptów wymagających plików cookie.

Aby rozwiązać ten problem, Chrome zaimplementował sposób, w jaki witryny najwyższego poziomu mogą prosić o dostęp do pamięci w imieniu określonych źródeł za pomocą Document.requestStorageAccessFor() (rSAFor).

 document.requestStorageAccessFor('https://target.site')

Interfejs requestStorageAccessFor() API powinien być wywoływany przez dokument najwyższego poziomu. Ten dokument też musi być w trakcie interakcji z użytkownikiem. W przeciwieństwie do requestStorageAccess() Chrome nie sprawdza jednak interakcji z dokumentem najwyższego poziomu w ciągu ostatnich 30 dni, ponieważ użytkownik jest już na stronie.

Sprawdź uprawnienia dostępu do pamięci

Dostęp do niektórych funkcji przeglądarki, takich jak aparat czy geolokalizacja, zależy od uprawnień przyznanych przez użytkownika. Interfejs Permissions API umożliwia sprawdzenie stanu uprawnień dostępu do interfejsu API – czy przyznano je, odmówiono czy wymaga on jakiejś formy interakcji, np. kliknięcia komunikatu lub interakcji ze stroną.

Zapytanie o stan uprawnień możesz wysyłać za pomocą narzędzia navigator.permissions.query().

Aby sprawdzić uprawnienia dostępu do pamięci w bieżącym kontekście, musisz przekazać ciąg tekstowy 'storage-access':

navigator.permissions.query({name: 'storage-access'})

Aby sprawdzić uprawnienia dostępu do pamięci dla określonego źródła, musisz przekazać ciąg 'top-level-storage-access':

navigator.permissions.query({name: 'top-level-storage-access', requestedOrigin: 'https://target.site'})

Pamiętaj, że aby chronić integralność umieszczonego źródła, sprawdzane są tylko uprawnienia przyznane przez dokument najwyższego poziomu za pomocą metody document.requestStorageAccessFor.

W zależności od tego, czy uprawnienie można przyznać automatycznie, czy wymaga ono gestu użytkownika, funkcja zwróci wartość prompt lub granted.

Model na klatkę

Przyznane konta rSA są stosowane do każdej ramki. Uprawnienia rSA i rSAFor są traktowane jako osobne uprawnienia.

Każda nowa ramka będzie osobno prosić o dostęp do pamięci, a dostęp zostanie przyznany automatycznie. Tylko pierwsze żądanie wymaga gestu użytkownika. Kolejne żądania zainicjowane przez element iframe, takie jak nawigacja czy zasoby podrzędne, nie muszą czekać na gest użytkownika, ponieważ zostanie on przyznany podczas sesji przeglądania przez pierwsze żądanie.

Odświeżenie, ponowne załadowanie lub ponowne utworzenie elementu iframe będzie wymagało ponownego wysłania żądania dostępu.

Pliki cookie muszą określać atrybuty SameSite=None i Secure, ponieważ rSA zapewnia dostęp tylko do plików cookie, które są już oznaczone do użycia w kontekstach z różnych stron.

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 innych witryn, niezależnie od RSA.

Zabezpieczenia

W przypadku rSAFor żądania zasobów podrzędnych wymagają nagłówków współdzielenia zasobów między serwerami (CORS) lub atrybutu crossorigin zasobów, co zapewnia jednoznaczne zezwolenie.

Przykłady implementacji

Poproś o dostęp do pamięci z osadzonego międzyźródłowego elementu iframe

Diagram przedstawiający umieszczoną witrynę w domenie najwyższego poziomu.
Użycie tagu requestStorageAccess() w umieszczonej witrynie w innej witrynie.

Sprawdzanie, czy masz dostęp do pamięci

Aby sprawdzić, czy masz już dostęp do pamięci, użyj document.hasStorageAccess().

Jeśli obiecuje to prawdziwa, dostęp do pamięci masowej możesz uzyskać w kontekście innych witryn. Jeśli wartość parametru to „false”, musisz poprosić o dostęp do pamięci.

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 chcesz poprosić o dostęp do pamięci, najpierw sprawdź uprawnienie dostępu do pamięci navigator.permissions.query({name: 'storage-access'}), aby zobaczyć, czy wymaga to gestu użytkownika lub czy może zostać przyznane automatycznie.

Jeśli uprawnienie to granted, możesz wywołać metodę document.requestStorageAccess(). Powinno to zadziałać bez gestu użytkownika.

Jeśli stan uprawnień to prompt, musisz zainicjować wywołanie document.requestStorageAccess() po geście użytkownika, 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, elementów nawigacyjnych lub zasobów podrzędnych automatycznie uzyskają uprawnienia dostępu do plików cookie pochodzących z różnych stron. hasStorageAccess() zwraca pliki cookie „prawda”, a pliki cookie pochodzące z innych witryn z tego samego zestawu powiązanych witryn będą wysyłane w przypadku tych żądań bez żadnych dodatkowych wywołań JavaScript.

Diagram przedstawiający użycie funkcji requestStorageAccessFor() w witrynie najwyższego poziomu, a nie w umieszczonej witrynie
Używanie requestStorageAccessFor() w witrynie najwyższego poziomu dla innego źródła

Witryny najwyższego poziomu mogą używać requestStorageAccessFor(), aby prosić o dostęp do pamięci w imieniu określonych źródeł.

hasStorageAccess() sprawdza tylko, czy strona wywołująca ma dostęp do pamięci, więc witryna najwyższego poziomu może sprawdzać uprawnienia dla innego źródła.

Aby sprawdzić, czy użytkownik zostanie poproszony o zgodę, czy też do określonego źródła został już przyznany dostęp do pamięci, wywołaj navigator.permissions.query({name: 'top-level-storage-access', requestedOrigin: 'https://target.site'}).

Jeśli uprawnienie to granted, możesz wywołać document.requestStorageAccessFor('https://target.site'). Powinno zadziałać bez gestu użytkownika.

Jeśli uprawnienie to prompt, musisz przechwycić wywołanie document.requestStorageAccessFor('https://target.site') za gestem użytkownika, np. kliknięciem 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 udanym wywołaniu requestStorageAccessFor() żądania z innych witryn będą zawierać pliki cookie, jeśli będą zawierać atrybut CORS lub atrybut crossorigin, dlatego witryny mogą zaczekać, zanim uruchomią żądanie.

Żądania muszą korzystać z 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 przeprowadzać testy lokalne

Wymagania wstępne

Aby lokalnie przetestować zestawy powiązanych witryn, użyj przeglądarki Chrome 119 lub nowszej uruchamianej z poziomu wiersza poleceń i włącz flagę Chrome test-third-party-cookie-phaseout.

Włącz flagę Chrome

Aby włączyć niezbędną flagę Chrome, przejdź do chrome://flags#test-third-party-cookie-phaseout na pasku adresu i zmień flagę na Enabled. Pamiętaj, aby ponownie uruchomić przeglądarkę po zmianie flag.

Aby uruchomić Chrome z lokalnie zadeklarowanym zestawem powiązanych witryn, utwórz obiekt JSON zawierający adresy URL, które należą do 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 wiersza poleceń z flagą --use-related-website-set i obiektem JSON zawierającym adresy URL należące do 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/

Sprawdzanie, czy masz dostęp do plików cookie w różnych witrynach

Wywołaj interfejsy API (rSA lub rSAFor) z testowanych witryn i zweryfikuj dostęp do plików cookie w różnych witrynach.

Aby zadeklarować relację między domenami i określić, do którego podzbioru należą, wykonaj te czynności:

  1. Zidentyfikuj odpowiednie domeny – w tym ustaw elementy podstawowe i elementy zestawu, które będą częścią zestawu powiązanych witryn. Określ też typ podzbioru, do którego należy każdy element zestawu.
  2. Upewnij się, że zostały spełnione wymagania dotyczące utworzenia konta i wymagania weryfikacji.
  3. Zadeklaruj zestaw powiązanych witryn w prawidłowym formacie JSON.
  4. Prześlij zestaw powiązanych witryn, tworząc żądanie pobierania (PR) do elementu related_website_sets.JSON, w którym Chrome będzie przechowywać listę kanonicznych zestawów witryn. Do utworzenia raportów PR wymagane jest konto GitHub. Aby dodawać treści do listy, musisz podpisać Umowę licencyjną dla współtwórców (CLA).

Po utworzeniu PR przeprowadzimy serię testów, aby sprawdzić, czy wymagania określone w kroku 2 są spełnione.

Jeśli weryfikacja zakończy się pomyślnie, PR będzie zawierać informację o przejściu weryfikacji. Zatwierdzone informacje o stronach będą ręcznie scalone partiami z listą kanonicznych powiązanych witryn raz w tygodniu (we wtorki o 12:00 czasu wschodniego).

Jeśli cokolwiek z testów nie powiedzie się, osoba przesyłająca zostanie o tym powiadomiona w wiadomości PR na GitHubie. Osoba zgłaszająca może poprawić błędy i zaktualizować PR. Pamiętaj, że:

  • Jeśli PR się nie powiedzie, pojawi się komunikat o błędzie zawierający dodatkowe informacje o przyczynie niepowodzenia przesyłania (przykład).
  • Wszystkie kontrole techniczne dotyczące przesyłania zestawów są przeprowadzane na GitHubie, dzięki czemu wszystkie błędy przesyłania wynikające z kontroli technicznej są dostępne w GitHubie.

Zasady firmowe

Aby zaspokoić potrzeby użytkowników biznesowych, Chrome wdrożył kilka zasad korporacyjnych:

  • Za pomocą zasady RelatedWebsiteSetsEnabled systemy, które mogą nie być w stanie przeprowadzić integracji z zestawami powiązanych witryn, mogą wyłączyć funkcję zestawów powiązanych witryn we wszystkich instancjach Chrome dla przedsiębiorstw.
  • Niektóre systemy przedsiębiorstwa mają witryny tylko wewnętrzne (takie jak intranet) z domenami, które można zarejestrować, różniącymi się od domen w zestawie powiązanych witryn. Jeśli chce traktować te witryny jako część zestawu powiązanych witryn bez ujawniania ich publicznie (ponieważ domeny mogą być poufne), może rozszerzyć lub zastąpić listę publicznych zestawów powiązanych witryn za pomocą zasad RelatedWebsiteSetsOverrides.

„Prompt użytkownika” i „Gest użytkownika”

„Prompt użytkownika” i „Gest użytkownika” to co innego. Chrome nie będzie wyświetlać użytkownikom prośby o przyznanie uprawnień w przypadku witryn należących do tego samego zestawu powiązanych witryn, ale Chrome będzie nadal wymagać od użytkownika interakcji ze stroną. Przed przyznaniem uprawnień Chrome wymaga gestu użytkownika, nazywanego też „interakcją użytkownika” lub „aktywacją użytkownika”. Dzieje się tak, ponieważ ze względu na zasady projektowania platformy internetowej korzystanie z interfejsu Storage Access API poza kontekstem zestawu powiązanych witryn (tj. requestStorageAccess()) wymaga też gestu użytkownika.

Dostęp do plików cookie i pamięci innych witryn

Zestawy powiązanych witryn nie scalają miejsca na dane z różnych witryn, a tylko umożliwiają wygodniejsze (bez promptów) wykonywanie wywołań requestStorageAccess(). Zestawy powiązanych witryn tylko upraszczają korzystanie z interfejsu Storage Access API, ale nie określają, co zrobić po przywróceniu dostępu. Jeśli witryny A i B są różnymi witrynami w tym samym zbiorze powiązanych witryn, a elementy umieszczone A B to obiekty umieszczone w witrynie B, może ona wywołać requestStorageAccess() i uzyskać dostęp do własnej pamięci bez pytania użytkownika. Zestawy powiązanych witryn nie obsługują komunikacji między witrynami. Na przykład skonfigurowanie zestawu powiązanych witryn nie spowoduje, że pliki cookie należące do grupy B będą wysyłane do domeny A. Jeśli chcesz udostępnić te dane, musisz to zrobić samodzielnie, np. wysyłając element window.postMessage z elementu iframe B do ramki A.

Zestawy powiązanych witryn nie zezwalają na niejawny dostęp do plików cookie bez partycjonowania bez wywołania żadnego interfejsu API. Pliki cookie pochodzące z różnych witryn nie są dostępne domyślnie w ramach zestawu. Zestawy powiązanych witryn zezwalają tylko witrynom z zestawu na pomijanie prośby o uprawnienia do interfejsu Storage Access API. Element iframe musi wywołać funkcję document.requestStorageAccess(), jeśli chce uzyskać dostęp do swoich plików cookie, lub strona najwyższego poziomu może wywołać metodę document.requestStorageAccessFor().

Podziel się opinią

Przesłanie zestawu na GitHubie oraz praca z interfejsami Storage Access API i requestStorageAccessFor API to okazja do podzielenia się doświadczeniami związanymi z tym procesem i wszelkimi napotkanymi problemami.

Aby dołączyć do dyskusji na temat zestawów powiązanych witryn: