Private Aggregation API'nin temelleri

Private Aggregation API'nin temel kavramları

Bu belge kimler için hazırlanmıştır?

Private Aggregation API, siteler arası verilere erişimi olan işlevletlerden toplu veri toplanmasını 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ı ö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 rapor almak için tasarım kararları vermenize yardımcı olur.

Anahtar terimler

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

• Toplama anahtarı (diğer adıyla grup), önceden belirlenmiş bir veri noktaları koleksiyonudur. Örneğin, tarayıcının ülke adını bildirdiği bir konum verileri grubu toplamak isteyebilirsiniz. Bir toplama anahtarı birden fazla boyut içerebilir (örneğin, ülke ve içerik widget'ınızın kimliği).
• Toplanabilir değer, bir toplama anahtarı içinde toplanan tek 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 boyuttur ve 1'nin viewCount değeri, toplanabilir değerdir.
• Toplanabilir raporlar tarayıcıda oluşturulur ve şifrelenir. Private Aggregation API için bu, tek bir etkinlikle ilgili verileri içerir.
• Toplama Hizmeti, özet rapor oluşturmak için toplanabilir raporlardaki verileri işler.
• Özet rapor, Aggregation Service'in nihai çıktısıdır ve gürültülü birleştirilmiş kullanıcı verileri ile ayrıntılı dönüşüm verilerini içerir.
• Worklet, belirli JavaScript işlevlerini çalıştırmanıza ve bilgileri istekte bulunan kişiye geri göndermenize olanak tanıyan bir altyapı parçasıdır. Bir iş birimi içinde JavaScript'i çalıştırabilirsiniz ancak dış sayfayla etkileşim kuramaz veya iletişimde bulunamazsınız.

Private Aggregation iş akışı

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

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

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

Toplama anahtarı

Toplama anahtarı (kısaca "anahtar"), toplanabilir değerlerin biriktirileceği grubu temsil eder. Anahtara bir veya daha fazla boyut kodlanabilir. Boyut, hakkında daha fazla bilgi edinmek istediğiniz bir yönü (ör. kullanıcıların yaş grubu veya bir reklam kampanyasının gösterim sayısı) temsil eder.

Örneğin, birden fazla siteye yerleştirilmiş bir widget'ınız olabilir ve widget'ınızı gören kullanıcıların ülkesini analiz etmek isteyebilirsiniz. "Widget'ımı gören kullanıcıların kaçı X ülkesinden?" gibi soruları yanıtlamak istiyorsunuz. Bu soruyla ilgili rapor oluşturmak için iki boyutu (widget kimliği ve ülke kimliği) kodlayan bir toplama anahtarı ayarlayabilirsiniz.

Private Aggregation API'ye sağlanan anahtar, birden fazla boyuttan oluşan bir BigInt'tir. Bu örnekte boyutlar, widget kimliği ve ülke kimliğidir. Widget kimliğinin 1234 gibi en fazla 4 haneli olabileceğini ve her ülkenin alfabetik sıraya göre bir sayıyla eşlendiğini (ör. Afganistan 1, Fransa 61, Zimbabve 195) varsayalım. 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, Fransa'daki (ülke kimliği 061) ve 3276 kimlikli widget'ı görmüş kullanıcıların sayısını temsil ettiğini varsayalım. Toplama anahtarı 3276061 olur.

Toplama anahtarı, SHA-256 gibi bir karma oluşturma mekanizmasıyla da oluşturulabilir. Örneğin, {"WidgetId":3276,"CountryID":67} dizesi karma oluşturma işlemine tabi tutulabilir ve ardından 42943797454801331377966796057547478208888578253058197330928948081739249096287n değerine dönüştürülebilir.BigInt Karma değer 128 bit'ten fazlaysa 2^128−1 olan izin verilen maksimum paket değerini aşmaması için değeri kesebilirsiniz.

Bir Shared Storage işlevinde, karma oluşturmanıza yardımcı olabilecek crypto ve TextEncoder modüllerine erişebilirsiniz. Karma oluşturma hakkında daha fazla bilgi edinmek için SubtleCrypto.digest() on MDN başlıklı makaleyi inceleyin.

Aşağıdaki örnekte, karma oluşturulmuş 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

Toplanabilir değer

Toplanabilir değerler, özet raporlardaki özet değerleri şeklinde toplu analizler oluşturmak için birçok kullanıcı arasında anahtar başına toplanır.

Şimdi, daha önce sorulan örnek soruya dönelim: "Widget'ımı gören kullanıcıların kaçı Fransa'dan?" Bu sorunun cevabı "3276 numaralı widget kimliğimi gören yaklaşık 4.881 kullanıcı Fransa'dan." şeklinde olacaktır. Toplanabilir değer her kullanıcı için 1'dir ve "4.881 kullanıcı", söz konusu toplama anahtarı için tüm toplanabilir değerlerin toplamı olan toplanan değerdir.

Bu örnekte, widget'ı gören her kullanıcı için değeri 1 artırıyoruz. Uygulamada, sinyal-gürültü oranını iyileştirmek için toplanabilir değer ölçeklendirilebilir.

Katkı bütçesi

Private Aggregation API'ye yapılan her çağrıya katkı adı verilir. Kullanıcı gizliliğini korumak için bir kullanıcıdan toplanabilecek katkı sayısı sınırlıdır.

Tüm toplama anahtarlarındaki tüm toplanabilir değerleri topladığınızda toplam, katkı bütçesinden küçük olmalıdır. Bütçe, iş akışı kaynağı başına ve günlük olarak belirlenir. Protected Audience API ve Shared Storage iş akışları için ayrıdır. Gün için yaklaşık son 24 saatlik bir hareketli pencere kullanılır. Yeni bir toplanabilir rapor, bütçenin aşılmasına neden oluyorsa rapor oluşturulmaz.

Katkı bütçesi, L₁ parametresiyle gösterilir ve günlük on dakikada bir 2¹⁶ (65.536) olarak ayarlanır. Bu değerin üst sınırı 2²⁰ (1.048.576) olarak belirlenir. Bu parametreler hakkında daha fazla bilgi edinmek için açıklayıcı makaleye bakın.

Katkı bütçesinin değeri rastgeledir ancak gürültü buna göre ölçeklendirilir. Bu bütçeyi, özet değerlerdeki 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çıklama bölümüne bakın. Daha fazla bilgi için Katkı Bütçesi bölümüne de göz atın.

Rapor başına katkı sınırı

Katkı sınırı, arayana bağlı olarak değişebilir. Paylaşılan Depolama Alanı'nda bu sınırlar, geçersiz kılınabilen varsayılan sınırlardır. Şu anda, Shared Storage API çağrıları için oluşturulan raporlar, rapor başına 20 katkı ile sınırlıdır. Öte yandan, Protected Audience API arayanlar rapor başına 100 katkıyla sınırlıdır. Bu sınırlar, yerleştirilebilecek katkı sayısı ile yükün boyutu arasında denge kurmak için belirlenmiştir.

Paylaşılan Depolama Alanı için tek bir run() veya selectURL() işlemi içinde yapılan katkılar tek bir raporda gruplandırılır. Protected Audience için, bir açık artırmada tek bir kaynak tarafından yapılan katkılar birlikte gruplandırılır.

Dolgulu katkılar

Katkılar, dolgu özelliğiyle daha da değiştirilir. Yükü doldurma işlemi, toplanabilir rapora yerleştirilmiş gerçek katkı sayısı hakkındaki bilgileri korur. 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ığında tarayıcı, özet raporlar oluşturmak için daha sonra Toplama Hizmeti tarafından işlenecek toplu raporlar oluşturur. Toplanabilir rapor, JSON biçimlidir 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. Tarayıcının şifreleme anahtarı ve Aggregation Service'in şifre çözme anahtarı, anahtar yönetim hizmeti olarak hareket eden koordinatör tarafından verilir. Koordinatör, arayanı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 bir listesini tutar.

Hata ayıklama modu etkinleştirilmiş bir örnek 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\"}"

Toplanabilir raporlar, chrome://private-aggregation-internals sayfasından incelenebilir:

Test amacıyla, raporu sunucuya hemen göndermek için "Seçili Raporları Gönder" düğmesi kullanılabilir.

Toplanabilir raporları toplama ve toplu işleme

Tarayıcı, Private Aggregation API çağrısını içeren worklet'in kaynağına, bilinen yolları kullanarak toplu raporlar gönderir:

• Shared Storage için: /.well-known/private-aggregation/report-shared-storage
• Protected Audience için: /.well-known/private-aggregation/report-protected-audience

Bu uç noktalarda, istemcilerden gönderilen toplanabilir raporları alan bir toplayıcı görevi gören bir sunucu çalıştırmanız gerekir.

Sunucu daha sonra raporları gruplandırmalı ve grubu Toplama Hizmeti'ne göndermelidir. Toplanabilir raporun şifrelenmemiş yükünde bulunan bilgilere (ör. shared_info alanı) göre toplu işlemler oluşturun. İdeal olarak, gruplar grup başına 100 veya daha fazla rapor içermelidir.

Günlük veya haftalık olarak gruplandırmaya karar verebilirsiniz. Bu strateji esnektir ve daha fazla hacim beklediğiniz belirli etkinlikler için toplu işleme stratejinizi değiştirebilirsiniz. Örneğin, yılın daha fazla gösterim beklenen günleri. Toplu işlemler aynı API sürümü, raporlama kaynağı ve rapor zamanlaması zamanından raporları içermelidir.

Filtre kimlikleri

Private Aggregation API ve Aggregation Service, sonuçları daha büyük sorgularda işlemek yerine reklam kampanyası başına gibi daha ayrıntılı bir düzeyde işlemek için filtreleme kimliklerinin kullanılmasına olanak tanır.

Bu özelliği bugün kullanmaya başlamak için mevcut uygulamanıza uygulayabileceğiniz bazı genel adımları aşağıda bulabilirsiniz.

Shared Storage adımları

Akışınızda Shared Storage API kullanıyorsanız:

1. Yeni Shared Storage modülünüzü nerede bildireceğinizi ve çalıştıracağınızı tanımlayın. Aşağıdaki örnekte, filtering-example altında kaydedilen modül dosyasına filtering-worklet.js adını verdik.

   (async function runFilteringIdsExample () {
   await window.sharedStorage.worklet.addModule('filtering-worklet.js');
   await window.sharedStorage.run('filtering-example', {
     keepAlive: true,
     privateAggregationConfig: {
       contextId: 'example-id',
       filteringIdMaxBytes: 8 // optional
     }
   }});
   })();
   

   filteringIdMaxBytes değerinin rapor başına yapılandırılabilir olduğunu ve ayarlanmamışsa varsayılan olarak 1 olduğunu unutmayın. Bu varsayılan değer, yük boyutunun ve dolayısıyla depolama ve işleme maliyetlerinin gereksiz yere artmasını önlemek için kullanılır. Esnek katkı açıklayıcı başlıklı makaleden daha fazla bilgi edinebilirsiniz.

2. filtering-worklet.js içinde, Shared Storage işleti aracılığıyla privateAggregation.contributeToHistogram(...)'ye katkı iletirken filtreleme kimliği belirtebilirsiniz.

   // Within  filtering-worklet.js
   class FilterOperation {
     async run() {
       let contributions = [{
         bucket: 1234n,
         value: 56,
         filteringId: 3n // defaults to 0n if not assigned, type bigint
       }];
   
       for (const c of contributions) {
         privateAggregation.contributeToHistogram(c);
       }
       …
   }
   });
   
   register('filtering-example', FilterOperation);
   

3. Toplanabilir raporlar, uç noktayı tanımladığınız yere gönderilir /.well-known/private-aggregation/report-shared-storage. Toplama Hizmeti iş parametrelerinde yapılması gereken değişiklikler hakkında bilgi edinmek için filtreleme kimlikleri kılavuzuna geçin.

Toplama işlemi tamamlanıp dağıtılan Toplama Hizmetinize gönderildikten sonra, filtrelenmiş sonuçlarınız nihai özet raporunuza yansıtılmalıdır.

Protected Audience adımları

Akışınızda Protected Audience API'yi kullanıyorsanız:

1. Protected Audience'ın mevcut uygulamanızda, Private Aggregation'a bağlanmak için aşağıdakileri ayarlayabilirsiniz. Paylaşılan Depolama'nın aksine, filtreleme kimliğinin maksimum boyutu henüz yapılandırılamaz. Varsayılan olarak, filtreleme kimliği maksimum boyutu 1 bayttır ve 0n olarak ayarlanır. Bunların Protected Audience raporlama işlevlerinizde (ör.reportResult() veya generateBid()) ayarlanacağını unutmayın.

   const contribution = {
     ...
     filteringId: 0n
   };
   
   privateAggregation.contributeToHistogram(contribution);
   

2. Toplanabilir raporlar, uç noktayı tanımladığınız yere gönderilir /.well-known/private-aggregation/report-protected-audience. Gruplandırma işlemi tamamlanıp dağıtılan toplama hizmetinize gönderildikten sonra, filtrelenmiş sonuçlarınız nihai özet raporunuza yansıtılır. Attribution Reporting API ve Private Aggregation API ile ilgili aşağıdaki açıklayıcıların yanı sıra ilk teklif de mevcuttur.

Daha ayrıntılı bilgi için Toplama Hizmeti'ndeki filtreleme kimlikleri kılavuzumuza gidin veya ilişkilendirme raporlama API'si bölümlerini inceleyin.

Aggregation Service

Toplama Hizmeti, toplayıcıdan şifrelenmiş toplama yapılabilir raporlar alır ve özet raporlar oluşturur. Toplayıcınızdaki toplu toplama raporlarının nasıl oluşturulacağıyla ilgili diğer stratejiler için toplu işleme kılavuzumuza bakın.

Hizmet, veri bütünlüğü, veri gizliliği ve kod bütünlüğü konusunda güvence sağlayan güvenilir bir yürütme ortamında (TEE) çalışır. Koordinatörlerin TEE'lerle birlikte nasıl kullanıldığına daha yakından bakmak isterseniz rolleri ve amaçları hakkında daha fazla bilgi edinin.

Özet raporlar

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

Özet rapor, anahtar/değer çiftlerinden oluşan JSON sözlüğü tarzında bir küme içerir. Her çiftte şunlar bulunur:

• bucket: İkili sayı dizesi olarak toplama anahtarı. Kullanılan toplama anahtarı "123" ise grup "1111011" olur.
• value: Belirli bir ölçüm hedefinin özet değeri. Gürültü eklenmiş, kullanılabilir tüm toplanabilir raporlardan toplanır.

Örneğin:

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

Gürültü ve ölçeklendirme

Aggregation Service, kullanıcı gizliliğini korumak için bir özet raporu her istendiğinde her özet değerine bir kez gürültü ekler. Gürültü değerleri, Laplace olasılık dağılımından rastgele alınır. Gürültünün eklenme şekilleri üzerinde doğrudan kontrolünüz olmasa da gürültünün ölçüm verileri üzerindeki etkisini azaltabilirsiniz.

Gürültü dağılımı, toplanabilir tüm değerlerin toplamından bağımsız olarak aynıdır. 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 ve sıfırda merkezlendiğini 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ı yalnızca toplanan değerin% 0,5'i olur. Bu nedenle, 20.000'lik toplanabilir değerin sinyal-gürültü oranı çok daha yüksek olur.

Bu nedenle, toplanabilir değerinizi bir ölçeklendirme faktörüyle çarpmak gürültüyü azaltmaya yardımcı olabilir. Ölçeklendirme faktörü, belirli bir toplanabilir değeri ne kadar ölçeklendirmek istediğinizi gösterir.

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

Daha fazla bilgi edinmek için Katkı bütçesi dokümanlarına göz atın.

Etkileşim kurma ve geri bildirim paylaşma

Private Aggregation API aktif olarak tartışılmaktadır ve gelecekte değişebilir. Bu API'yi denerseniz geri bildiriminizi bizimle paylaşmanızı rica ederiz.

• GitHub: Açıklamayı okuyun, soru sorun ve tartışmaya katılın.
  • Geliştirici desteği: Privacy Sandbox Developer Support repo'da soru sorun ve tartışmalara katılın.
• Private Aggregation ile ilgili en son duyurular için Shared Storage API grubuna ve Protected Audience API grubuna katılın.