Private Aggregation API'nin temelleri

Private Aggregation API'nin 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ı ölçüm için bir raporlama sistemi oluşturan bir geliştiriciyseniz.
• Pazarlamacı, veri bilimcisi veya başka bir özet rapor kullanıcısıysanız bu mekanizmaları anlamak, optimize edilmiş bir özet rapor almak için tasarım kararları almanıza yardımcı olur.

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ı (grup 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 (ö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 ve 1 için viewCount, toplanabilir değerdir.
• Toplanabilir raporlar bir 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 birleştirilebilir raporlardaki verileri işler.
• Özet rapor, Toplama Hizmeti'nin nihai çıkışıdır ve gürültülü birleştirilmiş kullanıcı verilerini ve ayrıntılı dönüşüm verilerini içerir.
• İş parçası, belirli JavaScript işlevlerini çalıştırmanıza ve bilgileri istek sahibine döndürmenize olanak tanıyan bir altyapı parçasıdır. Bir iş parçasında JavaScript'i çalıştırabilirsiniz ancak harici sayfayla etkileşime geçemez veya iletişim kuramazsı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. Gruplandırılmış 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şturur ve toplanması için sunucunuza gönderir.
2. Sunucunuz, istemcilerden raporları toplar ve toplama hizmetine gönderilmek üzere gruplandırır.
3. 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ışı, Attribution Reporting API'ye benzer. Ancak İlişkilendirme Raporlaması, farklı zamanlarda gerçekleşen bir gösterim etkinliğinden ve dönüşüm etkinliğinden toplanan verileri ilişkilendirir. Gizli toplama, tek bir siteler arası etkinliği ölçer.

Toplama anahtarı

Toplama anahtarı ("anahtar" kısaca), toplanabilir değerlerin toplanacağı paketi temsil eder. Anahtara bir veya daha fazla boyut kodlanabilir. Boyut, kullanıcıların yaş grubu veya bir reklam kampanyasının gösterim sayısı gibi daha fazla analiz elde etmek istediğiniz bir yönü 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?" gibi soruları yanıtlamak istiyorsunuz. Bu soruyu raporlamak için widget kimliği ve ülke kimliği olmak üzere iki boyutu kodlayan bir toplama anahtarı oluşturabilirsiniz.

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ırayla 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, 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ı, 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 sahip bir BigInt değerine dönüştürülebilir. Karma oluşturma değeri 128 bitten fazlaysa 2^128−1 olan izin verilen maksimum paket değerini aşmaması için 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 edinmek için MDN'deki SubtleCrypto.digest() bölümüne bakın.

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

Toplanabilir değerler, özet raporlarda özet değerler biçiminde toplu analizler oluşturmak için 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ç tanesi Fransa'dan?" Bu sorunun cevabı "3276 widget kimliğimi gören yaklaşık 4.881 kullanıcı Fransa'dan" şeklinde görünür. Toplanabilir değer her kullanıcı için 1'dir ve "4881 kullanıcı", söz konusu toplama anahtarı için tüm toplanabilir değerlerin toplamı olan toplanmış değerdir.

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. Kullanıcı gizliliğini korumak için bir kişiden alınabilecek 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 az olmalıdır. Bütçe, iş akışı kaynağı başına, günlük olarak kapsamlandırılır ve Protected Audience API ile Shared Storage iş akışları için ayrıdır. Gün için yaklaşık son 24 saati kapsayan bir kaydırmalı pencere kullanılır. Yeni bir toplu rapor bütçenin aşılmasına neden olacaksa rapor oluşturulmaz.

Katkı bütçesi, L₁ parametresi ile temsil edilir ve 2¹⁶ (65.536) olarak ayarlanır. Bu değer, 2²⁰ (1.048.576) değerine kadar artırılabilir. Bu parametreler hakkında daha fazla bilgi edinmek için açıklamayı inceleyin.

Katkı bütçesinin değeri keyfidir 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 edinmek için açıklamayı inceleyin. Daha fazla bilgi için Katkı Bütçesi'ne de göz atın.

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

Arayana bağlı olarak katkı sınırı farklı olabilir. Paylaşılan depolama alanı için bu sınırlar, geçersiz kılınabilen varsayılan değerlerdir. Şu anda, Shared Storage API çağrısı yapanlar için oluşturulan raporların rapor başına katkı sayısı 20 ile 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 belirlenmiş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, 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ün doldurulması işlemi, birleştirilebilir rapora yerleştirilen gerçek katkı sayısıyla ilgili 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ıktan sonra tarayıcı, özet raporlar oluşturmak için daha sonra Toplama Hizmeti tarafından işlenecek toplu raporlar oluşturur. 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 özet bir rapor oluşturur. Tarayıcı için şifreleme anahtarı ve Aggregation Service için şifre çözme anahtarı, anahtar yönetimi hizmeti işlevi 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, raporu hemen sunucuya göndermek için "Seçili Raporları Gönder" düğmesi kullanılabilir.

Toplanabilir raporları toplama ve toplu işleme

Tarayıcı, listelenen bilinen yolu kullanarak birleştirilebilir raporları Private Aggregation API çağrısını içeren worklet'in kaynağına gönderir:

• Ortak Depolama 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 birleştirilebilir raporları alan bir toplayıcı görevi gören bir sunucu çalıştırmanız gerekir.

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

Gruplandırmayı 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.

Filtre kimlikleri

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

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

Ortak Depolama adımları

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

1. Yeni Paylaşılan Depolama Alanı modülünüzü nerede tanımlayacağınızı ve çalıştıracağınızı tanımlayın. Aşağıdaki örnekte, modül dosyasını filtering-worklet.js olarak adlandırdık ve filtering-example altında kaydettik.

   (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 parametresinin rapor başına yapılandırılabilir olduğunu ve ayarlanmamışsa varsayılan değerinin 1 olduğunu unutmayın. Bu varsayılan değer, yükü boyutunun gereksiz yere artırılması ve dolayısıyla depolama alanı ve işleme maliyetlerinin artmasını önlemek içindir. Esnek katkı açıklamalı makalede daha fazla bilgi edinin.

2. filtering-worklet.js'te, Paylaşılan Depolama Alanı iş parçasında privateAggregation.contributeToHistogram(...)'a bir katkı aktarırken 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 /.well-known/private-aggregation/report-shared-storage gönderilir. Aggregation Service iş parametrelerinde yapılması gereken değişiklikler hakkında bilgi edinmek için kimlik filtreleme kılavuzuna gidin.

Gruplandırma tamamlanıp dağıtılan toplama hizmetinize gönderildikten sonra filtrelenen sonuçlarınız nihai özet raporunuza yansıtılır.

Protected Audience adımları

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

1. Mevcut Protected Audience uygulamanızda, aşağıdakileri Private Aggregation'a bağlanacak şekilde ayarlayabilirsiniz. Ortak depolama alanından farklı olarak, filtreleme kimliğinin maksimum boyutunu henüz yapılandırmak mümkün değildir. Varsayılan olarak filtreleme kimliğinin maksimum boyutu 1 bayttır ve 0n olarak ayarlanır. Bunların Protected Audience raporlama işlevlerinizde (ör.reportResult() veya generateBid()) ayarlandığını unutmayın.

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

2. Toplanabilir raporlar, uç noktayı tanımladığınız yere /.well-known/private-aggregation/report-protected-audience gönderilir. Gruplandırma tamamlanıp dağıtılan Toplama Hizmetinize gönderildikten sonra filtrelenen sonuçlarınız nihai özet raporunuza yansıtılır. Attribution Reporting API ve Private Aggregation API ile ilgili açıklamaların yanı sıra ilk teklifi burada bulabilirsiniz.

Daha ayrıntılı bilgi için Toplama Hizmeti'ndeki kimlik filtreleme kılavuzumuza göz atın veya İlişkilendirme Raporlama API'si bölümünü inceleyin.

Aggregation Service

Toplama Hizmeti, toplayıcıdan şifrelenmiş birleştirilebilir raporlar alır ve özet raporlar oluşturur. Toplayıcınızda toplanabilir raporları gruplandırmayla ilgili daha fazla strateji için gruplandırma kılavuzumuza göz atın.

Hizmet, veri bütünlüğü, veri gizliliği ve kod bütünlüğü için belirli bir güven düzeyi 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 istiyorsanız rolleri ve amaçları hakkında daha fazla bilgi edinin.

Özet raporlar

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

Özet rapor, JSON sözlük stilinde bir anahtar/değer çifti grubu 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 ö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

Toplama Hizmeti, kullanıcı gizliliğini korumak için her özet raporu 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 yöntemlerini doğrudan kontrol edemeseniz de gürültünün ölçüm verileri üzerindeki etkisini etkileyebilirsiniz.

Gürültü dağılımı, tüm toplanabilir değerlerin toplamından bağımsız olarak aynıdır. Bu nedenle, toplanabilir değerler ne kadar yüksekse 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ıra odaklı olduğunu varsayalım. 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ı, toplanmış değerin yalnızca% 0,5'i olur. Bu nedenle, 20.000 değerinin toplanabilir olması,sinyal-gürültü oranının çok daha yüksek olmasını sağlar.

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

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 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ü 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 anahtarlardaki toplanabilir değerlerin maksimum toplamına bölün.

Daha fazla bilgi edinmek 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çıklamayı okuyun, soru sorun ve tartışmaya katılın.
  • Geliştirici desteği: Privacy Sandbox Developer Support repo'sunda soru sorabilir ve tartışmalara katılabilirsiniz.
• Private Aggregation ile ilgili en son duyurular için Shared Storage API grubuna ve Protected Audience API grubuna katılın.