Private Aggregation API'nin temelleri

Private Aggregation API ile ilgili temel kavramlar

Bu doküman kimin için hazırlandı?

Private Aggregation API siteler arası verilere erişimi olan iş yayınlarından toplu veri toplanmasına olanak tanır. 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ı raporlama sistemi oluşturan bir geliştiriciyseniz bahsedeceğim.
• Pazarlamacı, veri bilimci veya başka bir özet raporuysanız tüketici, bu mekanizmaları anlamak, tasarımınızı 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ı (paket olarak da bilinir) bir önceden belirlenmiş veri noktası koleksiyonudur. Örneğin, ekip arkadaşlarınızın Tarayıcının ülkeyi bildirdiği bir konum verisi paketi toplama dokunun. Toplama anahtarı birden fazla boyut içerebilir (örneğin, içerik widget'ınızın ülkesi ve kimliği).
• Toplanabilir değer, tek bir veri noktasıdır bir toplama anahtarında toplayın. Kaç kullanıcının içeriğinizi Fransa'dan gören kullanıcıların oranı, France toplama anahtarıdır ve 1 öğesinin viewCount değeri toplanabilir değerdir.
• Birleştirilebilir raporlar, bir tarayıcı içinde oluşturulur ve şifrelenir. Private Aggregation API'sinde tek bir etkinlikle ilgili veriler yer alır.
• Toplama Hizmeti bir özet rapor oluşturmak için toplanabilir raporlardaki verileri işler.
• Özet rapor, Toplama Hizmeti'nin nihai çıktısıdır ve gürültülü birleştirilmiş kullanıcı verileri ve ayrıntılı dönüşüm verileri içerir.
• İş akışı, JavaScript işlevlerini çalıştırmanızı ve istek sahibine geri bilgi gönderebilir. Bir iş akışında Ancak dış sayfayla etkileşim kuramaz veya dış sayfayla iletişim kuramazsınız.

Özel Toplama iş akışı

Private Aggregation API'yi bir toplama anahtarı ve toplu hale getirildiğinde tarayıcı, toplu hale getirilebilir bir rapor oluşturur. Raporlar raporları toplu olarak sunan 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 raporları toplar ve bunları toplu hale getirir için bir e-posta alırsınız.
3. Yeterli sayıda rapor topladıktan sonra, bunları gruplandırıp Veri toplamak için güvenilir bir yürütme ortamında çalışan Toplama Hizmeti Özet raporu.

ziyaret edin.

Anahtar terim: güvenilir yürütme ortamı bilgisayar donanımı ve yazılımının özel bir yapılandırmasıdır. çalıştırılan yazılımların tam sürümlerini doğrulamak için harici taraflardan hoş geldiniz. TEE'ler, harici tarafların yazılımın tam olarak doğru çalıştığını doğrulamasına izin verir. yalnızca yazılım üreticisinin iddia ettiği noktaları özetler.

Bu bölümde açıklanan iş akışı, İlişkilendirme Raporları API. Ancak İlişkilendirme, Raporlama, bir gösterim etkinliğinden ve dönüşümden toplanan verileri ilişkilendirir ve farklı zamanlarda gerçekleşen etkinliklerdir. Özel Toplama, bir kullanıcının nasıl yardımcı olabileceğine bakalım.

Toplama anahtarı

Toplama anahtarı ("anahtar"), toplanabilir. Bir veya daha fazla boyut kodlanabilir içine yerleştireceğiz. Boyut, daha fazla kazanmak istediğiniz bir yönü gösterir (ör. kullanıcıların yaş grubu veya bir reklamın gösterim sayısı) hakkında bilgi pek de iyi olmadığını unutmayın.

Ö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. Baktığınız şey "Widget'ımı gören kullanıcılardan kaçı "X ülkesinden mi?" Bu soru hakkında rapor oluşturmak için toplama anahtarı oluşturabilirsiniz bir kod snippet'i ekleyin: widget kimliği ve ülke kimliği.

Private Aggregation API'ye sağlanan anahtar BigInt, reklam öğesidir. Bu örnekte boyutlar widget kimliğini ve ülke kimliğini girin. Widget kimliğinin en fazla 4 haneli olabileceğini varsayalım. her ülke alfabetik olarak bir sayıyla eşlenir (ör. 1234) sırası "Afganistan 1, Fransa 61 ve Zimbabve "195"tir. 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 Fransa'dan (ülke kimliği 061) kullanıcı sayısını temsil ettiğini varsayalım 3276 widget kimliğini gören kullanıcılar, Toplama anahtarı 3276061.

Toplama anahtarı
Widget kimliği	Ülke kimliği
3276	061

Örnek: Bir boyutta kullanılabilir anahtar alanı varsa ancak değerin daha az olması için baştaki sıfırları ekleyin. Örneğin, ülke kimliği 3 haneye izin veriyorsa Cezayir için ülke kimliği 003.

Toplama anahtarı, aşağıdaki gibi bir karma oluşturma mekanizmasıyla da oluşturulabilir: SHA-256'yı tıklayın. Örneğin, dize {"WidgetId":3276,"CountryID":67} için karma oluşturma işlemi uygulanabilir ve daha sonra BigInt değeri 42943797454801331377966796057547478208888578253058197330928948081739249096287n. Karma değeri 128 bitten büyükse, bitmemesi için bunu kısaltabilirsiniz. 2^128−1 olan izin verilen maksimum paket değerini aşıyor.

Paylaşılan Depolama iş akışında crypto ve TextEncoder modül bir veri kümesi oluşturabilirsiniz. Karma oluşturma hakkında daha fazla bilgi için SubtleCrypto.digest() açık MDN.

Aşağıdaki örnekte, karma oluşturma işlemi uygulanmış bir anahtardan 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 temel kavramlar Private Aggregation API için Attribution Reporting API. Özel Toplama için tek seferde JavaScript çağrısında belirtilir.

Toplanabilir değer

Toplanabilir değerler, toplu hale getirmek için birçok kullanıcıda anahtar başına toplanır. son derece değerli analizler elde etmenize olanak tanır.

Şimdi, daha önce sorulan örnek soruya geri dönün: "Kullanıcılardan widget'ımı kimler gördü?" 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 ve "4881 kullanıcı"dır. : Bu değer için tüm toplanabilir değerlerin toplamı olan toplu değer toplama anahtarı ile değiştirin.

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ı için de geçerli.

Katkı bütçesi

Private Aggregation API'ye yapılan her çağrıya katkı adı verilir. Koruma amaçlı kullanıcı gizliliği, bir web sitesinden toplanabilecek katkıların sayısı sınırlı sayıda kişiye özeldir.

Tüm toplama anahtarlarındaki toplanabilir değerlerin tümünü topladığınızda daha az olmalıdır. Bütçe iş akışı başına kapsama alınır origin, günlük ve Protected Audience API ve Paylaşılan Depolama işletleri için ayrı olarak. Yuvarlanan yaklaşık son 24 saatlik zaman aralığı, gün için kullanılır. Yeni bir bütçe aşılmasına neden olursa rapor, oluşturuldu.

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). Bkz. açıklayıcı ziyaret edebilirsiniz.

Katkı bütçesinin değeri isteğe bağlıdır, 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.

Birleştirilebilir raporlar

Kullanıcı Private Aggregation API'yi çağırdıktan sonra, tarayıcı daha sonra Toplama Hizmeti tarafından işlenmek üzere toplanabilir raporlar özeti oluşturmak için raporları inceleyin. toplu hale getirilebilir rapor JSON biçimindedir ve aşağıdakilerin şifrelenmiş bir listesini içerir: Katkılarından her biri {aggregation key, aggregatable value} çiftidir. 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. İlgili içeriği oluşturmak için kullanılan için şifreleme anahtarı ve Toplama için şifre çözme anahtarı Hizmet, anahtar yönetim hizmeti görevi gören koordinatör tarafından verilir. Koordinatör, doğrulama işlemi için hizmet görüntüsünün ikili karmalarının bir listesini tutar arayan kişinin şifre çözme anahtarını almasına izin verildiğini gösterir.

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 sayfa:

Test amacıyla, "Seçili Raporları Gönder" düğmesi, sunucuya rapor gönderir.

Toplanabilir raporları toplama ve toplu olarak hazırlama

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
• Korunan kitle 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ı toplu hale getirmeli ve grubu Toplama'ya göndermelidir. Hizmet. Şifrelenmemiş dosyadaki bilgilere dayalı olarak gruplar oluştur shared_info alanı gibi toplanabilir raporun yükü. İdeal koşullarda 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 zaman planlaması yapabilirsiniz.

Aggregation Service

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

Toplama Hizmeti, rapor yükünün şifresini çözmek için bir şifre çözme anahtarı getirir koordinatörden geliyor. Hizmet, güvenilir yürütme ortamında (TEE) çalışır. veri bütünlüğü, veri gizliliği, gizliliğin korunduğu ve yardımcı olur. 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ş halde görmenizi sağlar. Şunları isteyebilirsiniz: belirli bir anahtar grubu için özet raporları sunar.

Özet rapor, JSON sözlük stili anahtar/değer çiftleri kümesi içerir. Her biri ç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

Kullanıcı gizliliğini korumak için, Toplama Hizmeti her dosyaya bir kez gürültü ekler özet değerinin toplamıdır. Gürültü değerleri: Laplace olasılığından rastgele alınır dağıtım. Bu sırada Gürültünün eklenme şeklini doğrudan kontrol etmiyorsanız, etkiyi etkileyebilirsiniz. gürültünün ölçümüdür.

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 toplanabilir raporun değeri (veya "toplanabilir değer") yalnızca 200 ise gürültünün standart sapması şöyle olur: Toplam değerin% 50'si. Ancak toplanabilir değer 20.000 ise gürültünün standart sapması, toplam değerin yalnızca% 0,5'i olur. Dolayısıyla, 20.000'lik bir değer ise çok daha yüksek bir sinyal-gürültü oranına sahip olacaktır.

Bu nedenle, toplanabilir değerinizi bir ölçeklendirme faktörüyle çarpmanız, gürültüyü azaltın. Ölçeklendirme faktörü, belirli bir ölçeği ne kadar bir değer atfedilebilir.

Daha büyük bir ölçeklendirme faktörü seçerek değerleri yukarı ölçeklendirmek, gürültü. Ancak bu, tüm gruplardaki tüm katkıların toplamına da neden olur. . Değerleri şu oranda aşağı ölçeklendirme: daha küçük bir ölçeklendirme faktörü sabiti seçmek göreli gürültüyü artırır ancak hakkında konuşacağız.

Uygun bir ölçeklendirme faktörü hesaplamak için katkı bütçesini Tüm anahtarlar genelindeki toplanabilir değerlerin maksimum toplamı.

Bkz. Katkı bütçesi belgeleri konulu videomuzu izleyin.

Etkileşimde bulunun ve geri bildirim paylaşın

Private Aggregation API şu anda aktif olarak görülmektedir ve sahip olacaksınız. Bu API'yi deneyip geri bildirimlerinizi bizimle paylaşırsanız seviniriz.

• GitHub: açıklayıcı, sorular sorup tartışma hakkında daha fazla bilgi edinin. * Geliştirici desteği: Özel Korumalı Alan Geliştirici Desteği depo. * Shared Storage API'ye (Paylaşılan Depolama API'si) katılın. grup ve Protected Audience API grup inceleyin.