Private Aggregation API'nin temelleri

Private Aggregation API ile ilgili 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, raporlama oluşturan geliştiriciler için önemlidir Shared Storage ve Protected Audience API içindeki işlevlere sahiptir.

• Siteler arası ölçüm için bir raporlama sistemi oluşturan bir geliştiriciyseniz.
• Pazarlamacı, veri bilimci veya başka bir özet raporuysanız tüketici bu mekanizmaları anlamanız, size en iyi tasarımı optimize edilmiş özet raporu alma kararlarını verir.

Anahtar terimler

Bu belgeyi okumadan önce, genel bilgileri öğrenmeniz, temel terimler ve kavramlar. 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. Kaç kullanıcının içeriğinizi Fransa'dan görmüşse France ülke için geçerli bir boyuttur. toplama anahtarıdır ve 1 öğesinin viewCount değeri toplanabilir değerdir.
• Toplanabilir raporlar, bir tarayıcıda oluşturulur ve şifrelenir. Private Aggregation API'sinde tek bir etkinlikle ilgili veriler yer alır.
• 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.
• İş akışı, JavaScript işlevlerini çalıştırmanızı ve istek sahibine geri bilgi gönderebilir. 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. Private Aggregation API'yi çağırdığınızda, istemci (tarayıcı) ve toplanabilir raporu 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. Bir veya daha fazla boyut kodlanabilir içine yerleştireceğiz. 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örüntüleyen kullanıcıların ülkelerini analiz etmek istiyorsanız. "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ğini ve ülke kimliğini girin. Widget kimliğinin 1234 gibi en fazla 4 haneli olabileceğini ve her ülkenin alfabetik sırayla bir sayıyla eşlendiğini varsayalım. Örneğin, Afganistan 1, Fransa 61 ve Zimbabve "195" olur. Bu nedenle, toplanabilir anahtar 7 basamak uzunluğunda olur ve ilk 4 basamak, WidgetID için karakter ayrıldı ve son 3 karakter CountryID için ayrıldı.

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şta sıfır ekleyin. Örneğin, ülke kimliği 3 haneye izin veriyorsa Cezayir için ülke kimliği 003 olur.

Toplama anahtarı, aşağıdaki gibi bir karma oluşturma mekanizmasıyla da oluşturulabilir: SHA-256'yı tıklayın. Ö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 kampanyadan nasıl paket anahtarı oluşturabileceğiniz açıklanmaktadır değer:

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 yanıtı, "Widget kimliğimi 3276'yı gören yaklaşık 4.881 kullanıcı Fransa'dan." 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. Pratikte toplanabilir değer, sinyal-gürültü oranını iyileştirmek için ölçeklendirilebilir. oranı'nı inceleyin.

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 toplanabilir değerlerin tümünü topladığınızda daha 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. Yuvarlanan yaklaşık son 24 saatlik zaman aralığı, gün için kullanılır. Yeni bir toplu rapor bütçenin aşılmasına neden olacaksa rapor oluşturulmaz.

Katkı bütçesi, L₁ parametresiyle temsil edilir ve 2²⁰'lik geri bağlantıyla günde on dakikada 2¹⁶ (65.536) olarak ayarlandı

(1.048.576). 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. Bu bütçeyi, özet değerlerde sinyal-gürültü oranını en üst düzeye çıkarmak için kullanabilirsiniz. (bu konu 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: . Ayrıca, bkz. Katkı Bütçe daha fazla bilgi için.

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ün boyutunu dengelemek için seçilmiştir.

Ortak depolama alanı için, tek bir run() veya selectURL() içinde yapılan katkılar işlemleri tek bir rapor halinde gruplandırılır. Protected Audience için yapılan katkılar tek bir kaynağa göre gruplandırılır.

Dolgulu katkılar

Katkılar, bir dolgu özelliğiyle daha da değiştirilebilir. Yük, her bir e-tabloya yerleştirilmiş gerçek katkı sayısıyla ilgili bilgileri verileri toplayabilirsiniz. Dolgu, yükü null katkıyla artırır (yani 0 değerini) kullanarak sabit bir uzunluğa ulaşı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 bir özet 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 içeren, toplanabilir rapor örneği modu etkinse:

  "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ı, toplanabilir raporları iş akışının kaynağına gönderir listelenen iyi bilinen kodu kullanarak Private Aggregation API'ye yapılan çağrıyı içerir. yol:

• Paylaşılan depolama alanı için: /.well-known/private-aggregation/report-shared-storage
• Protected Audience için: /.well-known/private-aggregation/report-protected-audience

Bu uç noktalarda, toplayıcı görevi gören bir sunucu çalıştırmanız gerekir. toplanan verileri içeren bir e-posta alırsınız.

Ardından sunucu, raporları gruplandırıp grubu Toplama Hizmeti'ne göndermelidir. Şifrelenmemiş dosyadaki bilgilere dayalı olarak gruplar oluştur shared_info alanı gibi toplanabilir raporun yükü. İdeal olarak, gruplar grup başına 100 veya daha fazla rapor içermelidir.

Gruplandırma işlemini günlük veya haftalık olarak yapabilirsiniz. Bu strateji esnektir, ve toplu işleme stratejinizi daha fazla hacim (örneğin, yılın daha fazla gösterim beklenen günleri) 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ş ve toplanabilir raporlar alır ve özet oluşturur raporlar.

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 yöneticisi olmanıza rağmen, verilerin TEE içinde işlenen verilere ulaşmasını sağlar.

Ö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 stili anahtar/değer çiftleri kümesi içerir. Her çift şunları içerir:

• bucket: İkili sayı dizesi olarak toplama anahtarı. Öğe kullanılan toplama anahtarı "123", paket ise "1111011" olur.
• value: belirli bir ölçüm hedefinin Gürültü eklenmiş tüm mevcut, toplanabilir raporlar.

Ö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ı, toplanabilir tüm verilerin toplamından bağımsız olarak aynıdır değerler. Bu nedenle, toplanabilir değerler ne kadar yüksek olursa gürültünün etkisi o kadar az olur. belirler.

Örneğin, gürültü dağılımının standart sapmasının 100 olduğunu varsayalım. merkezde sıfır olarak görünür. 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, birleştirilebilir 20.000 değerinin 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ü 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, tüm gruplardaki tüm katkıların toplamı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 için Katkı bütçesi dokümanlarına bakın.

Etkileşimde bulunun ve geri bildirim paylaşın

Private Aggregation API aktif olarak tartışılmakta olup gelecekte değişikliğe tabi olabilir. Bu API'yi deneyip geri bildirimlerinizi bizimle paylaşırsanız seviniriz.

• GitHub: açıklayıcı, sorular sorup tartışma. * Geliştirici desteği: Özel Korumalı Alan Geliştirici Desteği reposunda 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.