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

Bu doküman, Paylaşılan Depolama ve Özel Toplama'yı kullanmaya yönelik bir hızlı başlangıç kılavuzudur. Paylaşılan Depolama, değerleri depolar 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ı.

Shared Storage API

Tarayıcılar, siteler arası takibi önlemek için yerel depolama alanı, çerezler vb. dahil olmak üzere tüm depolama alanlarını bölümlendirmeye başladı. Ancak, bölümlenmemiş depolama alanının gerekli olduğu kullanım alanları da 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 Alanı, bağlam kaynağıyla (sharedStorage öğesini çağıran) sınırlıdır.

Paylaşılan Depolama Alanı'nın, kaynak başına bir kapasite sınırı vardır. Her giriş, maksimum karakter sayısıyla sınırlıdır. Sınıra ulaşılırsa başka giriş depolanmaz. Veri depolama alanı sınırları Paylaşılan Depolama alanı başlıklı makalede açıklanmıştır.

Ortak Depolama'yı çağırma

Reklam teknolojileri, JavaScript veya yanıt üstbilgilerini kullanarak Paylaşılan Depolama'ya yazabilir. Paylaşılan depolama alanından okuma işlemi yalnızca iş akışı 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 teknolojisi uzmanları, JavaScript iş parçacığı dışında değer 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ş akışı üzerinden tamamlanması gerekir. JavaScript iş parçasının dışında kullanılabilen yöntemleri Önerilen API yüzeyi - İş parçasının dışında bölümünde bulabilirsiniz.

  Bir işlem sırasında çalışma sayfasında kullanılan yöntemleri Önerilen API yüzeyi - Çalışma sayfasında bölümünde bulabilirsiniz.

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

  JavaScript'e benzer şekilde, yanıt üstbilgileri yalnızca Paylaşılan Depolama Alanı'nda değer ayarlama, ekleme ve silme gibi belirli işlevler için kullanılabilir. Paylaşılan depolama alanıyla yanıt başlığında çalışmak için Shared-Storage-Writable: ?1 öğesinin istek başlığına eklenmesi gerekir.

  İ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";
    

Daha fazla bilgiyi Paylaşılan Depolama: Yanıt Başlıkları bölümünde bulabilirsiniz.

Paylaşılan Depolama alanına yazılıyor

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

ignoreIfPresent alanı isteğe bağlıdır. Mevcutsa ve true olarak ayarlandıysa zaten mevcut olan anahtar güncellenmez. Anahtar güncellenmese bile anahtar geçerlilik süresi, set() çağrısından itibaren 30 gün olarak 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() kullanmayı tercih edebilirsiniz.

• JavaScript kullanma

  Çalışma alanı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ş parçası içinde:

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

• Yanıt üstbilgilerini kullanma

  Yanıt üstbilgilerini kullanarak da Ortak Depolama Alanı'na yazabilirsiniz. Bunun için yanıt başlığında Shared-Storage-Write komutunu aşağıdaki komutlarla birlikte 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 fazla öğe virgül ile ayrılabilir ve set, append, delete ve clear öğelerini içerebilir.

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

Değer ekleme

Ekle yöntemini kullanarak mevcut bir anahtara değer ekleyebilirsiniz. Anahtar mevcut değilse append() çağrısı yapıldığında anahtar oluşturulur ve değer ayarlanır. Bu işlem, JavaScript veya yanıt başlıkları kullanılarak yapılabilir.

• JavaScript kullanma

  Mevcut anahtarların değerlerini güncellemek için iş parçasının içinden veya dışından sharedStorage.append() simgesini 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'}
  

  Çalışma modülüne eklemek için:

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

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

  Paylaşılan Depolama Alanı'nda değer ayarlamaya benzer şekilde, anahtar/değer çiftini iletmek için yanıt üst bilgisinde Shared-Storage-Write öğesini kullanabilirsiniz.

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

Paylaşılan Depolama Alanından Okuma

Ortak Depolama'dan yalnızca bir iş akışı içinden veri okuyabilirsiniz.

await sharedStorage.get('mykey');

İş uygulaması modülünün yüklendiği tarama bağlamının kaynağı, Paylaşılan Depolama alanının kimin okunduğunu belirler.

Ortak Depolama alanından siliniyor

Paylaşılan Depolama Alanı'ndan silme işlemini, JavaScript'i worklet'in içinden veya dışından kullanarak ya da delete() ile yanıt üstbilgilerini kullanarak gerçekleştirebilirsiniz. Tüm anahtarları aynı anda silmek için ikisinden de clear() kullanın.

• JavaScript kullanma

  Ortak Depolama'dan iş akışı dışından silmek için:

  window.sharedStorage.delete('myKey');
  

  İş uygulaması içinden Paylaşılan Depolama Alanı'ndan silmek için:

  sharedStorage.delete('myKey');
  

  İş uygulaması dışından tüm anahtarları tek seferde silmek için:

  window.sharedStorage.clear();
  

  İş uygulamasının içinden tüm anahtarları tek seferde silmek için:

  sharedStorage.clear();
  

• Yanıt üstbilgilerini kullanma

  Değerleri yanıt üstbilgilerini kullanarak silmek amacıyla silinecek anahtarı iletmek için yanıt başlığında Shared-Storage-Write öğesini de kullanabilirsiniz.

  delete;key="myKey"
  

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

  clear;
  

Bağlam değiştirme

Paylaşılan depolama alanı verileri, çağrının geldiği tarama bağlamının kaynak alanına (ör. https://example.adtech.com) yazılır.

Üçüncü taraf kodunu <script> etiketi kullanarak yüklediğinizde kod, yerleştirenin tarama bağlamında yürütülür. Bu nedenle, üçüncü taraf kodu sharedStorage.set() yöntemini çağırdığında, veriler yerleştiricinin Paylaşılan Depolama alanına yazılır. Üçüncü taraf kodunu bir iframe içine yüklediğinizde kod yeni bir tarama 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 Depolama Alanı'na depolar.

Birinci taraf bağlamı

Bir birinci taraf sayfasında sharedStorage.set() veya sharedStorage.delete()'yi çağıran üçüncü taraf JavaScript kodu yerleştirilmişse anahtar/değer çifti birinci taraf bağlamında depolanır.

Üçüncü taraf bağlamı

Anahtar/değer çifti, bir iFrame oluşturarak ve iFrame'den JavaScript kodunda set() veya delete() çağrısı yaparak reklam teknolojisi veya üçüncü taraf bağlamında saklanabilir.

Private Aggregation API

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

Rapor oluşturmak için bir çalışma modülü içinde contributeToHistogram() işlevini bir paket ve değerle çağırın. Paket, işleve BigInt olarak iletilmesi gereken, imzalanmamış 128 bitlik bir tam sayı ile temsil edilir. Değer pozitif bir tam sayı olmalıdır.

Gizliliği korumak amacıyla, paketi ve değeri içeren raporun yükü aktarım sırasında şifrelenir. Ayrıca, şifresi çözülüp yalnızca Toplama Hizmeti kullanılarak toplanabilir.

Tarayıcı, bir sitenin çıkış sorgusuna yapabileceği katkıları da sınırlandırır. Daha açık belirtmek gerekirse katkı bütçesi, belirli bir tarayıcı için tek bir siteden tüm gruplar genelinde belirli bir zaman aralığındaki 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 ve Özel Toplama'yı yürütme

Paylaşılan depolama alanındaki verilere erişmek için bir iş parçası oluşturmanız gerekir. Bunun için createWorklet() işlevini worklet'in URL'siyle çağırın. Varsayılan olarak, createWorklet() ile paylaşılan depolama alanı kullanıldığında veri bölümünün kaynağı, çalışma aracı komut dosyasının kaynağı değil, çağıran tarama bağlamının kaynağı olur.

Varsayılan davranışı değiştirmek için createWorklet özelliğini çağırırken dataOrigin özelliğini ayarlayın.

• dataOrigin: "context-origin": (Varsayılan) Veriler, çağıran tarama bağlamının kaynağının ortak depolama alanında depolanır.
• dataOrigin: "script-origin": Veriler, iş akışı komut dosyasının kaynağının ortak depolama alanında saklanır. Bu modu etkinleştirmek için etkinleştirmeniz gerektiğini unutmayın.

sharedStorage.createWorklet(scriptUrl, {dataOrigin: "script-origin"});

Etkinleştirmek için "script-origin" kullanılırken komut dosyası uç noktasının Shared-Storage-Cross-Origin-Worklet-Allowed başlığıyla yanıt vermesi gerekir. Kaynaklar arası istekler için CORS'un etkinleştirilmesi gerektiğini unutmayın.

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1

`createWorklet()` üzerinde "dataOrigin" ayarlama ve "addModule" ile kaynakta çapraz çalışma parçaları oluşturma M130'ta kullanıma sunuldu.

Kaynaklar arası iFrame kullanma

Ortak depolama iş akışını çağırmak için bir iFrame gereklidir.

Reklamın iFrame'inde addModule() çağrısı yaparak iş parçacığı modülünü yükleyin. sharedStorageWorklet.js worklet dosyasına kaydedilen yöntemi çalıştırmak için aynı reklam iframe JavaScript'inde sharedStorage.run() işlevini çağırın.

const sharedStorageWorklet = await window.sharedStorage.createWorklet(
  'https://any-origin.example/modules/sharedStorageWorklet.js'
);
await sharedStorageWorklet.run('shared-storage-report', {
  data: { campaignId: '1234' },
});

Worklet komut dosyasında, reklamın iFrame'inde çalışacak, asynkron bir runyöntem ve register içeren bir sınıf oluşturmanız gerekir. İç sharedStorageWorklet.js:

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

Kaynaklar arası istek kullanma

Paylaşılan depolama ve özel toplama, kökler arası iframe'lere gerek kalmadan kökler arası iş parçacıkları oluşturmanıza olanak tanır.

Birinci taraf sayfa, kaynak farklı JavaScript uç noktasına createWorklet() çağrısı da yapabilir. Çalışma alanını oluştururken çalışma alanının veri bölümü kaynağını komut dosyası kaynağı olarak ayarlamanız gerekir.

async function crossOriginCall() {
  const privateAggregationWorklet = await sharedStorage.createWorklet(
    'https://cross-origin.example/js/worklet.js',
    { dataOrigin: 'script-origin' }
  );
  await privateAggregationWorklet.run('pa-worklet');
}
crossOriginCall();

Kaynaklar arası JavaScript uç noktasının Shared-Storage-Cross-Origin-Worklet-Allowed başlıklarıyla yanıt vermesi gerekir. Ayrıca istek için CORS'nin etkinleştirildiğini unutmayın.

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1

createWorklet() kullanılarak oluşturulan çalışma kitaplarında selectURL ve run() bulunur. addModule() bu işlem için kullanılamaz.

Not: addModule(), kaynaklar arası iş akışları oluşturmak için kullanılabilir. Ancak createWorklet(), kaynak ötesi veri bölümü oluşturmaya olanak tanıdığı ve addModule()'ten farklı olarak birden fazla iş parçası oluşturabildiği için tercih edilir.

class CrossOriginWorklet {
  async run(data){
    // Other code goes here.
    bucket = getBucket(...);
    value = getValue(...);
    privateAggregation.contributeToHistogram({
      bucket,
      value
    });
  }
}

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)
• Özel Toplamaya Giriş (Geliştirici Chrome)
• Paylaşılan Depolama Alanı Açıklayıcısı (GitHub)
• Özel Toplama Açıklayıcı (GitHub)
• Ortak Depolama Alanı ve Özel Toplama Demo'su

API'ler hakkında bilgi edindikten sonra raporları toplamaya başlayabilirsiniz. Bu 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 birleştirilmiş raporları almak için Toplama Hizmeti için Güvenilir Yürütme Ortamı'nı ayarlayabilirsiniz.

Görüşlerinizi paylaşın

API'ler ve dokümanlar hakkındaki geri bildirimlerinizi GitHub'da paylaşabilirsiniz.

• Ortak Depolama
• Private Aggregation