Set Situs Terkait: panduan developer

Pembaruan: Set Pihak Pertama telah diganti namanya menjadi Set Situs Terkait. Untuk mempelajari perubahan nama lebih lanjut, lihat postingan blog.

Set Situs Terkait (RWS) adalah mekanisme platform web yang membantu browser memahami hubungan di antara kumpulan domain. Hal ini memungkinkan browser membuat keputusan penting untuk mengaktifkan fungsi situs tertentu (seperti apakah akan mengizinkan akses ke cookie lintas situs) dan untuk menyajikan informasi ini kepada pengguna.

Karena Chrome menghentikan penggunaan cookie pihak ketiga, sasarannya adalah mempertahankan kasus penggunaan utama di web sekaligus meningkatkan privasi bagi pengguna. Misalnya, banyak situs mengandalkan beberapa domain untuk menyajikan satu pengalaman pengguna. Organisasi mungkin ingin mempertahankan domain level teratas yang berbeda untuk beberapa kasus penggunaan seperti domain layanan khusus negara atau domain layanan untuk menghosting gambar atau video. Set Situs Terkait memungkinkan situs berbagi data di seluruh domain, dengan kontrol spesifik.

Apa itu Set Situs Terkait?

Pada tingkat tinggi, Set Situs Terkait adalah kumpulan domain, yang memiliki satu "kumpulan utama" dan kemungkinan beberapa "anggota kumpulan".

Dalam contoh berikut, primary mencantumkan domain primer, dan associatedSites mencantumkan domain yang memenuhi persyaratan subset terkait.

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

Daftar Set Situs Terkait kanonis adalah daftar yang dapat dilihat secara publik dalam format file JSON yang dihosting di repositori GitHub Set Situs Terkait, yang berfungsi sebagai sumber kebenaran untuk semua set. Chrome menggunakan file ini untuk diterapkan ke perilakunya.

Hanya pengguna yang memiliki kontrol administratif atas domain yang dapat membuat kumpulan dengan domain tersebut. Pengirim harus menyatakan hubungan antara setiap "anggota kumpulan" dengan "kumpulan utama". Anggota kumpulan dapat mencakup berbagai jenis domain yang berbeda dan harus menjadi bagian dari subkumpulan berdasarkan kasus penggunaan.

Jika aplikasi Anda bergantung pada akses ke cookie lintas situs (juga disebut cookie pihak ketiga) di seluruh situs dalam Set Situs Terkait yang sama, Anda dapat menggunakan Storage Access API (SAA) dan requestStorageAccessFor API untuk meminta akses ke cookie tersebut. Bergantung pada subset di setiap situs, browser dapat menangani permintaan secara berbeda.

Untuk mempelajari lebih lanjut proses dan persyaratan mengirimkan set, lihat panduan pengiriman. Set yang dikirimkan akan melalui berbagai pemeriksaan teknis untuk memvalidasi kiriman tersebut.

Kasus penggunaan Set Situs terkait

Set Situs Terkait sangat cocok untuk kasus saat organisasi memerlukan bentuk identitas bersama di berbagai situs tingkat atas.

Beberapa kasus penggunaan Set Situs Terkait adalah:

• Penyesuaian negara. Memanfaatkan situs yang dilokalkan sambil mengandalkan infrastruktur bersama (example.co.uk dapat mengandalkan layanan yang dihosting oleh example.ca).
• Integrasi domain layanan. Memanfaatkan domain layanan yang tidak pernah berinteraksi langsung dengan pengguna, tetapi menyediakan layanan di seluruh situs organisasi yang sama (example-cdn.com).
• Pemisahan konten pengguna. Mengakses data di domain berbeda yang memisahkan konten yang diupload pengguna dari konten situs lain untuk alasan keamanan, sekaligus mengizinkan akses domain dalam sandbox ke cookie autentikasi (dan lainnya). Jika menayangkan konten tidak aktif yang diupload pengguna, Anda mungkin dapat menghostingnya dengan aman di domain yang sama dengan mengikuti praktik terbaik.
• Konten terautentikasi yang disematkan. Mendukung konten tersemat dari seluruh properti terafiliasi (video, dokumen, atau resource yang dibatasi untuk pengguna yang login di situs tingkat atas).
• Login. Mendukung login di seluruh properti terafiliasi. FedCM API mungkin juga sesuai untuk beberapa kasus penggunaan.
• Analisis. Men-deploy analisis dan pengukuran perjalanan pengguna di seluruh properti terafiliasi untuk meningkatkan kualitas layanan.

Detail integrasi Set Situs terkait

Storage Access API

Dukungan Browser

• 119
• 85
• 65
• 11.1

Sumber

Storage Access API (SAA) menyediakan cara bagi konten lintas origin tersemat untuk mengakses penyimpanan yang biasanya hanya dapat diakses dalam konteks pihak pertama.

Resource tersemat dapat menggunakan metode SAA untuk memeriksa apakah resource tersebut saat ini memiliki akses ke penyimpanan, dan untuk meminta akses dari agen pengguna.

Saat cookie pihak ketiga diblokir, tetapi Set Situs Terkait (RWS) diaktifkan, Chrome akan otomatis memberikan izin dalam konteks intra-RWS, dan akan menampilkan perintah kepada pengguna jika tidak. ("Konteks intra-RWS" adalah konteks, seperti iframe, yang situs tersematnya dan situs tingkat atas berada dalam RWS yang sama.)

Catatan: SAA dikirimkan di beberapa browser, tetapi ada perbedaan di antara implementasi browser dalam aturan penanganan akses penyimpanan.

Memeriksa dan meminta akses penyimpanan

Untuk memeriksa apakah situs saat ini memiliki akses ke penyimpanan, situs yang disematkan dapat menggunakan metode Document.hasStorageAccess().

Metode ini menampilkan promise yang di-resolve dengan nilai boolean yang menunjukkan apakah dokumen sudah memiliki akses ke cookie-nya atau tidak. Promise juga menampilkan true (benar) jika iframe memiliki origin yang sama dengan frame atas.

Untuk meminta akses ke cookie di situs sematan konteks lintas situs dapat menggunakan Document.requestStorageAccess() (rSA).

requestStorageAccess() API ditujukan untuk dipanggil dari dalam iframe. Iframe tersebut baru saja menerima interaksi pengguna (gestur pengguna, yang diperlukan oleh semua browser), tetapi Chrome juga mewajibkan bahwa pada beberapa waktu dalam 30 hari terakhir, pengguna telah mengunjungi situs yang memiliki iframe tersebut dan telah berinteraksi dengan situs tersebut secara spesifik—sebagai dokumen tingkat atas, bukan dalam iframe.

requestStorageAccess() menampilkan promise yang di-resolve jika akses ke penyimpanan diberikan. Promise ditolak, dengan alasan, jika akses ditolak karena alasan apa pun.

requestStorageAccessFor di Chrome

Dukungan Browser

• 119
• 119
• x
• x

Sumber

Storage Access API hanya mengizinkan situs tersemat untuk meminta akses ke penyimpanan dari dalam elemen <iframe> yang telah menerima interaksi pengguna.

Hal ini menimbulkan tantangan dalam mengadopsi Storage Access API untuk situs tingkat atas yang menggunakan gambar lintas situs atau tag skrip yang memerlukan cookie.

Untuk mengatasinya, Chrome telah menerapkan cara bagi situs tingkat atas untuk meminta akses penyimpanan atas nama origin tertentu dengan Document.requestStorageAccessFor() (rSAFor).

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

requestStorageAccessFor() API dimaksudkan untuk dipanggil oleh dokumen level atas. Dokumen tersebut juga harus baru saja menerima interaksi pengguna. Namun, tidak seperti requestStorageAccess(), Chrome tidak memeriksa interaksi di dokumen tingkat teratas dalam 30 hari terakhir karena pengguna sudah ada di halaman.

Memeriksa izin akses penyimpanan

Akses ke beberapa fitur browser, seperti kamera atau geolokasi, didasarkan pada izin yang diberikan pengguna. Permissions API menyediakan cara untuk memeriksa status izin untuk mengakses API, baik telah diberikan, ditolak, atau memerlukan beberapa bentuk interaksi pengguna, seperti mengklik perintah atau berinteraksi dengan halaman.

Anda dapat mengkueri status izin menggunakan navigator.permissions.query().

Guna memeriksa izin akses penyimpanan untuk konteks saat ini, Anda harus meneruskan string 'storage-access':

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

Guna memeriksa izin akses penyimpanan untuk origin yang ditentukan, Anda harus meneruskan string 'top-level-storage-access':

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

Perlu diketahui bahwa untuk melindungi integritas asal yang disematkan, tindakan ini hanya memeriksa izin yang diberikan oleh dokumen tingkat atas menggunakan document.requestStorageAccessFor.

Bergantung pada apakah izin dapat diberikan secara otomatis atau memerlukan gestur pengguna, izin akan menampilkan prompt atau granted.

Model per frame

Hibah rSA berlaku per frame. Hibah rSA dan rSAFor diperlakukan sebagai izin terpisah.

Setiap frame baru harus meminta akses penyimpanan satu per satu dan frame akan otomatis diberi akses. Hanya permintaan pertama yang memerlukan gestur pengguna, setiap permintaan berikutnya yang dimulai oleh iframe, seperti navigasi atau subresource tidak perlu menunggu gestur pengguna karena itu akan diberikan untuk sesi penjelajahan oleh permintaan awal.

Memuat ulang, memuat ulang, atau membuat ulang iframe akan memerlukan permintaan akses lagi.

Persyaratan cookie

Cookie harus menentukan atribut SameSite=None dan Secure karena rSA hanya memberikan akses untuk cookie yang sudah ditandai untuk digunakan dalam konteks lintas situs.

Cookie dengan SameSite=Lax, SameSite=Strict, atau tanpa atribut SameSite hanya untuk penggunaan pihak pertama dan tidak akan pernah dibagikan dalam konteks lintas situs, terlepas dari rSA.

Keamanan

Untuk rSAFor, permintaan subresource memerlukan header Cross-Origin Resource Sharing (CORS) atau atribut crossorigin pada resource, yang memastikan keikutsertaan eksplisit.

Contoh implementasi

Meminta akses ke penyimpanan dari iframe lintas origin yang disematkan

Menggunakan requestStorageAccess() dalam sematan di situs lain.

Memeriksa apakah Anda memiliki akses penyimpanan

Untuk memeriksa apakah Anda sudah memiliki akses penyimpanan, gunakan document.hasStorageAccess().

Jika promise menghasilkan true, Anda dapat mengakses penyimpanan dalam konteks lintas situs. Jika ditetapkan sebagai salah (false), Anda perlu meminta akses penyimpanan.

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

Meminta akses penyimpanan

Jika Anda perlu meminta akses penyimpanan, periksa terlebih dahulu izin akses penyimpanan navigator.permissions.query({name: 'storage-access'}) untuk melihat apakah izin tersebut memerlukan gestur pengguna atau dapat diberikan secara otomatis.

Jika izinnya adalah granted, Anda dapat memanggil document.requestStorageAccess() dan seharusnya berhasil tanpa gestur pengguna.

Jika status izin adalah prompt, Anda harus memulai panggilan document.requestStorageAccess() setelah gestur pengguna, seperti mengklik tombol.

Catatan: Jika Anda mencoba memanggil requestStorageAccess() sebelum izin diberikan atau gestur pengguna didaftarkan, error: "requestStorageAccess: Harus menangani gestur pengguna untuk digunakan".

Contoh:

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

Permintaan berikutnya dari dalam frame, navigasi, atau subresource, akan otomatis memiliki izin untuk mengakses cookie lintas situs. hasStorageAccess() menampilkan cookie lintas situs dan benar dari Set Situs Terkait yang sama akan dikirim pada permintaan tersebut tanpa panggilan JavaScript tambahan.

Situs tingkat teratas yang meminta akses cookie atas nama situs lintas origin

Menggunakan requestStorageAccessFor() di situs tingkat atas untuk origin yang berbeda

Situs tingkat atas dapat menggunakan requestStorageAccessFor() untuk meminta akses penyimpanan atas nama origin tertentu.

hasStorageAccess() hanya memeriksa apakah situs yang memanggilnya memiliki akses penyimpanan sehingga situs tingkat atas dapat memeriksa izin untuk origin lain.

Untuk mengetahui apakah pengguna akan diminta atau jika akses penyimpanan telah diberikan ke origin yang ditentukan, panggil navigator.permissions.query({name: 'top-level-storage-access', requestedOrigin: 'https://target.site'}).

Jika izinnya adalah granted, Anda dapat memanggil document.requestStorageAccessFor('https://target.site'). SDK akan berhasil tanpa gestur pengguna.

Jika izinnya adalah prompt, Anda harus menarik panggilan document.requestStorageAccessFor('https://target.site') di belakang gestur pengguna, seperti klik tombol.

Contoh:

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

Setelah panggilan requestStorageAccessFor() berhasil, permintaan lintas situs akan menyertakan cookie jika menyertakan CORS atau atribut crossorigin. Oleh karena itu, situs sebaiknya menunggu sebelum memicu permintaan.

Permintaan harus menggunakan opsi credentials: 'include' dan resource harus menyertakan atribut 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
      });
  }

Cara melakukan pengujian secara lokal

Prasyarat

Untuk menguji Set Situs Terkait secara lokal, gunakan Chrome 119 atau versi yang lebih baru yang diluncurkan dari command line dan aktifkan test-third-party-cookie-phaseout tanda Chrome.

Mengaktifkan tanda Chrome

Untuk mengaktifkan tanda Chrome yang diperlukan, buka chrome://flags#test-third-party-cookie-phaseout dari kolom URL dan ubah tanda menjadi Enabled. Pastikan untuk memulai ulang browser setelah tanda diubah.

Catatan: Dengan mengaktifkan tanda ini, setelan dari chrome://settings/cookies tidak dapat diganti. Untuk mengaktifkan kembali cookie pihak ketiga, luncurkan kembali Chrome dengan tanda dinonaktifkan.

Luncurkan Chrome dengan Set Situs Terkait lokal

Untuk meluncurkan Chrome dengan Set Situs Terkait yang dideklarasikan secara lokal, buat objek JSON yang berisi URL yang merupakan anggota kumpulan dan teruskan ke --use-related-website-set.

Pelajari lebih lanjut cara menjalankan Chromium dengan tanda.

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

Catatan: Saat menggunakan Chrome versi 121 dan yang lebih baru, Anda dapat melihat Set Situs Terkait yang diterapkan oleh browser dengan membuka chrome://system dan meluaskan bagian Set Situs Terkait.

Contoh

Catatan: Untuk melihat cara kerja demo Set Situs Terkait, buka https://related-website-sets.glitch.me/.

Untuk mengaktifkan Set Situs Terkait secara lokal, Anda harus mengaktifkan test-third-party-cookie-phaseout di chrome://flags dan meluncurkan Chrome dari command line dengan tanda --use-related-website-set dengan objek JSON yang berisi URL yang merupakan anggota kumpulan.

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

Memverifikasi bahwa Anda memiliki akses ke cookie lintas situs

Panggil API (rSA atau rSAFor) dari situs yang sedang diuji dan validasi akses ke cookie lintas situs.

Proses pengiriman Set Situs Terkait

Untuk mendeklarasikan hubungan antar-domain, dan menentukan subset domain, ikuti langkah-langkah berikut:

1. Identifikasi domain yang relevan, ini termasuk anggota kumpulan utama dan anggota kumpulan, yang akan menjadi bagian dari Set Situs Terkait. Identifikasi juga jenis subset dari setiap anggota kumpulan.
2. Pastikan persyaratan formasi yang ditetapkan dan tetapkan persyaratan validasi sudah diterapkan.
3. Deklarasikan Set Situs Terkait dalam format JSON yang benar.
4. Kirim Set Situs Terkait dengan membuat permintaan pull (PR) ke related_website_sets.JSON tempat Chrome akan menghosting daftar Set Situs Terkait kanonis. (Akun GitHub diperlukan untuk membuat PR, dan Anda harus menandatangani Perjanjian Lisensi Kontributor (CLA) untuk berkontribusi ke daftar.)

Catatan: objek associatedSet memungkinkan pengaitan hingga 5 domain ke domain utama. Jumlah domain yang dapat dikaitkan menggunakan serviceSet atau ccTLD tidak terbatas, selama domain tersebut sesuai dengan persyaratan.

Setelah PR dibuat, serangkaian pemeriksaan akan dilakukan untuk memvalidasi bahwa persyaratan dari langkah 2 telah diterapkan.

Catatan: Sebelum membuat siaran pers, Anda dapat menguji kiriman secara lokal untuk melihat apakah kiriman tersebut lulus pemeriksaan.

Jika berhasil, PR akan menunjukkan bahwa pemeriksaan telah lulus. PR yang disetujui akan digabungkan secara manual dalam beberapa kelompok ke daftar Set Situs Terkait kanonis sekali seminggu (Selasa pukul 12.00 Waktu Timur).

Jika ada pemeriksaan yang gagal, pengirim akan diberi tahu melalui kegagalan PR di GitHub. Pengirim dapat memperbaiki kesalahan dan memperbarui PR, dan perlu diingat bahwa:

• Jika PR gagal, pesan error akan memberikan informasi tambahan tentang alasan pengiriman gagal (contoh).
• Semua pemeriksaan teknis yang mengatur pengiriman set dilakukan di GitHub, dan oleh karena itu semua kegagalan pengiriman yang dihasilkan dari pemeriksaan teknis akan dapat dilihat di GitHub.

Kebijakan perusahaan

Untuk memenuhi kebutuhan pengguna versi bisnis, Chrome menerapkan beberapa kebijakan perusahaan:

• Sistem yang mungkin tidak dapat terintegrasi dengan Set Situs Terkait dapat menonaktifkan fitur Set Situs Terkait di semua instance Chrome Enterprise dengan kebijakan RelatedWebsiteSetsEnabled.
• Beberapa sistem perusahaan memiliki situs khusus internal (seperti intranet) dengan domain yang dapat didaftarkan yang berbeda dengan domain di Set Situs Terkaitnya. Jika perlu memperlakukan situs ini sebagai bagian dari Set Situs Terkait tanpa mengeksposnya secara publik (karena domain mungkin bersifat rahasia), mereka dapat menambah atau mengganti daftar Set Situs Terkait publik dengan kebijakan RelatedWebsiteSetsOverrides.

Memecahkan Masalah Set Situs Terkait

"Perintah pengguna" dan "gestur pengguna"

"Perintah pengguna" dan "gestur pengguna" adalah dua hal yang berbeda. Chrome tidak akan menampilkan permintaan izin kepada pengguna untuk situs yang ada di Set Situs Terkait yang sama, tetapi Chrome tetap mengharuskan pengguna untuk berinteraksi dengan halaman. Sebelum memberikan izin, Chrome memerlukan gestur pengguna, yang juga disebut "interaksi pengguna" atau "aktivasi pengguna". Hal ini karena penggunaan Storage Access API di luar konteks Set Situs Terkait (yaitu requestStorageAccess()) juga memerlukan gestur pengguna, karena prinsip desain platform web.

Mengakses cookie atau penyimpanan situs lain

Set Situs Terkait tidak menggabungkan penyimpanan untuk situs yang berbeda: setelan ini hanya memungkinkan panggilan requestStorageAccess() yang lebih mudah (tanpa perintah). Set Situs Terkait hanya mengurangi hambatan pengguna dalam menggunakan Storage Access API, tetapi tidak menentukan tindakan yang harus dilakukan setelah akses dipulihkan. Jika A dan B adalah situs yang berbeda dalam Set Situs Terkait yang sama, dan A menyematkan B, B dapat memanggil requestStorageAccess() dan mendapatkan akses ke penyimpanan pihak pertama tanpa meminta pengguna. Set Situs Terkait tidak melakukan komunikasi lintas situs. Misalnya, menyiapkan Set Situs Terkait tidak akan menyebabkan cookie milik B mulai dikirim ke A. Jika ingin membagikan data tersebut, Anda harus membagikannya sendiri, misalnya dengan mengirim window.postMessage dari iframe B ke frame A.

Akses cookie tidak dipartisi secara default

Set Situs Terkait tidak mengizinkan akses cookie tanpa partisi implisit tanpa memanggil API apa pun. Cookie lintas situs tidak tersedia secara default dalam kumpulan; Set Situs Terkait hanya mengizinkan situs dalam kumpulan untuk melewati dialog izin Storage Access API. Suatu iframe harus memanggil document.requestStorageAccess() jika ingin mengakses cookie-nya, atau halaman tingkat atas dapat memanggil document.requestStorageAccessFor().

Berikan masukan

Anda dapat mengirimkan kumpulan di GitHub serta menggunakan Storage Access API dan requestStorageAccessFor API untuk membagikan pengalaman Anda terkait proses ini dan masalah apa pun yang Anda hadapi.

Untuk bergabung dalam diskusi tentang Set Situs Terkait:

• Bergabunglah ke milis publik Set Situs Terkait.
• Ajukan masalah dan ikuti diskusi tentang repo GitHub Set Situs Terkait.