İlgili Web Sitesi Grupları: geliştirici kılavuzu

İlgili Web Sitesi Grupları (RWS), tarayıcıların bir alan grubu arasındaki ilişkileri anlamasına yardımcı olan bir web platformu mekanizmasıdır. Böylece tarayıcılar, belirli site işlevlerini etkinleştirmek (örneğin, siteler arası çerezlere erişim izni verip vermemek) ve bu bilgileri kullanıcılara sunmak için temel kararlar verebilir.

Chrome, üçüncü taraf çerezlerini kullanımdan kaldırırken amacı web'deki temel kullanım alanlarını korurken kullanıcıların gizliliğini iyileştirmektir. Örneğin, birçok site tek bir kullanıcı deneyimi sunmak için birden fazla alan adından yararlanır. Kuruluşlar, ülkeye özgü alan adları ya da resim veya video barındırmak için hizmet alan adları gibi birden çok kullanım durumu için farklı üst düzey alan adları kullanmak isteyebilirler. İlişkili Websitesi Grupları, sitelerin belirli kontrollerle alanlar arasında veri paylaşmasına olanak tanır.

İlişkili Websitesi Grubu, genel anlamda tek bir "grup birincil grubu" ve potansiyel olarak birden fazla "grup üyesi"nin bulunduğu bir alan adları koleksiyonudur.

Aşağıdaki örnekte primary birincil alan adını, associatedSites ise ilişkili alt kümenin gereksinimlerini karşılayan alan adlarını listeler.

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

Standart İlişkili Websitesi Grupları listesi, İlgili Web Sitesi Grupları GitHub deposunda barındırılan ve tüm gruplar için bilgi kaynağı işlevi gören JSON dosyası biçiminde herkes tarafından görüntülenebilen bir listedir. Chrome, davranışına uygulamak için bu dosyayı kullanır.

Yalnızca bir alan üzerinde yönetici denetimi bulunan kullanıcılar söz konusu alanla grup oluşturabilir. Gönderenlerin, her "grup üyesi" ile "grup birincil" arasındaki ilişkiyi belirtmesi gerekir. Grup üyeleri, bir dizi farklı alan adı türünü içerebilir ve kullanım alanına göre bir alt kümenin parçası olmalıdır.

Uygulamanız, aynı İlişkili Websitesi Grubu'ndaki siteler arasında siteler arası çerezlere (üçüncü taraf çerezleri de denir) erişime dayanıyorsa bu çerezlere erişim isteğinde bulunmak için Storage Access API (SAA) ve requestStorageAccessFor API'sını kullanabilirsiniz. Her sitenin parçası olduğu alt kümeye bağlı olarak tarayıcı, isteği farklı bir şekilde işleyebilir.

Grupların gönderilmesiyle ilgili süreç ve gereksinimler hakkında daha fazla bilgi edinmek için gönderim yönergelerine göz atın. Gönderilen setler, gönderimlerin doğrulanması için çeşitli teknik kontrollerden geçer.

İlişkili Websitesi Grupları, kuruluşun farklı üst düzey sitelerde bir paylaşımlı kimliğe ihtiyaç duyduğu durumlar için uygundur.

İlişkili Websitesi Grupları için bazı kullanım alanları şunlardır:

  • Ülke özelleştirme. Paylaşılan altyapıdan yararlanırken yerelleştirilmiş sitelerden yararlanmak (example.co.uk için example.ca tarafından barındırılan bir hizmet kullanmak)
  • Hizmet alanı entegrasyonu. Kullanıcıların hiçbir zaman doğrudan etkileşimde bulunmadığı ancak aynı kuruluşun sitelerinde (example-cdn.com) hizmet sağladığı hizmet alanlarından yararlanma.
  • Kullanıcı içeriği ayrımı. Güvenlik nedeniyle kullanıcı tarafından yüklenen içeriği diğer site içeriğinden ayıran farklı alan adlarındaki verilere erişirken, korumalı alana alınan alan adının kimlik doğrulama (ve diğer) çerezlerine erişmesine izin verme. Kullanıcı tarafından yüklenen ve etkin olmayan içerikler sunuyorsanız en iyi uygulamaları izleyerek bu içeriği aynı alanda güvenli bir şekilde barındırabilirsiniz.
  • Kimliği doğrulanmış yerleştirilmiş içerik. İlişkili mülklerdeki yerleşik içerikleri destekleme (videolar, dokümanlar veya üst düzey sitede oturum açmış kullanıcıyla sınırlı kaynaklar).
  • Oturum açın. İlişkili mülklerde oturum açmayı destekleme. Bazı kullanım alanlarında FedCM API de uygun olabilir.
  • Analytics. Hizmetlerin kalitesini artırmak için ilişkili mülklerde kullanıcı yolculuklarına dair analizleri ve ölçümleri dağıtma.

Storage Access API

Tarayıcı Desteği

  • 119
  • 85
  • 65
  • 11.1

Kaynak

Storage Access API (SAA), yerleştirilmiş kaynaklar arası içeriklerin, normalde yalnızca birinci taraf bağlamında erişebileceği depolama alanına erişmesi için bir yol sunar.

Yerleştirilmiş kaynaklar, depolama alanına erişimlerinin olup olmadığını kontrol etmek ve kullanıcı aracısından erişim isteğinde bulunmak için SAA yöntemlerini kullanabilir.

Üçüncü taraf çerezleri engellendiğinde, İlişkili Websitesi Grupları (RWS) etkinleştirildiğinde Chrome, RWS içi bağlamlarda otomatik olarak izin verir, aksi takdirde kullanıcıya bir istem gösterir. ("RWS içi bağlam", yerleştirilmiş sitesi ve üst düzey sitesi aynı RWS'de bulunan iframe gibi bir bağlamdır.)

Depolama alanı erişimini kontrol etme ve isteme

Yerleşik siteler, şu anda depolama alanına erişimlerinin olup olmadığını kontrol etmek için Document.hasStorageAccess() yöntemini kullanabilir.

Yöntem, dokümanın çerezlerine halihazırda erişimi olup olmadığını belirten bir boole değeriyle çözümlenen bir söz döndürür. Vaat, iframe'in üst çerçeveyle aynı kaynak olması durumunda da true değerini döndürür.

Siteler arası bağlamda çerezlere erişim istemek için yerleştirilmiş siteler Document.requestStorageAccess()'i (rSA) kullanabilir.

requestStorageAccess() API'sinin bir iframe içinden çağrılması amaçlanmıştır. Bu iframe'in kısa süre önce kullanıcı etkileşimi (tüm tarayıcılar tarafından zorunlu kılınan bir kullanıcı hareketi) almış olması gerekir, ancak Chrome buna ek olarak son 30 gün içinde kullanıcının söz konusu iframe'in sahibi olan siteyi ziyaret etmiş ve özellikle bu siteyle etkileşimde bulunmuş olması gerekir (üst düzey doküman olarak değil, iframe'de değil).

requestStorageAccess(), depolama alanına erişim izni verilmişse kesinleşen bir söz döndürür. Erişim herhangi bir nedenle reddedildiyse söz konusu vaat reddedilir.

Chrome'da requestStorageAccessFor

Tarayıcı Desteği

  • 119
  • 119
  • x
  • x

Kaynak

Storage Access API yalnızca yerleştirilmiş sitelerin, kullanıcı etkileşimi alan <iframe> öğelerinin içinden depolamaya erişim isteğinde bulunmasına izin verir.

Bu durum, siteler arası görüntüler veya çerez gerektiren komut dosyası etiketleri kullanan üst düzey siteler için Storage Access API'yi benimsemede zorluklara yol açar.

Chrome bu sorunu gidermek amacıyla üst düzey sitelerin Document.requestStorageAccessFor() (rSAFor) ile belirli kaynaklar adına depolama alanı erişimi isteyebilmesi için bir yöntem uyguladı.

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

requestStorageAccessFor() API'nin, üst düzey bir belge tarafından çağrılması amaçlanmıştır. Bu dokümanın da kısa süre önce kullanıcı etkileşimi almış olması gerekir. Ancak requestStorageAccess()'in aksine Chrome, kullanıcı zaten sayfada bulunduğundan üst düzey dokümanlarda son 30 günde etkileşim olup olmadığını kontrol etmez.

Depolama alanı erişim izinlerini kontrol etme

Kamera veya coğrafi konum gibi bazı tarayıcı özelliklerine erişim, kullanıcı tarafından verilen izinlere bağlıdır. Permissions API, bir API'ye erişim için izin durumunu kontrol etmenin bir yolunu sunar. API'nin verilmiş, reddedilmiş veya bir bilgi istemini tıklamak ya da sayfayla etkileşimde bulunmak gibi bir tür kullanıcı etkileşimi gerektirip gerektirmediğini kontrol edebilirsiniz.

navigator.permissions.query() kullanarak izin durumunu sorgulayabilirsiniz.

Geçerli bağlam için depolama erişim iznini kontrol etmek üzere 'storage-access' dizesinde iletmeniz gerekir:

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

Belirli bir kaynağın depolama erişim iznini kontrol etmek için 'top-level-storage-access' dizesini iletmeniz gerekir:

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

Yerleştirilmiş kaynağın bütünlüğünü korumak için bu işlemin yalnızca document.requestStorageAccessFor kullanılarak üst düzey doküman tarafından verilen izinleri kontrol ettiğini unutmayın.

İznin otomatik olarak verilip verilemeyeceğine veya bir kullanıcı hareketi gerektirip gerektirmediğine bağlı olarak prompt veya granted değerini döndürür.

Çerçeve başına model

rSA izinleri çerçeve bazında geçerlidir. rSA ve rSAFor izinleri ayrı izinler olarak kabul edilir.

Her yeni çerçevenin ayrı ayrı depolama alanı erişimi istemesi gerekir ve bu çerçeveye otomatik olarak erişim izni verilir. Yalnızca ilk istek için kullanıcı hareketi gerekir. iFrame tarafından başlatılan gezinme veya alt kaynaklar gibi sonraki isteklerin, ilk istekle göz atma oturumu için verileceği kullanıcı hareketinin beklenmesine gerek yoktur.

iframe'i yenilemek, yeniden yüklemek veya başka bir şekilde yeniden oluşturmak, tekrar erişim isteğinde bulunmanızı gerektirir.

rSA olarak yalnızca siteler arası bağlamlarda kullanılmak üzere önceden işaretlenmiş çerezlere erişim sağlandığı için, çerezlerde hem SameSite=None hem de Secure özellikleri belirtilmelidir.

SameSite=Lax, SameSite=Strict veya SameSite özelliği olmayan çerezler yalnızca birinci taraf kullanımına yöneliktir ve rSA'dan bağımsız olarak siteler arası bağlamda hiçbir zaman paylaşılmaz.

Güvenlik

rSAFor için alt kaynak istekleri, kaynaklarda Ortamlar Arası Kaynak Paylaşımı (CORS) üst bilgilerini veya crossorigin özelliğini gerektirir. Böylece, açık bir şekilde katılım sağlanır.

Uygulama örnekleri

Yerleştirilmiş çapraz kaynak iframe'den depolama alanına erişim isteyin

Üst düzey bir.sitedeki yerleştirilmiş bir siteyi gösteren şema
Başka bir sitedeki yerleştirilmiş öğede requestStorageAccess() kullanma.

Depolama alanına erişiminiz olup olmadığını kontrol etme

Depolama alanına zaten erişiminiz olup olmadığını kontrol etmek için document.hasStorageAccess() ürününü kullanın.

Sözü yerine getirirseniz depolama alanına siteler arası bağlamda erişebilirsiniz. Bu politika "yanlış" olarak çözümlenirse depolama alanı erişimi istemeniz gerekir.

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

Depolama alanı erişimi iste

Depolama alanı erişimi istemeniz gerekiyorsa önce depolama erişimi iznini navigator.permissions.query({name: 'storage-access'}) kontrol ederek kullanıcı hareketi gerektirip gerektirmediğini veya bu izne otomatik olarak verilip verilmeyeceğini belirleyin.

İzin granted ise document.requestStorageAccess() yöntemini çağırabilirsiniz. İşlemin, kullanıcı hareketi olmadan başarılı olması gerekir.

İzin durumu prompt ise düğmeyi tıklama gibi bir kullanıcı hareketinden sonra document.requestStorageAccess() çağrısını başlatmanız gerekir.

Örnek:

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

Çerçeve, gezinmeler veya alt kaynaklardan gelen sonraki istekler otomatik olarak siteler arası çerezlere erişim iznine sahip olur. hasStorageAccess(), aynı İlişkili Websitesi Grubu'ndan gelen doğru ve siteler arası çerezleri döndürür. Bu çerezler, ek JavaScript çağrıları olmadan bu isteklerde gönderilir.

requestStorageAccessFor() öğesinin yerleştirilmiş bir sitede değil, üst düzey bir sitede kullanıldığını gösteren şema
requestStorageAccessFor() öğesini farklı bir kaynak için üst düzey bir sitede kullanma

Üst düzey siteler, belirli kaynaklar adına depolama erişimi istemek için requestStorageAccessFor() hizmetini kullanabilir.

hasStorageAccess() yalnızca çağıran sitenin depolama erişimi olup olmadığını kontrol eder. Böylece üst düzey bir site, başka bir kaynağın izinlerini kontrol edebilir.

Kullanıcıdan istenip istenmeyeceğini veya belirtilen kaynağa zaten depolama alanı erişimi verilip verilmediğini öğrenmek için navigator.permissions.query({name: 'top-level-storage-access', requestedOrigin: 'https://target.site'}) numaralı telefonu arayın.

İzin granted ise document.requestStorageAccessFor('https://target.site') işlevini çağırabilirsiniz. Kullanıcı hareketi olmadan başarılı olmalıdır.

İzin prompt ise document.requestStorageAccessFor('https://target.site') çağrısını düğmeyi tıklama gibi kullanıcı hareketinin arkasına bağlamanız gerekir.

Örnek:

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

Başarılı bir requestStorageAccessFor() çağrısından sonra, siteler arası istekler CORS veya çapraz kaynak özelliğini içeriyorsa çerezleri de içerir. Bu nedenle, siteler bir isteği tetiklemeden önce beklemek isteyebilir.

İsteklerde credentials: 'include' seçeneği kullanılmalı ve kaynaklar crossorigin="use-credentials" özelliğini içermelidir.

function checkCookie() {
    fetch('https://related-website-sets.glitch.me/getcookies.json', {
        method: 'GET',
        credentials: 'include'
      })
      .then((response) => response.json())
      .then((json) => {
      // Do something
      });
  }

Yerel olarak test etme

Ön koşullar

İlgili Web Sitesi Gruplarını yerel olarak test etmek için komut satırından başlatılan Chrome 119 veya sonraki bir sürümü kullanın ve test-third-party-cookie-phaseout Chrome işaretini etkinleştirin.

Chrome işaretini etkinleştir

Gerekli Chrome işaretini etkinleştirmek için adres çubuğundan chrome://flags#test-third-party-cookie-phaseout adresine gidin ve bayrağı Enabled olarak değiştirin. İşaretler değiştirildikten sonra tarayıcıyı yeniden başlatmayı unutmayın.

Chrome'u yerel olarak bildirilmiş İlgili Web Sitesi Grubu ile başlatmak için bir grubun üyesi olan URL'leri içeren bir JSON nesnesi oluşturup bunu --use-related-website-set öğesine iletin.

Chromium'u bayraklarla çalıştırma hakkında daha fazla bilgi edinin.

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

Örnek

İlgili Web Sitesi Gruplarını yerel olarak etkinleştirmek için chrome://flags ürününde test-third-party-cookie-phaseout özelliğini etkinleştirmeniz ve Chrome'u komut satırından --use-related-website-set işaretini kullanarak, grubun üyesi olan URL'leri içeren JSON nesnesiyle başlatmanız gerekir.

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

Siteler arası çerezlere erişiminiz olduğunu doğrulayın

Test edilen sitelerdeki API'leri (rSA veya rSAFor) çağırın ve siteler arası çerezlere erişimi doğrulayın.

Alanlar arasındaki ilişkiyi ve bunların hangi alt kümenin parçası olduklarını belirtmek için aşağıdaki adımları uygulayın:

  1. İlişkili Websitesi Grubu'nun parçası olacak grup birincil ve grup üyeleri de dahil olmak üzere ilgili alan adlarını belirleyin. Ayrıca her grup üyesinin hangi alt küme türüne ait olduğunu belirleyin.
  2. Ayar oluşturma şartlarının ve belirleme şartlarının yerine getirildiğinden emin olun.
  3. İlişkili Websitesi Grubu'nu doğru JSON biçiminde bildirin.
  4. Chrome'un standart İlişkili Websitesi Grubu listesini barındıracağı related_website_sets.JSON'a bir çekme isteği (PR) oluşturarak İlişkili Websitesi Grubu'nu gönderin. (PR'leri oluşturmak için bir GitHub hesabı gerekir ve listeye katkıda bulunmak için bir Katkıda Bulunan Lisans Sözleşmesi (CLA) imzalamanız gerekir.)

PR oluşturulduktan sonra, 2. adımdaki gereksinimlerin yer aldığını doğrulamak için bir dizi kontrol gerçekleştirilir.

Başarılı olursa, PR'de kontrollerin başarılı olduğu belirtilir. Onaylanan halkla ilişkiler, haftada bir kez (Salı günleri Doğu Saati ile 12:00'da) standart İlişkili Websitesi Grubu'nda gruplar halinde manuel olarak birleştirilir.

Kontrollerden herhangi biri başarısız olursa gönderen kişiye GitHub'daki bir PR hatasıyla bildirim gönderilir. Şikayet gönderen kişi hataları düzeltip PR'yi güncelleyebilir ve aşağıdakileri aklınızdan çıkarmayın:

  • PR başarısız olduğunda bir hata mesajı, gönderimin neden başarısız olabileceğine dair ek bilgi sağlar (örnek).
  • Grup gönderimlerini yöneten tüm teknik kontroller GitHub'da gerçekleştirilir. Dolayısıyla teknik kontrollerden kaynaklanan tüm gönderim hataları GitHub'da görüntülenebilir.

Kurumsal politikalar

Kurumsal kullanıcıların ihtiyaçlarını karşılamak için Chrome'da bir dizi kurumsal politika uygulanmaktadır:

  • İlgili Web Sitesi Grupları ile entegre edilemeyen sistemler, RelatedWebsiteSetsEnabled politikasına sahip Chrome'un tüm kurumsal örneklerinde İlgili Web Sitesi Grupları özelliğini devre dışı bırakabilir.
  • Bazı kurumsal sistemlerde, İlişkili Websitesi Gruplarındaki alan adlarından farklı kaydedilebilir alan adlarına sahip yalnızca dahili siteler (intranet gibi) bulunur. Bu siteleri herkese açık olarak göstermeden İlişkili Websitesi Gruplarının bir parçası olarak işlemeleri gerekiyorsa (alanlar gizli olabileceğinden), herkese açık İlişkili Websitesi Grupları listesini RelatedWebsiteSetsOverrides politikası ile genişletebilir veya geçersiz kılabilirler.

"Kullanıcı istemi" ve "kullanıcı hareketi"

"Kullanıcı istemi" ve "kullanıcı hareketi" farklı şeylerdir. Chrome, aynı İlişkili Websitesi Grubu'ndaki siteler için kullanıcılara izin istemi göstermez ancak Chrome yine de kullanıcının sayfayla etkileşimde bulunmasını gerektirir. Chrome, izin vermeden önce "kullanıcı etkileşimi" veya "kullanıcı etkinleştirme" olarak da adlandırılan bir kullanıcı hareketi gerektirir. Bunun nedeni, web platformu tasarım ilkeleri nedeniyle Storage Access API'nin İlişkili Websitesi Grubu bağlamı (requestStorageAccess()) dışında kullanımının da kullanıcı hareketi gerektirmesidir.

Diğer sitelerin çerezlerine veya depolama alanına erişme

İlgili Web Sitesi Grupları farklı sitelere ait depolama alanlarını birleştirmez. Yalnızca daha kolay (istem içermeyen) requestStorageAccess() aramalarına olanak tanır. İlgili Web Sitesi Setleri, yalnızca kullanıcının Storage Access API'yi kullanırken yaşadığı zorlukları azaltır, ancak erişim tekrar sağlandığında ne yapılacağını belirtmez. A ve B aynı İlişkili Websitesi Grubu'ndaki farklı sitelerse ve A yerleştirmeleri B ise requestStorageAccess() öğesini çağırabilir ve kullanıcıya sormadan birinci taraf depolama alanına erişim elde edebilir. İlişkili Websitesi Grupları, siteler arası iletişim gerçekleştirmez. Örneğin, bir İlişkili Websitesi Grubu'nun ayarlanması, B'ye ait çerezlerin A'ya gönderilmeye başlamasına neden olmaz. Bu verileri paylaşmak isterseniz verileri kendiniz paylaşmanız gerekir. Örneğin, bir B iframe'inden A çerçevesine bir window.postMessage gönderin.

İlişkili Websitesi Grupları, herhangi bir API çağırmadan örtülü bölümlendirilmemiş çerez erişimine izin vermez. Siteler arası çerezler, grup içinde varsayılan olarak kullanıma sunulmaz. İlişkili Websitesi Grupları yalnızca gruptaki sitelerin Storage Access API izin istemini atlamasına olanak tanır. Bir iframe, çerezlerine erişmek istiyorsa document.requestStorageAccess() yöntemini çağırmalıdır veya üst düzey sayfa document.requestStorageAccessFor() yöntemini çağırabilir.

Geri bildirim

GitHub'da bir grup göndermek, Storage Access API ve requestStorageAccessFor API ile çalışmak süreç ve karşılaştığınız sorunlarla ilgili deneyiminizi paylaşmanız için fırsat sunar.

İlgili Web Sitesi Grupları ile ilgili tartışmalara katılmak için: