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, Shared Storage ve Protected Audience API'de raporlama işlevleri oluşturan geliştiriciler için önemlidir.

• 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ı anlamanız, size en iyi tasarımı optimize edilmiş özet raporu alma kararlarını verir.

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ı (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 (ö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'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 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.

Özel Toplama 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ı 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, ö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 ö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 Raporlama API'sine benzer. 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, tek bir siteler arası etkinliği ölçer.

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ören kullanıcıların bulunduğu ülkeyi analiz etmek isteyebilirsiniz. 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ği ve ülke kimliğidir. 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 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 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 olur.

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 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 için SubtleCrypto.digest() açık MDN.

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. Özel Toplama için tek seferde JavaScript çağrısında 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 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. 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. 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 tüm toplanabilir değerleri topladığınızda toplam, katkı bütçesinden 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. Gün için yaklaşık son 24 saati kapsayan bir kaydırmalı pencere 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). Bu parametreler hakkında daha fazla bilgi edinmek için açıklamayı inceleyin.

Katkı bütçesinin değeri isteğe bağlıdır, 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: . 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, raporlar Shared Storage API arayanları için oluşturulan veri sınırı, rapor başına 20 katkıyla 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.

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 yapılan katkılar tek bir kaynağa göre gruplandırılır.

Dolgulu katkılar

Katkılar, dolgu özelliğiyle daha da değiştirilir. Yük, her bir e-tabloya yerleştirilmiş gerçek katkı sayısıyla ilgili bilgileri verileri toplayabilirsiniz. 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ı daha sonra Toplama Hizmeti tarafından işlenmek üzere toplanabilir raporlar özeti oluşturmak için raporları inceleyin. 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. İ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, 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, "Seçili Raporları Gönder" düğmesi, sunucuya rapor gönderir.

Toplanabilir raporları toplama ve toplu olarak hazırlama

Tarayıcı, listelenen bilinen yolu kullanarak birleştirilebilir raporları Özel Toplama API'sine yapılan çağrıyı içeren çalışma aletinin kaynağına gönderir:

• Ortak Depolama için: /.well-known/private-aggregation/report-shared-storage
• Korunan kitle 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ı 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 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 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 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. 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 biri ç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

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. 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 varyansın etkisi o kadar az olur.

Ö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ı, 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 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 anahtarlar genelindeki toplanabilir değerlerin maksimum toplamı.

Daha fazla bilgi 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çı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.