Paylaşılan Depolama Alanı ve Özel Toplama Uygulaması için Hızlı Başlangıç Kılavuzu

Bu belge, Paylaşılan Depolama Alanı ve Özel Toplama'yı kullanmayla ilgili hızlı başlangıç kılavuzudur. Paylaşılan Depolama değerleri depoladığı ve Özel Toplama, toplanabilir raporları oluşturduğundan her iki API'yi de anlamanız gerekir.

Hedef Kitle: Reklam teknolojileri ve ölçüm sağlayıcıları.

Demoyu deneyin

Canlı demoyu deneyin. Özel Korumalı Alan API'lerini etkinleştirmek için demo talimatlarındaki adımları uygulayın. Chrome Geliştirici Araçları'nı açmak, farklı kullanım alanlarının sonuçlarını görselleştirmenize yardımcı olur. Demoda yer alan kullanım alanları:

• Gizli Toplama
  • Unique Reach Ölçümü
  • Demografi ölçümü
  • K+ sıklık ölçümü
• Genel Kullanım
  • Kısıtlanmış çerçevelerde fareyle üzerine gelme etkinliğini ölçme
  • Üst düzey gezinme
  • Üçüncü tarafların nereye yazabileceğini kontrol etme

Paylaşılan Depolama Alanı nasıl görüntülenir?

Paylaşılan Depolama Alanı'nda nelerin depolandığını görmek için Chrome Geliştirici Araçları'nı kullanın. Depolanan veriler Application -> Shared Storage içinde bulunabilir.

Gizli Toplama raporlarını görüntüleme

Gönderilen birleştirilebilir raporları görüntülemek için chrome://private-aggregation-internals konumuna gidin. Hata ayıklama modu etkinleştirildiğinde rapor hemen (gecikme olmadan) ve [[YOUR_ORIGIN]]/.well-known/private-aggregation/report-shared-storage adresine gönderilecek gecikmeli raporla birlikte [[YOUR_ORIGIN]]/.well-known/private-aggregation/debug/report-shared-storage adresine gönderilir.

Hata ayıklamayı etkinleştirmek için hata ayıklama bölümündeki talimatları uygulayın.

Paylaşılan Depolama API'sı

Siteler arası takibi önlemek için tarayıcılar, yerel depolama ve çerezler de dahil olmak üzere tüm depolama alanı biçimlerini bölümlendirmeye başladı. Ancak bölümlendirilmemiş depolamanın gerekli olduğu kullanım alanları vardır. Shared Storage API gizliliği korumaya yönelik okuma erişimi ile farklı üst düzey sitelerde sınırsız yazma erişimi sağlar.

Paylaşılan Depolama, bağlam kaynağı (sharedStorage çağrısını yapan) ile sınırlıdır.

Paylaşılan Depolama Alanının kaynak başına kapasite sınırı vardır. Her giriş maksimum karakter sayısı ile sınırlıdır. Bu sınıra ulaşılırsa başka giriş kaydedilmez. Veri depolama sınırları, Paylaşılan Depolama açıklayıcısında açıklanmıştır.

Paylaşılan Depolama Alanını Çağırma

Reklam teknisyenleri, JavaScript veya yanıt başlıklarını kullanarak Paylaşılan Depolama alanına yazabilir. Paylaşılan Depolama Alanından okuma, yalnızca iş uygulaması adı verilen izole bir JavaScript ortamında gerçekleşir.

İş uygulaması, belirli JavaScript işlevlerini çalıştırmanıza ve bilgileri istekte bulunan kişiye geri döndürmenize olanak tanır. İş uygulamasında JavaScript'i yürütebilir ancak dış sayfayla etkileşimde bulunamaz veya iletişim kuramazsınız.

İş akışları, Shared Storage API ile veri depolamak ve ayıklamak için kullanılır.

• JavaScript kullanma Reklam teknolojileri, JavaScript iş akışı dışındaki değerleri ayarlama, ekleme ve silme gibi belirli Paylaşılan Depolama işlevlerini gerçekleştirebilir. Ancak Paylaşılan Depolama Alanını okuma ve Özel Toplama gerçekleştirme gibi işlevlerin bir JavaScript iş uygulaması üzerinden tamamlanması gerekir. JavaScript iş uygulaması dışında kullanılabilen yöntemleri Önerilen API Yüzeyi - İş akışının dışında bölümünde bulabilirsiniz.

  Bir işlem sırasında iş akışında kullanılan yöntemleri Önerilen API Yüzeyi - İş uygulamasında bulabilirsiniz.

• Yanıt başlıklarını kullanma

  Bu özellik M119 sürümünde kullanıma sunulmuştur.

  JavaScript'e benzer şekilde, yalnızca Paylaşılan Depolama Alanı'nda değer ayarlama, ekleme ve silme gibi belirli işlevler, yanıt başlıkları kullanılarak yapılabilir. Bir yanıt başlığında Paylaşılan Depolama ile çalışmak için Shared-Storage-Writable: ?1, istek başlığına eklenmelidir.

  İstemciden istek başlatmak için, seçtiğiniz yönteme bağlı olarak aşağıdaki kodu çalıştırın:

  • fetch() kullanılıyor

    fetch("https://a.example/path/for/updates", {sharedStorageWritable: true});
    

  • iframe veya img etiketi kullanma

    <iframe src="https://a.example/path/for/updates" sharedstoragewritable></iframe>
    

  • iframe veya img etiketiyle IDL özelliği kullanma

    let iframe = document.getElementById("my-iframe");
    iframe.sharedStorageWritable = true;
    iframe.src = "https://a.example/path/for/updates";
    

Paylaşılan Depolama: Yanıt Başlıkları bölümünden daha fazla bilgi edinebilirsiniz.

Paylaşılan Depolama birimine yazma

Paylaşılan Depolama'ya yazmak için JavaScript iş akışının içinden veya dışından sharedStorage.set() çağrısı yapın. İş akışının dışından çağrılırsa veriler, çağrının yapıldığı göz atma bağlamının kaynağına yazılır. İş akışının içinden çağrılırsa veriler, iş akışını yükleyen tarama bağlamının kaynağına yazılır. Ayarlanan anahtarların geçerlilik bitiş tarihi, son güncellemeden itibaren 30 gün sonradır.

ignoreIfPresent alanı isteğe bağlıdır. Mevcutsa ve true değerine ayarlanmışsa zaten varsa anahtar güncellenmez. Anahtar güncellenmemiş olsa bile anahtarın geçerlilik süresi set() çağrısından itibaren 30 gün olacak şekilde yenilenir.

Paylaşılan Depolama Alanına aynı sayfa yüklemesinde aynı anahtarla birden çok kez erişilirse anahtar değerinin üzerine yazılır. Anahtarın önceki değeri koruması gerekiyorsa sharedStorage.append() öğesini kullanmak iyi bir fikirdir.

• JavaScript kullanma

  İş akışının dışında:

  window.sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });
  // Shared Storage: {'myKey': 'myValue1'}
  window.sharedStorage.set('myKey', 'myValue2', { ignoreIfPresent: true });
  // Shared Storage: {'myKey': 'myValue1'}
  window.sharedStorage.set('myKey', 'myValue2', { ignoreIfPresent: false });
  // Shared Storage: {'myKey': 'myValue2'}
  

  Benzer şekilde, iş akışının içinde:

  sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });
  

• Yanıt başlıklarını kullanma

  Ayrıca, yanıt başlıklarını kullanarak Paylaşılan Depolama alanına yazabilirsiniz. Bunu yapmak için aşağıdaki komutlarla birlikte yanıt başlığında Shared-Storage-Write kullanın:

  Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present
  

  Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present=?0
  

  Birden çok öğe virgülle ayrılabilir ve set, append, delete ve clear öğelerini birleştirebilir.

  Shared-Storage-Write : 
  set;key="hello";value="world";ignore_if_present, set;key="good";value="bye"
  

Değer ekleme

Ekleme yöntemini kullanarak mevcut bir anahtara değer ekleyebilirsiniz. Anahtar mevcut değilse append() çağrısı, anahtarı oluşturur ve değeri ayarlar. Bu, JavaScript veya yanıt başlıkları kullanılarak gerçekleştirilebilir.

• JavaScript kullanma

  Mevcut anahtarların değerlerini güncellemek için iş akışının içinde veya dışında sharedStorage.append() kullanın.

  window.sharedStorage.append('myKey', 'myValue1');
  // Shared Storage: {'myKey': 'myValue1'}
  window.sharedStorage.append('myKey', 'myValue2');
  // Shared Storage: {'myKey': 'myValue1myValue2'}
  window.sharedStorage.append('anotherKey', 'hello');
  // Shared Storage: {'myKey': 'myValue1myValue2', 'anotherKey': 'hello'}
  

  İş akışının içine eklemek için:

  sharedStorage.append('myKey', 'myValue1');
  

• Yanıt başlıklarını kullanma

  Paylaşılan Depolama'da bir değer ayarlamaya benzer şekilde, anahtar/değer çiftini geçirmek için yanıt başlığındaki Shared-Storage-Write öğesini kullanabilirsiniz.

  Shared-Storage-Write : append;key="myKey";value="myValue2"
  

Paylaşılan Depolama Alanından Okuma

Paylaşılan Depolama Alanı'ndan yalnızca bir iş akışının içinden veri okuyabilirsiniz.

await sharedStorage.get('mykey');

İş akışı modülünün yüklendiği göz atma bağlamının kaynağı, hangi Paylaşılan Depolama Alanının okunacağını belirler.

Paylaşılan Depolama Alanından Silme

İş akışının içinden veya dışından JavaScript kullanarak ya da delete() ile yanıt başlıkları kullanarak Paylaşılan Depolama'dan silme işlemleri gerçekleştirebilirsiniz. Tüm anahtarları aynı anda silmek için bu ikisinden birinden clear() değerini kullanın.

• JavaScript kullanma

  İş akışının dışından Paylaşılan Depolama Alanı'ndan silmek için:

  window.sharedStorage.delete('myKey');
  

  İş akışının içinden Paylaşılan Depolama'dan silmek için:

  sharedStorage.delete('myKey');
  

  Tüm anahtarları aynı anda iş akışının dışından silmek için:

  window.sharedStorage.clear();
  

  İş akışının içinden tüm anahtarları aynı anda silmek için:

  sharedStorage.clear();
  

• Yanıt başlıklarını kullanma

  Yanıt başlıklarını kullanarak değerleri silmek için, silinecek anahtarı iletmek amacıyla yanıt başlığında Shared-Storage-Write ifadesini de kullanabilirsiniz.

  delete;key="myKey"
  

  Yanıt üstbilgilerini kullanarak tüm anahtarları silmek için:

  clear;
  

Bağlam değiştirme

Paylaşılan Depolama verileri, çağrının kaynağı olan göz atma bağlamının kaynak öğesine (ör. https://example.adtech.com) yazılır.

Üçüncü taraf kodunu <script> etiketi kullanarak yüklediğinizde kod, yerleştiricinin göz atma bağlamında yürütülür. Bu nedenle, üçüncü taraf kodu sharedStorage.set() çağırdığında, veriler yer tutucunun Paylaşılan Depolama Alanına yazılır. Üçüncü taraf kodunu bir iframe içinde yüklediğinizde, kod yeni bir göz atma bağlamı alır ve kaynağı iframe'in kaynağıdır. Bu nedenle, iframe'den yapılan sharedStorage.set() çağrısı, verileri iframe kaynağının Paylaşılan Depolamasında depolar.

Birinci taraf bağlamı

Birinci taraf sayfasında sharedStorage.set() veya sharedStorage.delete() çağıran yerleşik üçüncü taraf JavaScript kodu varsa anahtar/değer çifti birinci taraf bağlamında depolanır.

Üçüncü taraf bağlamı

Anahtar/değer çifti, bir iframe oluşturup iframe'in içinden JavaScript kodunda set() veya delete() çağrısı yaparak reklam teknolojisi veya üçüncü taraf bağlamında depolanabilir.

Gizli Toplama API'sı

Shared Storage'da depolanan toplanabilir verileri ölçmek için Private Aggregation API'yi kullanabilirsiniz.

Rapor oluşturmak için paket ve değere sahip bir iş uygulamasının içinde contributeToHistogram() çağrısı yapın. Paket, BigInt olarak işleve iletilmesi gereken imzasız 128 bitlik bir tam sayı ile temsil edilir. Değer, pozitif bir tam sayıdır.

Gizliliği korumak amacıyla, paketi ve değeri içeren rapor yükü aktarım sırasında şifrelenir. Bu verilerin şifresi yalnızca Toplama Hizmeti kullanılarak çözülebilir ve toplanabilir.

Tarayıcı, bir sitenin çıkış sorgusuna yapabileceği katkıları da sınırlandırır. Daha ayrıntılı ifade etmek gerekirse katkı bütçesi, tüm paketler genelinde belirli bir zaman aralığında belirli bir tarayıcı için tek bir siteden alınan tüm raporların toplamını sınırlar. Mevcut bütçe aşılırsa rapor oluşturulmaz.

privateAggregation.contributeToHistogram({
  bucket: BigInt(myBucket),
  value: parseInt(myBucketValue)
});

Paylaşılan Depolama Alanı ve Özel Toplama Yürütme

Reklamın iframe'inde, addModule() çağrısı yaparak iş uygulaması modülünü yükleyin. sharedStorageWorklet.js iş uygulaması dosyasında kayıtlı yöntemi çalıştırmak için aynı reklam iframe JavaScript'inde sharedStorage.run() yöntemini çağırın.

await window.sharedStorage.worklet.addModule('modules/sharedStorageWorklet.js');
await window.sharedStorage.worklet.run('shared-storage-report', {
  data: { campaignId: '1234' },
});

İş akışı komut dosyasında, eşzamansız run yöntemine sahip bir sınıf oluşturmanız gerekir. Ve bu sınıfın reklamın iframe'inde çalıştırılması için register. sharedStorageWorklet.js içinde:

class SharedStorageReportOperation {
  async run(data) {
    // Other code goes here.
    bucket = getBucket(...);
    value = getValue(...);
    privateAggregation.contributeToHistogram({
      bucket: bucket,
      value: value
    });
  }
}
register('shared-storage-report',
  SharedStorageReportOperation);

Hata ayıklama

Hata ayıklamayı etkinleştirmek için Paylaşılan Depolama ve Gizli Toplama'nın kullanıldığı bağlamda enableDebugMode() JavaScript yöntemini çağırın. Bu, aynı bağlamda gelecekteki raporlara uygulanacaktır.

privateAggregation.enableDebugMode();

Raporları tetikleyen bağlamlarla ilişkilendirmek için JavaScript çağrısına geçirilen 64 bitlik imzalanmamış bir tamsayı hata ayıklama anahtarı ayarlayabilirsiniz. debugKey bir BigInt.

privateAggregation.enableDebugMode({debugKey: 1234});

Paylaşılan Depolama Alanında Hata Ayıklama

Paylaşılan Depolama, genel bir hata mesajı döndürür:

Promise is rejected without and explicit error message

Çağrıları try-catch bloklarıyla sarmalayarak Paylaşılan Depolama'da hata ayıklayabilirsiniz.

try {
  privateAggregation.contributeToHistogram({bucket, value});
} catch (e){
  console.log(e);
}

Gizli Toplamada Hata Ayıklama

Raporlar /.well-known/private-aggregation/report-shared-storage ve /.well-known/private-aggregation/debug/report-shared-storage adreslerine gönderilir. Hata ayıklama raporları aşağıdaki JSON'a benzer bir yük alır. Bu yük, api alanını "shared-storage" olarak tanımlar.

{
   "aggregation_coordinator_identifier": "aws-cloud",
   "aggregation_service_payloads": [ {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAEfV32BFWlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "9bc4afa7-2934-4779-99ff-999d91b137ec",
      "payload": "bqOFO/cHCdwefU2W4FjMYRMSLoGHPWwZbgVF4aa/ji2YtwFz+jb6v2XCwQUdmvYcZSRPKosGRpKELJ0xAFv+VBYvCiv3FXP6jjAHQD+XAJUz17A39aXijk6JnEAu86+DfTSbXYn1fWhGzIG9xH/Y"
   } ],
   "debug_key": "1234",
   "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"93f86829-cdf7-4ecd-b16d-4e415a3ee063\",\"reporting_origin\":\"https://small-free-wealth.glitch.me\",\"scheduled_report_time\":\"1681319668\",\"version\":\"0.1\"}"
}

Net metin yükünde hata ayıklama

debug_cleartext_payload, Base64 CBOR kodludur. Paketi ve değeri kod çözücü ile görüntüleyebilir veya Shared Storage kod çözücü'de bulunan JavaScript kodunu kullanabilirsiniz.

Sonraki adımlar

Aşağıdaki sayfalarda, Paylaşılan Depolama ve Özel Toplama API'lerinin önemli yönleri açıklanmaktadır.

• Paylaşılan Depolama Alanına Giriş (Geliştirici Chrome)
• Paylaşılan Depolama Alanı Kullanım Alanları (Geliştirici Chrome)
• Gizli Toplamaya Giriş (Geliştirici Chrome)
• Paylaşılan Depolama Alanı Açıklaması (GitHub)
• Özel Toplama Açıklaması (GitHub)
• Paylaşılan Depolama Alanı ve Gizli Toplama Demosu

API'ler hakkında bilgi edindikten sonra raporları toplamaya başlayabilirsiniz. Raporlar, istek gövdesinde JSON olarak aşağıdaki uç noktalara POST isteği olarak gönderilir.

• Hata Ayıklama Raporları - context-origin/.well-known/private-aggregation/debug/report-shared-storage
• Raporlar - context-origin/.well-known/private-aggregation/report-shared-storage

Raporlar toplandıktan sonra yerel test aracını kullanarak test yapabilir veya toplu raporları almak için Toplama Hizmeti için Güvenilir Yürütme Ortamı'nı kurabilirsiniz.

Görüşlerinizi paylaşın

API'ler ve GitHub'daki dokümanlarla ilgili geri bildirimlerinizi paylaşabilirsiniz.

• Paylaşılan Depolama
• Gizli Toplama