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 hizmetinin nihai çıkışıdır ve gürültülü toplu 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ışı

Ö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ı gruplandıran sunucunuza gönderilir. Toplu raporlar daha sonra Toplama Hizmeti tarafından işlenir ve bir özet rapor oluşturulur.

1. Özel Toplama API'sini çağırdığınızda istemci (tarayıcı), toplanabilir raporu oluşturur ve toplanması için sunucunuza gönderir.
2. Sunucunuz, istemcilerden gelen raporları toplar ve Toplama Hizmeti'ne 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.

Anahtar terim: Güvenilir yürütme ortamı, bilgisayar donanımı ve yazılımının, harici tarafların bilgisayarda çalışan yazılımların tam sürümlerini doğrulamasına olanak tanıyan özel bir yapılandırmasıdır. TEE'ler, harici tarafların, yazılımın tam olarak yazılım üreticisinin iddia ettiği şekilde çalıştığını (daha fazla veya daha az değil) doğrulamasına olanak tanır.

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. Özel 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ı
Widget kimliği	Ülke kimliği
3276	061

Örnek: Bir boyutta birden fazla basamak için kullanılabilir anahtar alanı varsa ancak değerde daha az basamak varsa başına sıfır ekleyin. Örneğin, ülke kimliği 3 haneye izin veriyorsa Cezayir için ülke kimliği 003 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 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 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 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

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

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 cevabı "3276 widget kimlikli widget'ımı 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.

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

Özel Toplama API'sine 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 Ortak Depolama 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²⁰ (1.048.576) yedek değeriyle günde on dakika başına 2¹⁶ (65.536) olarak ayarlanır. 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ı

Katkı sınırı, arayana bağlı olarak farklılık gösterebilir. Şu anda, Shared Storage API çağrıcıları 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ü boyutu arasında denge sağlamak için seçilmiştir.

Paylaşılan depolama alanında, 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ırmadaki 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 toplanabilir 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 Toplama Hizmeti 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 karma oluşturma işlemlerinin 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 sunucuya hemen 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 çalışma aletinin 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ündeki 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.

Kimlikleri filtreleme

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ı adımlar aşağıda verilmiştir.

Paylaşılan 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 ve dolayısıyla depolama ve işleme maliyetlerinin gereksiz yere artmasını önlemek içindir. Esnek katkı açıklamalı makalede daha fazla bilgi edinebilirsiniz.

2. Yukarıda kullandığınız dosyada (bu durumda filtering-worklet.js), Ortak 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, /.well-known/private-aggregation/report-shared-storage uç noktasını tanımladığınız yere gönderilir. Toplama Hizmeti 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 Korunan Kitle uygulamanızda, aşağıdakileri Özel Toplama'ya bağlanacak şekilde ayarlayabilirsiniz. Ortak depolama alanından farklı olarak, filtreleme kimliğinin maksimum boyutunu henüz yapılandıramazsınız. Filtreleme kimliğinin varsayılan maksimum boyutu 1 bayttır ve 0n olarak ayarlanır. Bunların [Protected Audience raporlama işlevlerinizde](Protected Audience raporlama işlevleri (ör.reportResult() veya generateBid()) ayarlandığını unutmayın.

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

2. Toplanabilir raporlar, /.well-known/private-aggregation/report-protected-audience uç noktasını tanımladığınız yere 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 Aggregation Service'teki kimlik filtreleme kılavuzumuza gidin veya Attribution Reporting API bölümlerine göz atın.

Aggregation Service

Toplama Hizmeti, toplayıcıdan şifrelenmiş toplanabilir raporlar alır ve özet raporlar oluşturur. Toplayıcınızda toplu olarak raporları gruplandırmayla ilgili daha fazla strateji için toplu işleme kılavuzumuzu inceleyin.

Hizmet, veri bütünlüğü, veri gizliliği ve kod bütünlüğü için 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ı çok daha yüksek hale getirir.

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 ölçeklendirmek, nispi 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 Geliştirici Desteği deposunda soru sorabilir ve tartışmalara katılabilirsiniz.
• Gizli toplama ile ilgili en son duyurulardan haberdar olmak için Shared Storage API grubuna ve Protected Audience API grubuna katılın.