Private Aggregation API ile ilgili temel kavramlar
Bu doküman kimler için hazırlanmıştır?
Private Aggregation API, siteler arası verilere erişimi olan iş parçacıklarından toplu veri toplamayı sağlar. Burada paylaşılan kavramlar, Shared Storage ve Protected Audience API'de raporlama işlevleri oluşturan geliştiriciler için önemlidir.
- Siteler arası raporlama sistemi oluşturan bir geliştiriciyseniz bahsedeceğim.
- Pazarlamacı, veri bilimci veya başka bir özet raporuysanız tüketici bu mekanizmaları anlamanız, size en iyi tasarımı optimize edilmiş özet raporu alma kararlarını verir.
Anahtar terimler
Bu dokümanı okumadan önce temel terimler ve kavramlarla ilgili bilgi edinmeniz faydalı olacaktır. Bu terimlerin her biri burada ayrıntılı olarak açıklanacaktır.
- Toplama anahtarı (paket olarak da bilinir) bir önceden belirlenmiş veri noktası koleksiyonudur. Örneğin, ekip arkadaşlarınızın Tarayıcının ülkeyi bildirdiği bir konum verisi paketi toplama dokunun. Toplama anahtarı birden fazla boyut içerebilir (ör. içerik widget'ınızın ülkesi ve kimliği).
- Toplanabilir değer, bir toplama anahtarında toplanan tek bir veri noktasıdır. Fransa'dan kaç kullanıcının içeriğinizi gördüğünü ölçmek istiyorsanız
France
, toplama anahtarındaki bir boyuttur ve1
içinviewCount
, toplanabilir değerdir. - Toplanabilir raporlar, bir tarayıcıda oluşturulur ve şifrelenir. Private Aggregation API'sinde tek bir etkinlikle ilgili veriler yer alır.
- Toplama Hizmeti bir özet rapor oluşturmak için toplanabilir raporlardaki verileri işler.
- Özet rapor, toplama hizmetinin nihai çıkışıdır ve gürültülü toplu kullanıcı verilerini ve ayrıntılı dönüşüm verilerini içerir.
- İş akışı, JavaScript işlevlerini çalıştırmanızı ve istek sahibine geri bilgi gönderebilir. Bir iş parçasında JavaScript'i çalıştırabilirsiniz ancak harici sayfayla etkileşime geçemez veya iletişim kuramazsınız.
Özel Toplama iş akışı
Özel Toplama API'sini bir toplama anahtarı ve birleştirilebilir bir değerle çağırdığınızda tarayıcı, birleştirilebilir bir rapor oluşturur. Raporlar raporları toplu olarak sunan sunucunuza gönderilir. Toplu raporlar daha sonra Toplama Hizmeti tarafından işlenir ve bir özet rapor oluşturulur.
- Private Aggregation API'yi çağırdığınızda, istemci (tarayıcı) ve toplanabilir raporu toplanması için sunucunuza gönderir.
- Sunucunuz istemcilerden raporları toplar ve bunları toplu hale getirir için bir e-posta alırsınız.
- Yeterli sayıda rapor topladıktan sonra, özet rapor oluşturmak için bunları gruplandırıp güvenilir bir yürütme ortamında çalışan Toplama Hizmeti'ne gönderirsiniz.
Bu bölümde açıklanan iş akışı, İlişkilendirme Raporlama API'sine benzer. Ancak İlişkilendirme, Raporlama, bir gösterim etkinliğinden ve dönüşümden toplanan verileri ilişkilendirir ve farklı zamanlarda gerçekleşen etkinliklerdir. Özel toplama, tek bir siteler arası etkinliği ölçer.
Toplama anahtarı
Toplama anahtarı ("anahtar"), toplanabilir. Bir veya daha fazla boyut kodlanabilir içine yerleştireceğiz. Boyut, daha fazla kazanmak istediğiniz bir yönü gösterir (ör. kullanıcıların yaş grubu veya bir reklamın gösterim sayısı) hakkında bilgi pek de iyi olmadığını unutmayın.
Örneğin, birden fazla siteye yerleştirilmiş bir widget'ınız olabilir ve widget'ınızı gören kullanıcıların bulunduğu ülkeyi analiz etmek isteyebilirsiniz. Baktığınız şey "Widget'ımı gören kullanıcılardan kaçı "X ülkesinden mi?" Bu soru hakkında rapor oluşturmak için toplama anahtarı oluşturabilirsiniz bir kod snippet'i ekleyin: widget kimliği ve ülke kimliği.
Private Aggregation API'ye sağlanan anahtar
BigInt,
reklam öğesidir. Bu örnekte boyutlar widget kimliği ve ülke kimliğidir. Widget kimliğinin en fazla 4 haneli olabileceğini varsayalım.
her ülke alfabetik olarak bir sayıyla eşlenir (ör. 1234
)
sırası "Afganistan 1
, Fransa 61
ve Zimbabve "195"tir.
Bu nedenle, toplanabilir anahtar 7 haneli olur. İlk 4 karakter WidgetID
için, son 3 karakter ise CountryID
için ayrılır.
Anahtarın, 3276
widget kimliğini görmüş Fransa'dan (ülke kimliği 061
) kullanıcıların sayısını temsil ettiğini varsayalım. Toplama anahtarı 3276061
olsun.
Toplama anahtarı | |
Widget kimliği | Ülke kimliği |
3276 | 061 |
Toplama anahtarı, aşağıdaki gibi bir karma oluşturma mekanizmasıyla da oluşturulabilir:
SHA-256'yı tıklayın. Örneğin, dize
{"WidgetId":3276,"CountryID":67}
için karma oluşturma işlemi uygulanabilir ve daha sonra
BigInt
değeri
42943797454801331377966796057547478208888578253058197330928948081739249096287n
.
Karma oluşturma değeri 128 bitten fazlaysa 2^128−1
olan izin verilen maksimum paket değerini aşmaması için değeri kısaltabilirsiniz.
Paylaşılan Depolama Alanı iş parçasında, karma oluşturmanıza yardımcı olabilecek crypto
ve TextEncoder
modüllerine erişebilirsiniz. Karma oluşturma hakkında daha fazla bilgi için
SubtleCrypto.digest()
açık
MDN.
Aşağıdaki örnekte, karma oluşturma işlemi uygulanmış bir değerden nasıl bir paket anahtarı oluşturabileceğiniz açıklanmaktadır:
async function convertToBucket(data) {
// Encode as UTF-8 Uint8Array
const encodedData = new TextEncoder().encode(data);
// Generate SHA-256 hash
const hashBuffer = await crypto.subtle.digest('SHA-256', encodedData);
// Truncate the hash
const truncatedHash = Array.from(new Uint8Array(hashBuffer, 0, 16));
// Convert the byte sequence to a decimal
return truncatedHash.reduce((acc, curr) => acc * 256n + BigInt(curr), 0n);
}
const data = {
WidgetId: 3276,
CountryID: 67
};
const dataString = JSON.stringify(data);
const bucket = await convertToBucket(dataString);
console.log(bucket); // 126200478277438733997751102134640640264n
Toplanabilir değer
Özet raporlarda özet değerler biçiminde toplu analizler oluşturmak için birleştirilebilir değerler, birçok kullanıcıda anahtar başına toplanır.
Şimdi, daha önce verilen örnek soruya dönelim: "Widget'ımı gören kullanıcıların kaçı Fransa'dan?" Bu sorunun yanıtı, "Widget kimliğimi 3276'yı gören yaklaşık 4.881 kullanıcı Fransa'dan." Toplanabilir değer her kullanıcı için 1 ve "4881 kullanıcı"dır. : Bu değer için tüm toplanabilir değerlerin toplamı olan toplu değer toplama anahtarı ile değiştirin.
Toplama anahtarı | Toplanabilir değer | |
Widget kimliği | Ülke kimliği | Görüntüleme Sayısı |
3276 | 061 | 1 |
Bu örnekte, widget'ı gören her kullanıcı için değeri 1 artırırız. Uygulamada, toplanabilir değer sinyal gürültü oranını iyileştirmek için ölçeklendirilebilir.
Katkı bütçesi
Private Aggregation API'ye yapılan her çağrıya katkı adı verilir. Koruma amaçlı kullanıcı gizliliği, bir web sitesinden toplanabilecek katkıların sayısı sınırlı sayıda kişiye özeldir.
Tüm toplama anahtarlarındaki tüm toplanabilir değerleri topladığınızda toplam, katkı bütçesinden az olmalıdır. Bütçe, iş akışı başına kapsama alınır origin, günlük ve Protected Audience API ve Paylaşılan Depolama işletleri için ayrı olarak. Gün için yaklaşık son 24 saati kapsayan bir kaydırmalı pencere kullanılır. Yeni bir bütçe aşılmasına neden olursa rapor, oluşturuldu.
Katkı bütçesi, L1 parametresiyle temsil edilir ve 220'lik geri bağlantıyla günde on dakikada 216 (65.536) olarak ayarlandı
(1.048.576). Bu parametreler hakkında daha fazla bilgi edinmek için açıklamayı inceleyin.
Katkı bütçesinin değeri isteğe bağlıdır, ancak gürültü buna göre ölçeklendirilir. Özet değerlerdeki sinyal-gürültü oranını artırmak için bu bütçeyi kullanabilirsiniz (Gürültü ve ölçeklendirme bölümünde daha ayrıntılı olarak ele alınmıştır).
Katkı bütçeleri hakkında daha fazla bilgi: . Ayrıca, bkz. Katkı Bütçe daha fazla bilgi için.
Rapor başına katkı sınırı
Katkı sınırı, arayana bağlı olarak farklılık gösterebilir. Şu anda, raporlar Shared Storage API arayanları için oluşturulan veri sınırı, rapor başına 20 katkıyla sınırlıdır. Öte yandan, Protected Audience API'yi çağıranlar için rapor başına 100 katkı sınırı vardır. Bu sınırlar, yerleştirilebilecek katkıların sayısı ile yükün boyutunu dengelemek için seçilmiştir.
Paylaşılan depolama alanı için tek bir run()
veya selectURL()
işleminde yapılan katkılar tek bir raporda gruplandırılır. Protected Audience için yapılan katkılar
tek bir kaynağa göre gruplandırılır.
Dolgulu katkılar
Katkılar, dolgu özelliğiyle daha da değiştirilir.
Yük, her bir e-tabloya yerleştirilmiş gerçek katkı sayısıyla ilgili bilgileri
verileri toplayabilirsiniz. Dolgu, sabit bir uzunluğa ulaşmak için yükü null
katkılarıyla (yani 0 değeriyle) artırır.
Toplanabilir raporlar
Kullanıcı Private Aggregation API'yi çağırdıktan sonra, tarayıcı
daha sonra Toplama Hizmeti tarafından işlenmek üzere toplanabilir raporlar
özeti oluşturmak için
raporları inceleyin. Toplanabilir raporlar JSON biçimindedir ve her biri {aggregation key, aggregatable value}
çifti olan şifrelenmiş bir katkı listesi içerir.
Toplanabilir raporlar, bir saate kadar rastgele bir gecikmeyle gönderilir.
Katkılar şifrelenir ve Toplama Hizmeti dışında okunamaz. Toplama Hizmeti, raporların şifresini çözer ve bir özet rapor oluşturur. İlgili içeriği oluşturmak için kullanılan için şifreleme anahtarı ve Toplama için şifre çözme anahtarı Hizmet, anahtar yönetim hizmeti görevi gören koordinatör tarafından verilir. Koordinatör, arayanın şifre çözme anahtarını almasına izin verilip verilmediğini doğrulamak için hizmet resminin ikili karmalarının bir listesini tutar.
Hata ayıklama modunun etkin olduğu örnek bir toplanabilir rapor:
"aggregation_service_payloads": [
{
"debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAE0mlvcGVyYXRpb25paGlzdG9ncmFt",
"key_id": "2cc72b6a-b92f-4b78-b929-e3048294f4d6",
"payload": "a9Mk3XxvnfX70FsKrzcLNZPy+00kWYnoXF23ZpNXPz/Htv1KCzl/exzplqVlM/wvXdKUXCCtiGrDEL7BQ6MCbQp1NxbWzdXfdsZHGkZaLS2eF+vXw2UmLFH+BUg/zYMu13CxHtlNSFcZQQTwnCHb"
}
],
"debug_key": "777",
"shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"5bc74ea5-7656-43da-9d76-5ea3ebb5fca5\",\"reporting_origin\":\"https://localhost:4437\",\"scheduled_report_time\":\"1664907229\",\"version\":\"0.1\"}"
Birleştirilebilir raporlar chrome://private-aggregation-internals
sayfasından incelenebilir:
Test amacıyla, "Seçili Raporları Gönder" düğmesi, sunucuya rapor gönderir.
Toplanabilir raporları toplama ve toplu olarak hazırlama
Tarayıcı, listelenen bilinen yolu kullanarak birleştirilebilir raporları Özel Toplama API'sine yapılan çağrıyı içeren çalışma aletinin kaynağına gönderir:
- Ortak Depolama için:
/.well-known/private-aggregation/report-shared-storage
- Korunan kitle için:
/.well-known/private-aggregation/report-protected-audience
.
Bu uç noktalarda, istemcilerden gönderilen birleştirilebilir raporları alan bir toplayıcı görevi gören bir sunucu çalıştırmanız gerekir.
Ardından sunucu, raporları toplu hale getirmeli ve grubu Toplama'ya göndermelidir.
Hizmet. Şifrelenmemiş dosyadaki bilgilere dayalı olarak gruplar oluştur
shared_info
alanı gibi toplanabilir raporun yükü. İdeal olarak, gruplar grup başına 100 veya daha fazla rapor içermelidir.
Gruplandırma işlemini günlük veya haftalık olarak yapabilirsiniz. Bu strateji esnektir ve daha fazla hacim beklediğiniz belirli etkinlikler (ör. yılın daha fazla gösterim beklendiği günler) için gruplandırma stratejinizi değiştirebilirsiniz. Gruplar, aynı API sürümünden, raporlama kaynağından ve planlanmış rapor zamanından raporlar içermelidir.
Aggregation Service
Toplama Hizmeti, toplayıcıdan şifrelenmiş toplanabilir raporlar alır ve özet raporlar oluşturur.
Toplama Hizmeti, rapor yükünün şifresini çözmek için bir şifre çözme anahtarı getirir koordinatörden geliyor. Hizmet, güvenilir yürütme ortamında (TEE) çalışır. veri bütünlüğü, veri gizliliği, gizliliğin korunduğu ve yardımcı olur. Hizmetin sahibi ve yöneticisi olmanıza rağmen, verilerin TEE içinde işlenen verilere ulaşmasını sağlar.
Özet raporlar
Özet raporlar topladığınız verileri gürültü eklenmiş halde görmenizi sağlar. Belirli bir anahtar grubu için özet raporlar isteyebilirsiniz.
Özet rapor, JSON sözlük stili anahtar/değer çiftleri kümesi içerir. Her biri çift şunları içerir:
bucket
: İkili sayı dizesi olarak toplama anahtarı. Kullanılan toplama anahtarı "123" ise paket "1111011" olur.value
: Belirli bir ölçüm hedefinin özet değeri. Mevcut tüm toplanabilir raporlardan toplanır ve gürültü eklenir.
Örneğin:
[
{"bucket":` `"111001001",` `"value":` `"2558500"},
{"bucket":` `"111101001",` `"value":` `"3256211"},
{"bucket":` `"111101001",` `"value":` `"6536542"},
]
Gürültü ve ölçeklendirme
Kullanıcı gizliliğini korumak için, Toplama Hizmeti her dosyaya bir kez gürültü ekler özet değerinin toplamıdır. Gürültü değerleri: Laplace olasılığından rastgele alınır dağıtım. Gürültünün eklenme yöntemlerini doğrudan kontrol edemeseniz de gürültünün ölçüm verileri üzerindeki etkisini etkileyebilirsiniz.
Gürültü dağılımı, toplanabilir tüm verilerin toplamından bağımsız olarak aynıdır değerler. Bu nedenle, toplanabilir değerler ne kadar yüksek olursa varyansın etkisi o kadar az olur.
Örneğin, gürültü dağılımının standart sapmasının 100 olduğunu varsayalım. merkezde sıfır olarak görünür. Toplanan birleştirilebilir rapor değeri (veya "birleştirilebilir değer") yalnızca 200 ise gürültünün standart sapması, birleştirilmiş değerin %50'si olur. Ancak toplanabilir değer 20.000 ise gürültünün standart sapması, toplam değerin yalnızca% 0,5'i olur. Dolayısıyla, 20.000'lik bir değer ise çok daha yüksek bir sinyal-gürültü oranına sahip olacaktır.
Bu nedenle, toplanabilir değerinizi bir ölçeklendirme faktörüyle çarpmanız, gürültüyü azaltın. Ölçeklendirme faktörü, belirli bir ölçeği ne kadar bir değer atfedilebilir.
Daha büyük bir ölçeklendirme faktörü seçerek değerleri büyütmek, göreceli gürültüyü azaltır. Ancak bu, tüm gruplardaki tüm katkıların toplamına da neden olur. . Daha küçük bir ölçeklendirme faktörü sabit değeri seçerek değerleri küçültmek, göreceli gürültüyü artırır ancak bütçe sınırına ulaşma riskini azaltır.
Uygun bir ölçeklendirme faktörü hesaplamak için katkı bütçesini Tüm anahtarlar genelindeki toplanabilir değerlerin maksimum toplamı.
Daha fazla bilgi için Katkı bütçesi dokümanlarına bakın.
Etkileşim kurma ve geri bildirim paylaşma
Private Aggregation API aktif olarak tartışılmakta olup gelecekte değişikliğe tabi olabilir. Bu API'yi denedikten sonra geri bildiriminiz olursa bizimle paylaşın.
- GitHub: açıklayıcı, sorular sorup tartışma. * Geliştirici desteği: Özel Korumalı Alan Geliştirici Desteği reposunda soru sorabilir ve tartışmalara katılabilirsiniz. * Gizli toplama ile ilgili en son duyurular için Shared Storage API grubuna ve Protected Audience API grubuna katılın.