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.

Ortak Depolama Alanı, bağlam kaynağıyla (sharedStorage'yi çağıran) sınırlıdır.

Ortak depolama alanında, her girişin maksimum karakter sayısıyla sınırlı olduğu kaynak başına bir kapasite sınırı vardı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.

  • 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ş parçası aracılığıyla 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 üstbilgilerini 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. Yanıt başlığında Ortak Depolama ile çalışmak için Shared-Storage-Writable: ?1 isteği başlığına dahil edilmelidir.

    İ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 Alanı: Yanıt Başlıkları başlıklı makalede bulabilirsiniz.

Paylaşılan depolama birimine yazma

Paylaşılan depolama alanına yazmak için JavaScript iş parçasının 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 itibaren 30 gündü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. Bunu yapmak için yanıt üstbilgisinde aşağıdaki komutlarla birlikte 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ü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 yoksa append() çağrıldığında anahtar oluşturulur ve değer ayarlanır. Bu, 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 üstbilgilerini 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"
    

Değerlerin toplu olarak güncellenmesi

sharedStorage.batchUpdate() işlevini bir JavaScript iş parçasının içinden veya dışından çağırabilir ve seçilen işlemleri belirten sıralı bir yöntem dizisi iletebilirsiniz. Her yöntem kurucusu, ayarlama, ekleme, silme ve temizleme için ilgili bağımsız yöntemiyle aynı parametreleri kabul eder.

Kilidi JavaScript veya yanıt başlığı kullanarak ayarlayabilirsiniz:

  • JavaScript kullanma

    batchUpdate() ile kullanılabilen JavaScript yöntemleri şunlardır:

    • SharedStorageSetMethod(): Paylaşılan depolama alanına bir anahtar/değer çifti yazar.
    • SharedStorageAppendMethod(): Ortak Depolama'daki mevcut bir anahtara değer ekler.
    • SharedStorageDeleteMethod(): Ortak Depolama'dan bir anahtar/değer çiftini siler.
    • SharedStorageClearMethod(): Paylaşılan Depolama Alanındaki tüm anahtarları temizler.
    sharedStorage.batchUpdate([
    new SharedStorageSetMethod('keyOne', 'valueOne'),
    new SharedStorageAppendMethod('keyTwo', 'valueTwo'),
    new SharedStorageDeleteMethod('keyThree'),
    new SharedStorageClearMethod()
    ]);
    
  • Yanıt üstbilgilerini kullanma

    Shared-Storage-Write : batchUpdate;methods="set;key=keyOne;value=valueOne, append;key=keyTwo;value=valueTwo,delete;key=keyThree,clear"
    

Paylaşılan Depolama Alanından Okuma

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

await sharedStorage.get('mykey');

İş akışı modülünün yüklendiği tarama bağlamının kaynağı, kimin Ortak Depolama'sının okunacağını belirler.

Paylaşılan depolama alanından silme

Paylaşılan Depolama Alanı'ndan silme işlemini, JavaScript'i worklet'in içinden veya dışından ya da delete() ile yanıt üstbilgilerini kullanarak gerçekleştirebilirsiniz. Tüm anahtarları tek seferde silmek için bu iki seçenekten birini kullanarak clear() simgesini kullanın.

  • JavaScript kullanma

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

    window.sharedStorage.delete('myKey');
    

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

    sharedStorage.delete('myKey');
    

    Tüm anahtarları çalışma aletinin dışından tek seferde silmek için:

    window.sharedStorage.clear();
    

    Tüm anahtarları çalışma aracının içinden tek seferde silmek için:

    sharedStorage.clear();
    
  • Yanıt üstbilgilerini kullanma

    Yanıt üst bilgilerini kullanarak değerleri silmek için, yanıt üst bilgisinde Shared-Storage-Write değerini kullanarak silinecek anahtarı da iletebilirsiniz.

    delete;key="myKey"
    

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

    clear;
    

Paylaşılan depolama alanından Protected Audience ilgi alanı gruplarını okuma

Protected Audience'ın ilgi alanı gruplarını bir Ortak Depolama Alanı iş parçasından okuyabilirsiniz. interestGroups() yöntemi, AuctionInterestGroup ve GenerateBidInterestGroup özellikleri dahil olmak üzere bir StorageInterestGroup nesnesi dizisi döndürür.

Aşağıdaki örnekte, tarama bağlamı ilgi alanı gruplarının nasıl okunacağı ve alınan ilgi alanı gruplarında yapılabilecek bazı olası işlemler gösterilmektedir. Kullanılan iki olası işlem, ilgi alanı gruplarının sayısını bulmak ve en yüksek teklif sayısına sahip ilgi alanı grubunu bulmaktır.

async function analyzeInterestGroups() {
  const interestGroups = await interestGroups();
  numIGs = interestGroups.length;
  maxBidCountIG = interestGroups.reduce((max, cur) => { return cur.bidCount > max.bidCount ? cur : max; }, interestGroups[0]);
  console.log("The IG that bid the most has name " + maxBidCountIG.name);
}

Worklet modülünün yüklendiği tarama bağlamının kaynağı, varsayılan olarak okunan ilgi alanı gruplarının kaynağını belirler. Varsayılan iş parçası kaynağı ve nasıl değiştirileceği hakkında daha fazla bilgi edinmek için Shared Storage API Rehberli Turu'ndaki Executing Shared Storage and Private Aggregation (Paylaşılan Depolama Alanı ve Özel Toplama'yı Çalıştırma) bölümünü inceleyin.

Seçenekler

Tüm Paylaşılan Depolama alanı değiştirici yöntemleri, son bağımsız değişken olarak isteğe bağlı bir seçenekler nesnesini destekler.

withLock

withLock seçeneği isteğe bağlıdır. Belirtilen bu seçenek, yönteme devam etmeden önce Web Locks API'yi kullanarak tanımlanan kaynak için kilit edinmesini söyler. Kilit isteğinde bulunurken bir kilit adı iletilir. Ad, kaynağın içindeki birden fazla sekme, işleyici veya kodda kullanımının koordine edildiği bir kaynağı temsil eder.

withLock seçeneği, aşağıdaki Paylaşılan Depolama Alanı değiştirici yöntemleriyle kullanılabilir:

  • grup
  • ekleme
  • delete
  • temizle
  • toplu güncelleme

Kilidi JavaScript veya yanıt başlığı kullanarak ayarlayabilirsiniz:

  • JavaScript kullanma

    sharedStorage.set('myKey', 'myValue', { withLock: 'myResource' });
    
  • Yanıt üstbilgilerini kullanma

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

Ortak depolama alanı kilitleri, veri kaynağına göre bölümlendirilir. Kilitler, window veya worker bağlamında olup olmadıklarından bağımsız olarak LockManager request() yöntemi kullanılarak elde edilen kilitlerden bağımsızdır. Bununla birlikte, SharedStorageWorklet bağlamında request() kullanılarak elde edilen kilitlerle aynı kapsamı paylaşırlar.

request() yöntemi çeşitli yapılandırma seçeneklerine izin verse de Paylaşılan Depolama Alanı'nda edinilen kilitler her zaman aşağıdaki varsayılan ayarlara uyar:

  • mode: "exclusive": Aynı ada sahip başka kilitler aynı anda tutulamaz.
  • steal: false: Aynı ada sahip mevcut kilitler, diğer isteklere yer açmak için serbest bırakılmaz.
  • ifAvailable: false: İstekler, kilit kullanılabilir hale gelene kadar süresiz olarak bekler.
withLock ne zaman kullanılır?

Kilitler, aynı anda çalışan birden fazla çalışma öğesinin (ör. bir sayfadaki birden fazla çalışma öğesi veya farklı sekmelerdeki birden fazla çalışma öğesi) her birinin aynı verilere baktığı senaryolarda faydalıdır. Bu senaryoda, raporların tek seferde yalnızca bir worklet tarafından işlenmesi için ilgili worklet kodunu bir kilitle sarmalamak iyi bir fikirdir.

Kilitlerin yararlı olduğu bir diğer durum da, bir iş parçasında birlikte okunması gereken birden fazla anahtar varsa ve bunların durumları senkronize edilmek zorundaysa ortaya çıkar. Bu durumda, get çağrılarını bir kilitle sarmalamak ve bu anahtarlara yazarken aynı kilidi edindiğinizden emin olmak gerekir.

Kilitlerin sırası

Web kilitlerinin yapısı nedeniyle değiştirici yöntemleri, tanımladığınız sırayla yürütülmeyebilir. İlk işlem kilit gerektiriyorsa ve geciktiyse ikinci işlem ilk işlem tamamlanmadan önce başlayabilir.

Örnek:

// This line might pause until the lock is available.
sharedStorage.set('keyOne', 'valueOne', { withLock: 'resource-lock' });

// This line will run right away, even if the first one is still waiting.
sharedStorage.set('keyOne', 'valueTwo');
Birden fazla anahtarı değiştirme örneği

Bu örnekte, iş parçası içindeki okuma ve silme işlemlerinin birlikte gerçekleşmesini sağlamak için bir kilit kullanılır. Böylece, iş parçasının dışından müdahale edilmesi engellenir.

Aşağıdaki modify-multiple-keys.js örneğinde, modify-lock ile keyOne ve keyTwo için yeni değerler ayarlanır ve ardından çalışma sayfasından modify-multiple-keys işlemi yürütülür:

// modify-multiple-keys.js
sharedStorage.batchUpdate([
    new SharedStorageSetMethod('keyOne', calculateValueFor('keyOne')),
    new SharedStorageSetMethod('keyTwo', calculateValueFor('keyTwo'))
], { withLock: 'modify-lock' });

const modifyWorklet = await sharedStorage.createWorklet('modify-multiple-keys-worklet.js');
await modifyWorklet.run('modify-multiple-keys');

Ardından, modify-multiple-keys-worklet.js içinde navigator.locks.request() kullanarak kilit isteğinde bulunabilir ve anahtarları gerektiği gibi okuyabilir ve değiştirebilirsiniz.

// modify-multiple-keys-worklet.js
class ModifyMultipleKeysOperation {
  async run(data) {
    await navigator.locks.request('modify-lock', async (lock) => {
      const value1 = await sharedStorage.get('keyOne');
      const value2 = await sharedStorage.get('keyTwo');

      // Do something with `value1` and `value2` here.

      await sharedStorage.delete('keyOne');
      await sharedStorage.delete('keyTwo');
    });
  }
}
register('modify-multiple-keys', ModifyMultipleKeysOperation);

Bağlam değiştirme

Paylaşılan Depolama verileri, çağrının kaynağı olan tarama bağlamının kökenine (ö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()'yi çağrdığında veriler, yerleştirenin 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.

Yerleştirilmiş üçüncü taraf JavaScript&#39;i içeren bir birinci taraf sayfasında depolanan veriler.

Üçü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 teknolojisinde ya da üçüncü taraf bağlamında saklanabilir.

Reklam teknolojisi veya üçüncü taraf bağlamında depolanan veriler.

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 için, paketi ve değeri içeren rapor yükü aktarma sırasında şifrelenir ve yalnızca Toplama Hizmeti kullanılarak şifresi çözülüp 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 ortak depolama alanı kullanıldığında veri bölümü 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

Kaynaklar arası iFrame kullanma

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

Reklamın iFrame'inde addModule() çağrısını 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, runasynkron bir yönteme sahip bir sınıf oluşturmanız ve register gerekir. sharedStorageWorklet.js içinde:

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 üstbilgileriyle yanıt vermesi ve istek için CORS'un etkinleştirildiğini belirtmesi gerekir.

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

createWorklet() kullanılarak oluşturulan iş parçacıklarında selectURL ve run() bulunur. addModule() bu işlem için kullanılamaz.

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.

API'leri öğrendikten sonra, istek gövdesinde JSON olarak aşağıdaki uç noktalara POST isteği olarak gönderilen raporları toplamaya başlayabilirsiniz.

  • 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.