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

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

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

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을 새로고침, 새로고침 또는 다시 만들면 액세스 권한을 다시 요청해야 합니다.

쿠키 요구사항

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

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

보안

rSAFor의 경우 하위 리소스 요청에 CORS (Cross-Origin Resource Sharing) 헤더 또는 리소스에 대한 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 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 및 크로스 사이트 쿠키를 반환하며, 이러한 요청은 추가 자바스크립트 호출 없이 해당 요청에 전송됩니다.

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

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 또는 교차 출처 속성이 포함된 경우 크로스 사이트 요청에 쿠키가 포함되므로 사이트에서 요청을 트리거하기 전에 기다리는 것이 좋습니다.

요청은 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를 사용 설정하고 명령줄에서 --use-related-website-set 플래그와 함께 Chrome을 실행하고 세트의 멤버인 URL이 포함된 JSON 객체를 사용해야 합니다.

--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 정책에 따라 공개 관련 웹사이트 세트 목록을 늘리거나 재정의할 수 있습니다.

의견 공유

GitHub에 세트를 제출하고 Storage Access API와 requestStorageAccessFor API를 사용해 작업 경험과 겪는 문제를 공유해 보세요.

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

관련 웹사이트 세트 공개 메일링 리스트에 참여하세요.
문제를 제기하고 관련 웹사이트 세트 GitHub 저장소의 토론을 팔로우합니다.