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ıyorfetch("https://a.example/path/for/updates", {sharedStorageWritable: true});
iframe
veyaimg
etiketi kullanma<iframe src="https://a.example/path/for/updates" sharedstoragewritable></iframe>
iframe
veyaimg
etiketiyle IDL özelliği kullanmalet 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
veclear
öğ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.

Üçü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.

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, run
asynkron 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.
- Paylaşılan Depolama Alanına Giriş (Geliştirici Chrome)
- Ortak Depolama Alanının Kullanım Alanları (Geliştirici Chrome)
- Gizli toplama hakkında (Geliştirici Chrome)
- Paylaşılan Depolama Alanı Açıklayıcısı (GitHub)
- Private Aggregation Explainer (GitHub)
- Ortak Depolama Alanı ve Özel Toplama Demo'su
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.