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ışı, İlişkilendirme Raporlama API'sine 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¹⁶ (65.536) olarak ayarlanır. Bu değer, 2²⁰ (1.048.576) olarak ayarlanan bir destek sınırına sahiptir. 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 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ı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 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 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ı Özel Toplama API'sine çağrı 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.

Aggregation Service

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

Toplama Hizmeti, rapor yayının şifresini çözmek için koordinatörden bir şifre çözme anahtarı alır. 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. Hizmetin sahibi ve işletmecisi olsanız da TEE'de işlenen verileri göremezsiniz.

Ö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 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. * Gizli toplama ile ilgili en son duyurular için Shared Storage API grubuna ve Protected Audience API grubuna katılın.