이 페이지는 Cloud Translation API를 통해 번역되었습니다.

관련 웹사이트 세트: 개발자 가이드

관련 웹사이트 세트 (RWS)는 브라우저가 도메인 모음 간의 관계를 이해하는 데 도움을 주는 웹 플랫폼 메커니즘입니다. 이를 통해 브라우저는 특정 사이트 기능 (예: 크로스 사이트 쿠키에 대한 액세스 허용 여부)을 사용 설정하고 이 정보를 사용자에게 표시하기 위해 중요한 결정을 내릴 수 있습니다.

Chrome에서 서드 파티 쿠키에 대한 지원을 중단함에 따라 Chrome의 목표는 웹에서 주요 사용 사례를 유지하면서 사용자의 개인 정보 보호를 개선하는 것입니다. 예를 들어 단일 사용자 환경을 제공하기 위해 여러 도메인을 사용하는 사이트가 많습니다. 조직은 이미지나 동영상을 호스팅하는 국가별 도메인 또는 서비스 도메인과 같은 여러 사용 사례를 위해 서로 다른 최상위 도메인을 유지 관리하기를 원할 수 있습니다. 관련 웹사이트 세트를 사용하면 사이트에서 특정 관리 기능을 통해 도메인 간에 데이터를 공유할 수 있습니다.

관련 웹사이트 세트 통합 세부정보

Storage Access API

브라우저 지원

119
85
65
11.1

소스

Storage Access API (SAA)는 삽입된 교차 출처 콘텐츠가 일반적으로 퍼스트 파티 맥락에서만 액세스할 수 있는 저장소에 액세스할 수 있는 방법을 제공합니다.

삽입된 리소스는 SAA 메서드를 사용하여 현재 저장소에 액세스할 수 있는지 확인하고 사용자 에이전트에 액세스 권한을 요청할 수 있습니다.

서드 파티 쿠키가 차단되었지만 관련 웹사이트 세트 (RWS)가 사용 설정된 경우 Chrome은 RWS 내 컨텍스트에서 자동으로 권한을 부여하며 그 외의 경우에는 사용자에게 메시지를 표시합니다. ('RWS 내 컨텍스트'는 삽입된 사이트와 최상위 사이트가 동일한 RWS에 있는 iframe과 같은 컨텍스트입니다.)

스토리지 액세스 확인 및 요청

삽입된 사이트는 현재 저장소에 액세스할 수 있는지 확인하기 위해 Document.hasStorageAccess() 메서드를 사용할 수 있습니다.

이 메서드는 문서가 이미 쿠키에 액세스할 수 있는지 여부를 나타내는 불리언 값으로 확인되는 프로미스를 반환합니다. iframe의 출처가 상단 프레임과 동일한 경우에도 프라미스가 true를 반환합니다.

크로스 사이트 컨텍스트로 삽입된 사이트에서 쿠키에 대한 액세스를 요청하려면 Document.requestStorageAccess() (rSA)를 사용하면 됩니다.

requestStorageAccess() API는 iframe 내에서 호출되어야 합니다. 이 iframe은 방금 사용자 상호작용 (모든 브라우저에 필요한 사용자 동작)을 수신했어야 하지만 Chrome에서는 추가로 지난 30일 중 특정 시점에 사용자가 iframe을 소유한 사이트를 방문하고 iframe이 아닌 최상위 문서로 해당 사이트와 상호작용하도록 요구합니다.

requestStorageAccess()는 저장소에 대한 액세스 권한이 부여되었는지 확인하는 프로미스를 반환합니다. 어떤 이유로든 액세스가 거부된 경우 그 이유를 근거로 프로미스가 거부됩니다.

Chrome의 requestStorageAccessFor

브라우저 지원

소스

Storage Access API는 삽입된 사이트에서 사용자 상호작용을 수신한 <iframe> 요소 내에서만 저장소에 대한 액세스를 요청할 수 있도록 허용합니다.

따라서 쿠키가 필요한 크로스 사이트 이미지 또는 스크립트 태그를 사용하는 최상위 사이트에 Storage Access API를 채택하는 데 어려움이 있습니다.

이 문제를 해결하기 위해 Chrome에서는 최상위 사이트가 Document.requestStorageAccessFor() (rSAFor)를 사용하여 특정 출처를 대신하여 스토리지 액세스를 요청하는 방법을 구현했습니다.

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

requestStorageAccessFor() API는 최상위 문서에서 호출해야 합니다. 해당 문서도 방금 사용자 상호작용을 수신해야 합니다. 하지만 requestStorageAccess()와 달리 Chrome은 사용자가 이미 페이지에 있기 때문에 지난 30일 동안 최상위 문서에서 상호작용을 확인하지 않습니다.

저장소 액세스 권한 확인

카메라 또는 위치정보와 같은 일부 브라우저 기능에 대한 액세스는 사용자가 부여한 권한을 기반으로 합니다. Permissions API는 API 액세스를 위한 권한 상태(권한이 부여되었는지, 거부되었는지, 프롬프트 클릭, 페이지와 상호작용 등)를 요구하는지 확인하는 방법을 제공합니다.

navigator.permissions.query()를 사용하여 권한 상태를 쿼리할 수 있습니다.

현재 컨텍스트의 저장소 액세스 권한을 확인하려면 'storage-access' 문자열을 전달해야 합니다.

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

지정된 출처의 저장소 액세스 권한을 확인하려면 'top-level-storage-access' 문자열을 전달해야 합니다.

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

삽입된 출처의 무결성을 보호하기 위해 이 검사에서는 document.requestStorageAccessFor를 사용하여 최상위 문서에서 부여한 권한만 확인합니다.

권한을 자동으로 부여할 수 있는지 또는 사용자 동작이 필요한지에 따라 prompt 또는 granted를 반환합니다.

프레임별 모델

rSA 승인은 프레임당 적용됩니다. rSA 및 rSAFor 부여는 별도의 권한으로 취급됩니다.

새로운 프레임마다 개별적으로 저장소 액세스 권한을 요청해야 하며 액세스 권한이 자동으로 부여됩니다. 첫 번째 요청만 사용자 동작이 필요하며, iframe에서 시작된 탐색 또는 하위 리소스와 같은 후속 요청은 초기 요청에 의해 탐색 세션에 부여되므로 사용자 동작을 기다릴 필요가 없습니다.

새로고침, 새로고침 또는 iframe을 다시 만들려면 액세스 권한을 다시 요청해야 합니다.

쿠키 요구사항

쿠키는 SameSite=None 속성과 Secure 속성을 모두 지정해야 합니다. rSA는 크로스 사이트 컨텍스트에서 사용하도록 이미 표시된 쿠키에 대한 액세스만 제공하기 때문입니다.

SameSite=Lax, SameSite=Strict 또는 SameSite 속성이 없거나 없는 쿠키는 퍼스트 파티 전용이며 rSA와 관계없이 크로스 사이트 컨텍스트에서 공유되지 않습니다.

보안

rSAFor의 경우 하위 리소스 요청에는 교차 출처 리소스 공유 (CORS) 헤더 또는 리소스에 대한 crossorigin 속성이 필요하므로 명시적인 선택이 보장됩니다.

구현 예

삽입된 교차 출처 iframe에서 저장소에 대한 액세스 요청

최상위 수준 사이트에 삽입된 사이트를 보여주는 다이어그램 — 다른 사이트의 삽입에 `requestStorageAccess()` 사용

스토리지 액세스 권한이 있는지 확인하기

스토리지 액세스 권한이 이미 있는지 확인하려면 document.hasStorageAccess()을(를) 사용하세요.

프로미스가 true로 결정되면 크로스 사이트 컨텍스트에서 스토리지에 액세스할 수 있습니다. false로 확인되면 스토리지 액세스를 요청해야 합니다.

document.hasStorageAccess().then((hasAccess) => {
    if (hasAccess) {
      // You can access storage in this context
    } else {
      // You have to request storage access
    }
});

스토리지 액세스 요청

저장소 액세스를 요청해야 하는 경우 먼저 저장소 액세스 권한 navigator.permissions.query({name: 'storage-access'})에서 사용자 동작이 필요한지 아니면 자동으로 부여될 수 있는지 확인하세요.

권한이 granted이면 document.requestStorageAccess()를 호출할 수 있으며 사용자 동작 없이 성공해야 합니다.

권한 상태가 prompt이면 버튼 클릭과 같은 사용자 동작 후에 document.requestStorageAccess() 호출을 시작해야 합니다.

참고: 권한이 부여되거나 사용자 동작이 등록되기 전에 requestStorageAccess()를 호출하려고 하면 'requestStorageAccess: Must to be handling a user action to use' 오류가 발생합니다.

예:

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
      }
    );
  }
}

프레임, 탐색 또는 하위 리소스 내에서 발생하는 후속 요청은 크로스 사이트 쿠키 액세스 권한을 자동으로 갖게 됩니다. hasStorageAccess()는 true를 반환하고 동일한 관련 웹사이트 세트의 크로스 사이트 쿠키를 반환하며, 추가 JavaScript 호출 없이 이러한 요청에 함께 전송됩니다.

교차 출처 사이트를 대신하여 쿠키 액세스를 요청하는 최상위 사이트

requestStorageAccessFor()가 삽입된 사이트 내가 아닌 최상위 사이트에서 사용 중인 모습을 보여주는 다이어그램 — 다른 출처의 최상위 사이트에서 `requestStorageAccessFor()` 사용

최상위 사이트는 requestStorageAccessFor()를 사용하여 특정 출처 대신 스토리지 액세스를 요청할 수 있습니다.

hasStorageAccess()는 이를 호출하는 사이트에 스토리지 액세스 권한이 있는지만 확인하므로 최상위 사이트는 다른 출처의 권한을 확인할 수 있습니다.

사용자에게 메시지가 표시되는지 또는 지정된 출처에 이미 스토리지 액세스 권한이 부여되었는지 알아보려면 navigator.permissions.query({name: 'top-level-storage-access', requestedOrigin: 'https://target.site'})를 호출합니다.

권한이 granted이면 document.requestStorageAccessFor('https://target.site')를 호출할 수 있습니다. 사용자 동작 없이도 성공해야 합니다.

권한이 prompt이면 버튼 클릭과 같은 사용자 동작 뒤에 document.requestStorageAccessFor('https://target.site') 호출을 연결해야 합니다.

예:

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
      }
    );
  }
}

requestStorageAccessFor() 호출이 성공하면 크로스 사이트 요청에 CORS 또는 crossorigin 속성이 포함된 경우 쿠키가 포함되므로 사이트에서는 요청을 트리거하기 전에 기다리는 것이 좋습니다.

요청은 credentials: 'include' 옵션을 사용해야 하며 리소스는 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
      });
  }

로컬에서 테스트하는 방법

기본 요건

관련 웹사이트 세트를 로컬에서 테스트하려면 명령줄에서 실행된 Chrome 119 이상을 사용하고 test-third-party-cookie-phaseout Chrome 플래그를 사용 설정합니다.

Chrome 신고 사용 설정

필요한 Chrome 플래그를 사용 설정하려면 주소 표시줄에서 chrome://flags#test-third-party-cookie-phaseout로 이동하여 플래그를 Enabled로 변경합니다. 플래그가 변경된 후 브라우저를 다시 시작해야 합니다.

로컬 관련 웹사이트 세트가 포함된 Chrome을 실행합니다.

로컬에서 선언된 관련 웹사이트 세트로 Chrome을 실행하려면 세트의 구성원인 URL이 포함된 JSON 객체를 만들어 --use-related-website-set에 전달합니다.

플래그를 사용하여 Chromium을 실행하는 방법을 자세히 알아보세요.

--use-related-website-set="{\"primary\": \"https://related-website-sets.glitch.me\", \"associatedSites\": [\"https://rws-member-1.glitch.me\"]}" \
https://related-website-sets.glitch.me/

예

관련 웹사이트 세트를 로컬에서 사용 설정하려면 chrome://flags에서 test-third-party-cookie-phaseout를 사용 설정하고 집합에 속한 URL이 포함된 JSON 객체와 함께 --use-related-website-set 플래그를 사용하여 명령줄에서 Chrome을 실행해야 합니다.

--use-related-website-set="{\"primary\": \"https://related-website-sets.glitch.me\", \"associatedSites\": [\"https://rws-member-1.glitch.me\"]}" \
https://related-website-sets.glitch.me/

크로스 사이트 쿠키에 액세스할 수 있는지 확인하기

테스트 중인 사이트에서 API (rSA 또는 rSAFor)를 호출하고 크로스 사이트 쿠키에 대한 액세스를 검증합니다.

엔터프라이즈 정책

Chrome에는 기업 사용자의 요구사항을 충족하기 위해 두 가지 정책이 있습니다.

관련 웹사이트 세트와 통합하지 못할 수도 있는 시스템에서는 RelatedWebsiteSetsEnabled 정책에 따라 Chrome의 모든 엔터프라이즈 인스턴스에서 관련 웹사이트 세트 기능을 사용 중지할 수 있습니다.
일부 엔터프라이즈 시스템에는 관련 웹사이트 세트의 도메인과 다른 등록 가능한 도메인을 가진 내부 전용 사이트 (예: 인트라넷)가 있습니다. 도메인이 기밀일 수 있으므로 이러한 사이트를 공개적으로 노출하지 않고 관련 웹사이트 세트의 일부로 처리해야 하는 경우 RelatedWebsiteSetsOverrides 정책을 사용하여 공개된 관련 웹사이트 세트 목록을 보완하거나 재정의할 수 있습니다.

Chrome은 공개 세트와 엔터프라이즈 세트의 교차점을 둘 중 하나로 해결합니다. replacemements 또는 additions가 지정되었는지 여부에 따라 다른 방식으로 계산됩니다.

예를 들어 공개 집합 {primary: A, associated: [B, C]}의 경우 다음과 같습니다.


`replacements`세트 종료:	`{primary: C, associated: [D, E]}`
엔터프라이즈 세트가 공통 사이트를 흡수하여 새로운 세트를 구성합니다.
결과 집합:	`{primary: A, associated: [B]}` `{primary: C, associated: [D, E]}`

`additions`세트 종료:	`{primary: C, associated: [D, E]}`
공개 및 엔터프라이즈 세트가 결합됩니다.
결과 집합:	`{primary: C, associated: [A, B, D, E]}`

의견 공유

GitHub에 세트를 제출하고 Storage Access API 및 requestStorageAccessFor API를 사용하면 프로세스 및 발생한 문제에 관한 경험을 공유할 수 있습니다.

관련 웹사이트 세트에 관한 토론에 참여하려면 다음 단계를 따르세요.

관련 웹사이트 세트 공개 메일링 리스트에 가입합니다.
문제를 제기하고 관련 웹사이트 세트 GitHub 저장소에서 토론을 따릅니다.