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

İlişkili Websitesi Grupları (RWS), tarayıcıların bir alan koleksiyonu arasındaki ilişkileri anlamasına yardımcı olan bir web platformu mekanizmasıdır. Bu sayede tarayıcılar, belirli site işlevlerini etkinleştirmek için önemli kararlar alabilir (ör. siteler arası çerezlere erişime izin verilip verilmeyeceği) ve bu bilgileri kullanıcılara sunabilir.

Birçok site, tek bir kullanıcı deneyimi sunmak için birden fazla alana güvenir. Kuruluşlar, ülkeye özgü alanlar veya resim ya da video barındırmak için hizmet alanları gibi birden fazla kullanım alanı için farklı üst düzey alan adları kullanmak isteyebilir. İlişkili Websitesi Grupları, sitelerin alanlar arasında veri paylaşmasına olanak tanır.

İlişkili Websitesi Grubu nedir?

İlişkili Websitesi Grubu, genel olarak tek bir "grubun birincil üyesi" ve muhtemelen birden fazla "grup üyesi" bulunan bir alan koleksiyonudur.

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

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

İlgili Web Sitesi Grupları, GitHub'da barındırılan herkese açık bir JSON dosyasında listelenir. Bu, onaylanmış tüm kümeler için standart kaynaktır. Tarayıcılar, sitelerin aynı İlişkili Websitesi Grubu'na ait olup olmadığını belirlemek için bu dosyayı kullanır.

Yalnızca bir alan üzerinde yönetim kontrolü olan kullanıcılar bu alanla bir küme oluşturabilir. Gönderenlerin, her "set üyesi" ile "setin birincil üyesi" arasındaki ilişkiyi bildirmesi gerekir. Küme üyeleri, çeşitli alan türlerini içerebilir ve kullanım alanına dayalı bir alt kümenin parçası olmalıdır.

Uygulamanız, aynı İlgili Web Sitesi Grubu'ndaki sitelerde siteler arası çerezlere (üçüncü taraf çerezleri olarak da adlandırılır) erişime bağlıysa bu çerezlere erişim isteğinde bulunmak için Storage Access API (SAA) ve requestStorageAccessFor API'yi kullanabilirsiniz. Tarayıcı, her sitenin parçası olduğu alt kümeye bağlı olarak isteği farklı şekilde işleyebilir.

Set gönderme süreci ve koşulları hakkında daha fazla bilgi edinmek için gönderim yönergelerini inceleyin. Gönderilen setler, gönderimlerin doğrulanması için çeşitli teknik kontrollerden geçer.

İlişkili Websitesi Grupları kullanım alanları

İlişkili Websitesi Grupları, bir kuruluşun farklı üst düzey sitelerde ortak bir kimliğe ihtiyaç duyduğu durumlarda iyi bir seçenektir.

İlişkili Web Sitesi Gruplarının bazı kullanım alanları şunlardır:

• Ülkeye göre özelleştirme. Paylaşılan altyapıdan yararlanırken yerelleştirilmiş sitelerden yararlanma (ör. example.co.uk, example.ca tarafından barındırılan bir hizmeti kullanabilir).
• Hizmet alanı entegrasyonu. Kullanıcıların doğrudan etkileşimde bulunmadığı ancak aynı kuruluşun sitelerinde hizmet sağlayan hizmet alanlarından (ör. example-cdn.com) yararlanma.
• Kullanıcı içeriğini ayırma. Güvenlik nedeniyle kullanıcı tarafından yüklenen içeriği diğer site içeriklerinden ayıran farklı alanlardaki verilere erişirken, korumalı alanın kimlik doğrulama (ve diğer) çerezlerine erişmesine izin verilir. Etkin olmayan, kullanıcı tarafından yüklenen içerik yayınlıyorsanı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. Bağlı mülklerdeki yerleştirilmiş içerikleri (videolar, dokümanlar veya üst düzey sitede oturum açmış kullanıcıyla sınırlı kaynaklar) destekleme.
• Oturum açma. Bağlı mülklerde oturum açmayı destekleme FedCM API de bazı kullanım alanları için uygun olabilir.
• Analytics Hizmet kalitesini artırmak için bağlı kuruluş mülklerinde kullanıcı yolculuklarının analizini ve ölçümünü dağıtma.

İlişkili Websitesi Grupları entegrasyonuyla ilgili ayrıntılar

Storage Access API

Storage Access API (SAA), yerleştirilmiş kaynaklar arası içeriğin normalde yalnızca birinci taraf bağlamında erişebileceği depolama alanına erişmesini sağlar.

Yerleştirilmiş kaynaklar, şu anda depolama alanına erişimleri 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 ancak İlişkili Web Sitesi Grupları (RWS) etkinleştirildiğinde Chrome, RWS içi bağlamlarda otomatik olarak izin verir ve 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 bir bağlamdır (ör. iframe).)

Depolama alanına erişimi kontrol etme ve isteme

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

Bu yöntem, dokümanın çerezlerine erişiminin olup olmadığını belirten bir Boole değeriyle çözümlenen bir söz döndürür. Iframe, üst çerçeveyle aynı kaynaklıysa söz de doğru (true) değerini döndürür.

Yerleştirilmiş siteler, siteler arası bağlamda çerezlere erişim isteğinde bulunmak için Document.requestStorageAccess() (rSA) kullanabilir.

requestStorageAccess() API'sinin bir iFrame içinden çağrılması amaçlanmıştır. Bu iframe'in, kullanıcı etkileşimi (tüm tarayıcılar tarafından gerekli olan bir kullanıcı hareketi) almış olması gerekir. Ancak Chrome, son 30 gün içinde kullanıcının bu iframe'e sahip olan siteyi ziyaret etmesini ve bu siteyle özellikle etkileşimde bulunmasını (iframe'de değil, üst düzey bir doküman olarak) de zorunlu kılar.

requestStorageAccess(), depolama alanına erişim izni verildiyse çözümlenen bir söz döndürür. Erişim herhangi bir nedenle reddedilirse gerekçe belirtilerek söz reddedilir.

Chrome'da requestStorageAccessFor

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

Bu durum, çerez gerektiren siteler arası resimler veya komut dosyası etiketleri kullanan üst düzey sitelerde Storage Access API'nin benimsenmesi açısından zorluklar yaratır.

Chrome bu sorunu çözmek için üst düzey sitelerin Document.requestStorageAccessFor() (rSAFor) ile belirli kaynaklar adına depolama erişimi istemesine olanak tanıyan bir yöntem uyguladı.

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

requestStorageAccessFor() API'sinin üst düzey bir doküman tarafından çağrılması amaçlanmıştır. Bu belgenin de kısa süre önce kullanıcı etkileşimi almış olması gerekir. Ancak requestStorageAccess()'dan farklı olarak Chrome, kullanıcı zaten sayfada olduğundan son 30 gün içinde üst düzey bir dokümanda etkileşim olup olmadığını kontrol etmez.

Depolama alanına 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 (izin verilmiş mi, reddedilmiş mi veya bir istemi tıklamak ya da sayfayla etkileşim kurmak gibi bir kullanıcı etkileşimi gerektiriyor mu) kontrol etmenin bir yolunu sunar.

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

Mevcut bağlam için depolama alanı erişim iznini kontrol etmek üzere 'storage-access' dizesini iletmeniz gerekir:

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

Belirli bir kaynak için depolama alanı erişim iznini kontrol etmek üzere '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 kontrolün 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 kullanıcı hareketi gerektirip gerektirmediğine bağlı olarak prompt veya granted döndürülür.

Çerçeve başına model

rSA izinleri kare başına uygulanır. rSA ve rSAFor izinleri ayrı izinler olarak değerlendirilir.

Her yeni çerçeve için ayrı ayrı depolama alanı erişimi isteğinde bulunulması gerekir ve erişim otomatik olarak verilir. Yalnızca ilk istek için kullanıcı hareketi gerekir. Iframe tarafından başlatılan sonraki istekler (ör. gezinme veya alt kaynaklar) için kullanıcı hareketi beklenmez. Çünkü bu hareket, ilk istek tarafından tarama oturumu için verilir.

iFrame'in yenilenmesi, yeniden yüklenmesi veya başka bir şekilde yeniden oluşturulması için tekrar erişim isteğinde bulunulması gerekir.

Çerez şartları

Çerezler hem SameSite=None hem de Secure özelliklerini rSA olarak belirtmelidir. rSA yalnızca siteler arası bağlamlarda kullanılmak üzere işaretlenmiş çerezlere erişim sağlar.

SameSite=Lax, SameSite=Strict veya SameSite özelliği olmayan çerezler yalnızca birinci taraf kullanımı içindir ve RSA'dan bağımsız olarak siteler arası bağlamda asla paylaşılmaz.

Güvenlik

rSAFor için alt kaynak istekleri, açıkça etkinleştirme sağlamak üzere kaynaklarda merkezler arası kaynak paylaşımı (CORS) üstbilgileri veya crossorigin özelliğini gerektirir.

Uygulama örnekleri

Yerleştirilmiş bir kaynaklar arası iframe'den depolama alanına erişim isteğinde bulunma

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

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

Söz doğru olarak çözümlenirse siteler arası bağlamda depolamaya erişebilirsiniz. Değer yanlışsa depolama alanı erişimi isteğinde bulunmanız gerekir.

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

Depolama alanına erişim isteği

Depolama erişimi isteğinde bulunmanız gerekiyorsa öncelikle depolama erişimi iznini kontrol ederek navigator.permissions.query({name: 'storage-access'}) kullanıcı hareketi gerektirip gerektirmediğini veya otomatik olarak verilip verilemeyeceğini öğrenin.

İzin granted ise document.requestStorageAccess() işlevini çağırabilirsiniz ve bu işlem, kullanıcı hareketi olmadan başarılı olur.

İzin durumu prompt ise document.requestStorageAccess() çağrısını bir kullanıcı hareketi (ör. düğme tıklama) sonrasında 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çevenin içinden gelen sonraki istekler, gezinmeler veya alt kaynaklar, siteler arası çerezlere erişim iznine otomatik olarak sahip olur. hasStorageAccess() doğru değerini döndürür ve aynı İlgili Web Sitesi Grubu'ndaki siteler arası çerezler, bu isteklerde ek JavaScript çağrıları olmadan gönderilir.

Alanlar arası siteler adına çerez erişimi isteyen üst düzey siteler

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

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

Kullanıcıya istem gösterilip gösterilmeyeceğini veya belirtilen kaynağa depolama alanı erişiminin zaten verilip verilmediğini öğrenmek için navigator.permissions.query({name: 'top-level-storage-access', requestedOrigin: 'https://target.site'}) işlevini çağırı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ı kullanıcı hareketinin (ör. düğme tıklama) arkasına yerleştirmeniz 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 crossorigin özelliği 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 sürümleri kullanın ve test-third-party-cookie-phaseout Chrome işaretini etkinleştirin.

Chrome işaretini etkinleştirme

Gerekli Chrome flag'ini etkinleştirmek için adres çubuğundan chrome://flags#test-third-party-cookie-phaseout simgesine gidin ve flag'i Enabled olarak değiştirin. Flags değiştirildikten sonra tarayıcıyı yeniden başlattığınızdan emin olun.

Yerel bir İlişkili Websitesi Grubu ile Chrome'u başlatma

Chrome'u yerel olarak tanımlanmış İlişkili Web Sitesi Kümesi ile başlatmak için bir kümenin üyeleri olan URL'leri içeren bir JSON nesnesi oluşturun ve bunu --use-related-website-set öğesine iletin.

Chromium'u işaretlerle ç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 test-third-party-cookie-phaseout seçeneğini chrome://flags bölümünde etkinleştirmeniz ve Chrome'u komut satırından, bir gruba ait URL'leri içeren JSON nesnesiyle birlikte --use-related-website-set işaretiyle 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şebildiğinizi doğrulayın

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

İlişkili Websitesi Grupları gönderim süreci

Alanlar arasındaki ilişkiyi bildirmek ve hangi alt kümeye ait olduklarını belirtmek için aşağıdaki adımları uygulayın.

1. RWS'nizi belirleme

İlişkili Websitesi Grubu'nun parçası olacak grubun birincil sitesi ve grup üyeleri dahil olmak üzere ilgili alanları belirleyin. Ayrıca her küme üyesinin hangi alt küme türüne ait olduğunu da belirleyin.

2. RWS gönderiminizi oluşturma

GitHub deposunun yerel bir kopyasını (klon veya çatallama) oluşturun. Yeni bir dalda, kümenizi yansıtmak için related_website_sets.JSON dosyasında değişiklikler yapın. Setinizin doğru JSON biçimlendirmesine ve yapısına sahip olduğundan emin olmak için JSON Oluşturma Aracı'nı kullanabilirsiniz.

3. RWS'nizin teknik koşulları karşıladığından emin olun

Set oluşturma koşullarının ve set doğrulama koşullarının karşılandığından emin olun.

4. RWS'nizi yerel olarak test etme

Setinizi göndermek için çekme isteği (PR) oluşturmadan önce gönderiminizi yerel olarak test ederek gerekli tüm kontrollerden geçtiğinden emin olun.

5. RWS'nizi gönderme

Chrome'un standart İlişkili Websitesi Grupları listesini barındırdığı related_website_sets.JSON dosyası için bir çekme isteği oluşturarak İlişkili Websitesi Grubu'nu gönderin. (PR oluşturmak için GitHub hesabı gerekir ve listeye katkıda bulunabilmeniz öncesinde Katkıda Bulunanların Lisans Sözleşmesi'ni (CLA) imzalamanız gerekir.)

PR oluşturulduktan sonra, 3. adımda belirtilen şartların karşılandığından emin olmak için bir dizi kontrol yapılır. Örneğin, CLA'yı imzaladığınız ve .well-known dosyasının geçerli olduğu doğrulanır.

İşlem başarılı olursa çekme isteği, kontrollerin başarılı olduğunu gösterir. Onaylanan çekme istekleri, standart İlişkili Websitesi Grubu listesine haftada bir kez (Doğu saatiyle salı günleri öğlen 12:00'de) manuel olarak toplu şekilde birleştirilir. Kontrollerden herhangi biri başarısız olursa gönderen, GitHub'da bir çekme isteği hatası aracılığıyla bilgilendirilir. Gönderen, hataları düzeltebilir ve PR'yi güncelleyebilir. Bu durumda şunları göz önünde bulundurmalıdır:

• PR başarısız olursa hata mesajında gönderimin neden başarısız olmuş olabileceğine dair ek bilgiler verilir. (örnek).
• Gönderimlerin belirlenmesini yöneten tüm teknik kontroller GitHub'da yapılır. Bu nedenle, teknik kontrollerden kaynaklanan tüm gönderim hataları GitHub'da görülebilir.

Kurumsal politikalar

Chrome, kurumsal kullanıcıların ihtiyaçlarını karşılamak için iki politika uygular:

• İlişkili Web Sitesi Grupları ile entegre olamayan sistemler, RelatedWebsiteSetsEnabled politikasıyla Chrome'un tüm kurumsal örneklerinde İlişkili Web Sitesi Grupları özelliğini devre dışı bırakabilir.
  • Bazı kurumsal sistemlerde, İlişkili Web Sitesi Grubu'ndaki alanlardan farklı kaydedilebilir alanlara sahip yalnızca dahili siteler (ör. intranet) bulunur. Bu siteleri herkese açık olarak göstermeden (alan adları gizli olabileceğinden) İlişkili Web Sitesi Grubu'nun bir parçası olarak ele almaları gerekiyorsa herkese açık İlişkili Web Sitesi Grupları listelerini RelatedWebsiteSetsOverrides politikasıyla artırabilir veya geçersiz kılabilirler.

Chrome, replacements veya additions belirtilip belirtilmediğine bağlı olarak herkese açık ve Enterprise kümelerinin kesişimlerini iki şekilde çözer.

Örneğin, herkese açık ayar için {primary: A, associated: [B, C]}:

İlişkili Websitesi Gruplarıyla ilgili sorunları giderme

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

"Kullanıcı istemi" ve "kullanıcı hareketi" farklı şeylerdir. Chrome, aynı İlgili Web Sitesi Seti'ndeki siteler için kullanıcılara izin istemi göstermez ancak kullanıcının sayfayla etkileşimde bulunması yine de gerekir. Chrome, izin vermeden önce kullanıcı hareketi ("kullanıcı etkileşimi" veya "kullanıcı etkinleştirme" olarak da bilinir) yapılmasını zorunlu kılar. Bunun nedeni, web platformu tasarım ilkeleri nedeniyle Storage Access API'nin İlişkili Websitesi Grubu bağlamı dışında (yani requestStorageAccess()) kullanımının da kullanıcı hareketi gerektirmesidir.

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

İlişkili Web Sitesi Grupları, farklı sitelerin depolama alanlarını birleştirmez. Yalnızca daha kolay (istem içermeyen) requestStorageAccess() çağrılarına izin verir. İlişkili Web Sitesi Grupları yalnızca Storage Access API'nin kullanımındaki kullanıcı zorluğunu azaltır ancak erişim geri yüklendikten sonra ne yapılacağını belirlemez. A ve B aynı İlişkili Websitesi Grubu'nda farklı sitelerse ve A, B'yi yerleştiriyorsa B, requestStorageAccess() çağrısı yapabilir ve kullanıcıya sormadan birinci taraf depolama alanına erişebilir. İlişkili Websitesi Grupları, siteler arası iletişim gerçekleştirmez. Örneğin, bir İlişkili Web Sitesi Grubu oluşturmak, B'ye ait çerezlerin A'ya gönderilmeye başlamasına neden olmaz. Bu verileri paylaşmak istiyorsanız kendiniz paylaşmanız gerekir. Örneğin, B iFrame'inden A çerçevesine window.postMessage göndererek.

Varsayılan olarak bölümlenmemiş çerez erişimi

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

Geri bildiriminizi paylaşın

GitHub'da bir küme gönderme ve Storage Access API ile requestStorageAccessFor API'yi kullanma, süreçle ilgili deneyiminizi ve karşılaştığınız sorunları paylaşma fırsatlarıdır.

İlişkili Websitesi Grupları hakkındaki tartışmalara katılmak için:

• İlişkili Websitesi Grupları herkese açık posta listesine katılın.
  • Sorunları bildirin ve İlişkili Web Sitesi Grupları GitHub deposundaki tartışmayı takip edin.