Private Aggregation API'nin temelleri

Private Aggregation API ile ilgili temel kavramlar

Bu doküman kimin için?

Private Aggregation API, siteler arası verilere erişimi olan iş akışlarından birleştirilmiş veri toplamayı etkinleştirir. Burada paylaşılan kavramlar, Shared Storage ve Protected Audience API'de raporlama işlevleri oluşturan geliştiriciler için önemlidir.

• Siteler arası ölçüm için raporlama sistemi oluşturan bir geliştiriciyseniz.
• Pazarlamacı, veri bilimci veya başka bir özet rapor tüketicisiyseniz, bu mekanizmaları anlamak, optimize edilmiş bir özet raporu almak için tasarım kararları almanıza yardımcı olacaktır.

Anahtar terimler

Bu belgeyi okumadan önce temel terimler ve kavramlar hakkında bilgi edinmeniz yararlı olacaktır. Bu terimlerin her biri burada ayrıntılı olarak açıklanmaktadır.

• Toplama anahtarı (paket olarak da bilinir), önceden belirlenmiş bir veri noktası koleksiyonudur. Örneğin, tarayıcının ülke adını bildirdiği bir konum verisi grubu toplamak isteyebilirsiniz. Toplama anahtarı birden fazla boyut içerebilir (örneğin, içerik widget'ınızın ülkesi ve kimliği).
• Toplanabilir değer, toplama anahtarında toplanan bağımsız bir veri noktasıdır. İçeriğinizi Fransa'dan kaç kullanıcının gördüğünü ölçmek istiyorsanız France, toplama anahtarındaki bir boyut, 1 özelliğinin viewCount değeri ise toplanabilir değerdir.
• Toplanabilir raporlar bir tarayıcı içinde oluşturulup şifrelenir. Bu, Private Aggregation API için tek bir etkinlikle ilgili verileri içerir.
• Toplama Hizmeti, özet rapor oluşturmak için toplanabilir raporlardaki verileri işler.
• Özet raporu, Toplama Hizmeti'nin son çıktısıdır ve gürültüyle toplanmış kullanıcı verileri ile ayrıntılı dönüşüm verilerini içerir.
• İş uygulaması, belirli JavaScript işlevlerini çalıştırmanızı ve bilgileri istek sahibine geri vermenizi sağlayan bir altyapı parçasıdır. İş uygulamasında JavaScript'i çalıştırabilirsiniz, ancak dış sayfayla etkileşimde bulunamaz veya iletişim kuramazsınız.

Gizli Toplama iş akışı

Private Aggregation API'yi bir toplama anahtarı ve toplanabilir değerle çağırdığınızda tarayıcı, toplanabilir bir rapor oluşturur. Raporlar, raporları gruplandırmak üzere sunucunuza gönderilir. Toplu raporlar daha sonra Toplama Hizmeti tarafından işlenir ve özet rapor oluşturulur.

1. Private Aggregation API'yi çağırdığınızda istemci (tarayıcı) toplanabilir raporu oluşturur ve toplanmak üzere sunucunuza gönderir.
2. Sunucunuz, istemcilerden raporları toplar ve Toplama Hizmeti'ne gönderilmeleri için gruplandırır.
3. Yeterli sayıda rapor topladıktan sonra, bunları toplu olarak oluşturup güvenilir bir yürütme ortamında çalışan Toplama Hizmeti'ne göndererek bir özet raporu oluşturursunuz.

Anahtar terim: güvenilir yürütme ortamı, bilgisayar donanım ve yazılımlarının özel bir yapılandırmasıdır. Bu yapılandırma, harici tarafların bilgisayardaki yazılımın tam sürümlerini doğrulamasını sağlar. TEE'ler, harici tarafların yazılımın tam olarak yazılım üreticisinin iddia ettiği şeyi yaptığını doğrulamasına olanak tanır. Aksine, artımlılık etkisi yoktur.

Bu bölümde açıklanan iş akışı Attribution Reporting API'ye benzer. Ancak İlişkilendirme Raporlama, bir gösterim etkinliğinden ve farklı zamanlarda gerçekleşen bir dönüşüm etkinliğinden toplanan verileri ilişkilendirir. Gizli Toplama, siteler arası tek bir etkinliği ölçer.

Toplama anahtarı

Toplama anahtarı ("anahtar"), toplanabilir değerlerin toplanacağı paketi temsil eder. Bir veya daha fazla boyut anahtara kodlanabilir. Boyut, kullanıcıların yaş grubu veya bir reklam kampanyasının gösterim sayısı gibi hakkında daha fazla bilgi edinmek istediğiniz bir unsuru temsil eder.

Ö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. "Widget'ımı gören kullanıcıların kaçı X ülkesinden geliyor?" Bu soru hakkında rapor oluşturmak için iki boyutu kodlayan bir toplama anahtarı oluşturabilirsiniz: widget kimliği ve ülke kimliği.

Private Aggregation API'ye sağlanan anahtar, birden çok boyuttan oluşan bir BigInt'tir. Bu örnekte boyutlar widget kimliği ve ülke kimliğidir. Widget kimliğinin en fazla 4 basamak uzunluğunda olabileceğini varsayalım (1234 gibi). Her ülke alfabetik sırayla bir sayıyla eşlenir. Örneğin, Afganistan 1, Fransa 61 ve Zimbabve "195"tir. Bu nedenle, toplanabilir anahtar 7 rakam uzunluğunda olur. İlk 4 karakter WidgetID, son 3 karakter ise CountryID için ayrılmıştır.

Bu anahtarın, Fransa'dan (ülke kimliği 061) widget kimliğini 3276 gören kullanıcıların sayısını temsil ettiğini varsayalım. Toplama anahtarı 3276061 şeklindedir.

Toplama anahtarı
Widget kimliği	Ülke kimliği
3276	061

Örnek: Bir boyutta birden fazla basamak için anahtar alanı varsa ancak değer daha azsa baştaki sıfırları ekleyin. Örneğin, ülke kimliği 3 haneliyse Cezayir'in ülke kimliği 003 olur.

Toplama anahtarı, SHA-256 gibi bir karma oluşturma mekanizması ile de oluşturulabilir. Örneğin, {"WidgetId":3276,"CountryID":67} dizesine karma oluşturma işlemi uygulanabilir ve ardından BigInt, 42943797454801331377966796057547478208888578253058197330928948081739249096287n değerine dönüştürülebilir. Karma değeri 128 bitten fazlaysa 2^128−1 olan izin verilen maksimum paket değerini aşmaması için karma değerini kısaltabilirsiniz.

Paylaşılan Depolama iş uygulaması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 MDN'de SubtleCrypto.digest() bölümüne göz atın.

Aşağıdaki örnekte, karma oluşturma işlemi uygulanmış bir değerden nasıl 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

Not: Kavramlar benzer olsa da anahtar, Private Aggregation API için Attribution Reporting API'den farklı şekilde oluşturulur. Özel Toplama için anahtarın tamamı, JavaScript çağrısında tek seferde belirtilir.

Toplanabilir değer

Toplanabilir değerler, birçok kullanıcı genelinde anahtar başına toplanır ve özet raporlarında özet değerler biçiminde birleştirilmiş analizler oluşturur.

Şimdi, önceden sunulan örnek soruya geri dönün: "Widget'ımı gören kullanıcıların kaçı Fransa'dan?" Bu sorunun yanıtı şöyle bir şey olacaktır: "3276 numaralı widget kimliğimi gören yaklaşık 4881 kullanıcı Fransa'dandır." toplanabilir değer her kullanıcı için 1'dir ve "4881 kullanıcı" ise söz konusu toplama anahtarı için tüm toplanabilir değerlerin toplamı olan toplu değerdir.

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ıyoruz. Pratikte, birleştirilebilir 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. Kullanıcı gizliliğini korumak amacıyla, bir kişiden toplanabilecek katkı sayısı sınırlıdır.

Tüm toplama anahtarlarındaki tüm toplanabilir değerlerin toplamı, katkı bütçesinden küçük olmalıdır. Bütçe, günlük kaynak başına belirlenir ve Protected Audience API ile Paylaşılan Depolama iş uygulamaları için ayrıdır. Gün için, yaklaşık son 24 saatlik kayan bir zaman aralığı kullanılır. Yeni bir toplanabilir rapor bütçenin aşılmasına neden olacaksa rapor oluşturulmaz.

Katkı bütçesi, L₁ parametresiyle temsil edilir ve arka uç değeri 2²⁰ olacak şekilde günde on dakikada 2¹⁶ (65.536) olarak ayarlanır.

(1.048.576). Bu parametreler hakkında daha fazla bilgi edinmek için açıklayıcıya bakın.

Katkı bütçesinin değeri rastgeledir ancak gürültü buna göre ölçeklendirilir. Bu bütçeyi, özet değerlerde sinyal-gürültü oranını en üst düzeye çıkarmak için kullanabilirsiniz (Gürültü ve ölçeklendirme bölümünde daha ayrıntılı olarak açıklanmıştır).

Katkı bütçeleri hakkında daha fazla bilgi edinmek için açıklamaya bakın. Daha fazla bilgi için Katkı Bütçesi bölümünü de inceleyebilirsiniz.

Birleştirilebilir raporlar

Kullanıcı Private Aggregation API'yi çağırdıktan sonra tarayıcı, özet raporları oluşturmak için daha sonra Toplama Hizmeti tarafından işlenmek üzere toplanabilir raporlar oluşturur. Toplanabilir rapor JSON biçimindedir ve her biri {aggregation key, aggregatable value} çifti olmak üzere ş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. Tarayıcı için şifreleme anahtarı ve Toplama Hizmeti için şifre çözme anahtarı, anahtar yönetim hizmeti olarak görev yapan koordinatör tarafından verilir. Koordinatör, çağrı yapanın şifre çözme anahtarını almasına izin verildiğini doğrulamak için hizmet görüntüsünün ikili karmalarının listesini tutar.

Hata ayıklama modunun etkin olduğu birleştirilmiş bir rapor örneği:

  "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çilen Raporları Gönder" düğmesi, raporu sunucuya hemen göndermek için kullanılabilir.

Birleştirilebilir raporları toplayın ve gruplayın

Tarayıcı, listelenen iyi bilinen yolu kullanarak, toplanabilir raporları Private Aggregation API'ye yapılan çağrıyı içeren iş kümesinin kaynağına gönderir:

• Paylaşılan Depolama Alanı İç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 toplanabilir raporları alan bir sunucu (toplayıcı görevi gören) çalıştırmanız gerekir.

Ardından sunucu, raporları toplu hale getirmeli ve grubu Toplama Hizmeti'ne göndermelidir. Birleştirilebilir raporun şifrelenmemiş yükünde bulunan, shared_info alanı gibi bilgileri temel alarak gruplar oluşturun. İdeal olarak, grupların grup başına 100 veya daha fazla rapor içermesi gerekir.

Gruplandırmayı günlük veya haftalık olarak yapabilirsiniz. Bu strateji esnektir ve örneğin yılın daha fazla gösterim beklendiği günleri gibi daha fazla hacim beklediğiniz belirli etkinlikler için toplu işlem stratejinizi değiştirebilirsiniz. Gruplar, aynı API sürümüne ait raporları, raporlama kaynağını ve rapor zamanını planlamalıdır.

Toplama Hizmeti

Toplama Hizmeti, toplayıcıdan şifrelenmiş ve birleştirilmiş raporlar alır ve özet raporlar oluşturur.

Toplama Hizmeti, rapor yükünün şifresini çözmek için koordinatörden bir şifre çözme anahtarı getirir. Hizmet, veri bütünlüğü, veri gizliliği ve kod bütünlüğü için üst düzey güvence sağlayan güvenilir yürütme ortamında (TEE) çalışır. Hizmetin sahibi ve yöneticisi siz olsanız da, TEE içinde işlenen verileri göremezsiniz.

Özet raporlar

Özet raporları, gürültü eklenmiş halde topladığınız verileri görmenizi sağlar. Belirli bir anahtar grubu için özet raporu isteyebilirsiniz.

Özet rapor, JSON sözlüğü stilinde bir anahtar/değer çifti kümesi içerir. Her ç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 gürültü eklenmiş tüm toplanabilir raporlardan toplanan özet değeridir.

Örneğin:

[
  {"bucket":` `"111001001",` `"value":` `"2558500"},
  {"bucket":` `"111101001",` `"value":` `"3256211"},
  {"bucket":` `"111101001",` `"value":` `"6536542"},
]

Gürültü ve ölçeklendirme

Toplama Hizmeti, kullanıcı gizliliğini korumak için her özet raporu talep edildiğinde her özet değerine bir kez gürültü ekler. Gürültü değerleri, rastgele bir şekilde yer değiştirme olasılığı dağılımından alınır. Gürültünün nasıl eklendiği konusunda doğrudan kontrol sizde olmasa da gürültünün ölçüm verileri üzerindeki etkisini etkileyebilirsiniz.

Gürültü dağılımı, tüm toplanabilir değerlerin toplamı ne olursa olsun aynıdır. Bu nedenle, toplanabilir değerler ne kadar yüksek olursa gürültünün etkisi de o kadar az olur.

Örneğin, gürültü dağılımının standart sapmasının 100 olduğunu ve merkezde sıfır olduğunu varsayalım. Toplanan toplanabilir rapor değeri (veya "toplanabilir değer") yalnızca 200 ise gürültünün standart sapması, toplanan 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 değerindeki toplanabilir değer çok daha yüksek bir sinyal-gürültü oranına sahip olur.

Bu nedenle, toplanabilir değerinizi bir ölçeklendirme faktörüyle çarparak gürültüyü azaltabilirsiniz. Ölçeklendirme faktörü, belirli bir toplanabilir değeri ne kadar ölçeklendirmek istediğinizi temsil eder.

Daha büyük bir ölçeklendirme faktörü seçerek değerleri ölçeklendirmek göreli gürültüyü azaltır. Ancak bu durum aynı zamanda tüm paketlerdeki tüm katkıların toplamının, katkı bütçesi sınırına daha hızlı ulaşmasına neden olur. Daha küçük bir ölçeklendirme faktörü sabiti seçerek değerleri ölçeklendirmek göreli 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ünü hesaplamak için katkı bütçesini, tüm anahtarlar genelinde toplanabilir değerlerin maksimum toplamına bölün.

Daha fazla bilgi edinmek için Katkı bütçesi belgelerine bakın.

Etkileşimde bulunun ve geri bildirim paylaşın

Private Aggregation API şu anda etkin olarak tartışılmaktadır ve ileride değiştirilebilir. Bu API'yi deneyip geri bildirimde bulunursanız memnuniyet duyarız.

• GitHub: Açıklama belgesini okuyun, soruları sorun ve tartışmalara katılın. * Geliştirici desteği: Özel Korumalı Alan Geliştirici Desteği deposunda sorular sorun ve tartışmalara katılın. * Gizli Toplama ile ilgili en son duyurular için Shared Storage API grubuna ve Protected Audience API grubuna katılın.