Private Aggregation API'ye genel bakış

Protected Audience'taki verileri ve Ortak Depolama'daki siteler arası verileri kullanarak toplu veri raporları oluşturun.

Web'in ihtiyaç duyduğu kritik özellikleri sağlamak için Private Aggregation API, siteler arası verileri gizliliği koruyacak şekilde toplayıp raporlamak üzere tasarlanmıştır.

Uygulama durumu

Teklif Durum
Ortak Depolama için rapor doğrulamasıyla geçersiz Private Aggregation API raporlarını önleyin
Açıklayıcı
Chrome'da kullanılabilir
Özel toplama hata ayıklama modu, üçüncü taraf çerez uygunluğuna bağlı olarak kullanılabilir
GitHub sorunu
Chrome M119'da kullanılabilir
Rapor gecikmesini azaltma
Açıklayıcı
Chrome M119'da kullanılabilir
Shared Storage için Private Aggregation katkısı zaman aşımı
Açıklama
M119'da kullanılabilir
Google Cloud için Private Aggregation API ve Aggregation Service desteği
Açıklayıcı
Chrome M121'de kullanılabilir
Toplanabilir rapor yükü için dolgu
Açıklama
Chrome M119'da kullanılabilir
auctionReportBuyers raporlaması için Private Aggregation hata ayıklama modu kullanılabilir
Açıklama
Chrome M123'te kullanılabilir
Filtreleme kimliği desteği
Açıklama
Chrome M128'de kullanılabilir
İstemci tarafı katkı birleştirme
Açıklama
Chrome M129'da kullanılabilir
Bağlama göre katkı sınırları
Açıklama
2025'in 1. çeyreğinde yapılması bekleniyor
Farklı ölçüm kullanım alanları için gizlilik bütçesini önceden ayıran adlandırılmış gizlilik bütçeleri
Açıklama
2025'in 2. çeyreğinde yapılması bekleniyor
Üçüncü taraf çerezlerine ihtiyaç duymadan uygulama sorunlarında hata ayıklama yapan toplu hata raporlaması
Açıklama
2025'in 2. çeyreğinde yapılması bekleniyor

Private Aggregation API nedir?

Private Aggregation API, geliştiricilerin Protected Audience API'deki verileri ve Shared Storage'daki siteler arası verileri kullanarak toplu veri raporları oluşturmasına olanak tanır.

Bu API'nin ana işlevi contributeToHistogram() olarak bilinir. Histogram işlemi, tanımladığınız her gruptaki (API'de toplama anahtarı olarak bilinir) kullanıcılar arasında verileri toplamanıza olanak tanır. Histogram çağrınız değerleri toplar ve özet rapor biçiminde gürültülü bir toplu sonuç döndürür. Örneğin, raporda her kullanıcının içeriğinizi gördüğü sitelerin sayısı gösterilebilir veya üçüncü taraf komut dosyanızda bir hatayla karşılaşabilirsiniz. Bu işlem başka bir API'nin iş parçasında gerçekleştirilir.

Örneğin, daha önce Shared Storage'a demografik ve coğrafi veriler kaydettiyseniz New York'ta siteler arası içeriklerinizi yaklaşık olarak kaç kullanıcının gördüğünü gösteren bir histogram oluşturmak için Private Aggregation API'yi kullanabilirsiniz. Bu ölçüm için toplama yapmak istiyorsanız coğrafya boyutunu toplama anahtarına kodlayabilir ve kullanıcıları toplanabilir değerde toplayabilirsiniz.

Temel kavramlar

Private Aggregation API'yi bir toplama anahtarı ve toplanabilir bir değerle çağırdığınızda tarayıcı, toplanabilir bir rapor oluşturur.

Toplanabilir raporlar, toplanması ve gruplandırılması için sunucunuza gönderilir. Gruplandırılmış raporlar daha sonra Toplama Hizmeti tarafından işlenir ve bir özet rapor oluşturulur.

Private Aggregation API ile ilgili temel kavramlar hakkında daha fazla bilgi edinmek için Private Aggregation API'nin temelleri belgesine bakın.

İlişkilendirme raporlamasından farklılıklar

Private Aggregation API, Attribution Reporting API ile birçok benzerlik taşır. Attribution Reporting, dönüşümleri ölçmek için tasarlanmış bağımsız bir API'dir. Private Aggregation ise Protected Audience API ve Shared Storage gibi API'lerle birlikte siteler arası ölçümler için tasarlanmıştır. Her iki API de, özet raporlar oluşturmak için Toplama Hizmeti arka ucu tarafından kullanılan birleştirilebilir raporlar oluşturur.

İlişkilendirme raporlaması, farklı zamanlarda gerçekleşen bir gösterim etkinliğinden ve dönüşüm etkinliğinden toplanan verileri ilişkilendirir. Gizli toplama, tek bir siteler arası etkinliği ölçer.

Bu API'yi test etme

Private Aggregation API'yi yerel olarak test etmek için chrome://settings/adPrivacy altındaki tüm reklam gizliliği API'lerini etkinleştirin.

Deneme ve katılım bölümünde test hakkında daha fazla bilgi edinin.

Demoyu kullanma

Paylaşılan Depolama için Private Aggregation API'nin demosuna goo.gle/shared-storage-demo adresinden, koduna ise GitHub'dan erişebilirsiniz. Demo, istemci tarafı işlemleri uygular ve sunucunuza gönderilen birleştirilebilir bir rapor oluşturur.

Protected Audience API için Private Aggregation API demosu ileride yayınlanacaktır.

Kullanım alanları

Siteler arası ölçüm için genel amaçlı bir API olan Private Aggregation, Shared Storage ve Protected Audience API iş parçacıklarında kullanılabilir. İlk adım, hangi bilgileri toplamak istediğinize karar vermektir. Bu veri noktaları, toplama anahtarlarınızın temelini oluşturur.

Paylaşılan depolama alanı

Shared Storage, sızıntıyı önlemek için siteler arası verileri güvenli bir ortamda okumanıza ve yazmanıza olanak tanır. Private Aggregation API ise Shared Storage'da depolanan siteler arası verileri ölçmenize olanak tanır.

Tekil erişim ölçümü

İçeriklerini kaç benzersiz kullanıcının gördüğünü ölçmek isteyebilirsiniz. Private Aggregation API, "861 Content ID'sini yaklaşık 317 benzersiz kullanıcı gördü." gibi bir yanıt sağlayabilir.

Shared Storage'da, kullanıcının içeriği daha önce görüp görmediğini belirtmek için bir işaret belirleyebilirsiniz. İşaretin bulunmadığı ilk ziyarette, Özel Toplama çağrısı yapılır ve ardından işaret ayarlanır. Siteler arası ziyaretler dahil olmak üzere kullanıcının sonraki ziyaretlerinde, işaret ayarlanmışsa Shared Storage'ı kontrol edebilir ve Gizli Toplama'ya rapor göndermeyi atlayabilirsiniz. Bu ölçümleri uygulama yöntemleri hakkında daha fazla bilgi edinmek için erişim teknik belgemizi inceleyin.

Demografik grup ölçümü

İçeriğinizi farklı sitelerde gören kullanıcıların demografisini ölçmek isteyebilirsiniz.

Özel toplama, "Almanya'da 18-45 yaş aralığında yaklaşık 317 benzersiz kullanıcı" gibi bir yanıt sağlayabilir. Üçüncü taraf bağlamındaki demografi verilerine erişmek için Ortak Depolama'yı kullanın. Daha sonra, yaş grubu ve ülke boyutlarını toplama anahtarında kodlayarak Özel Toplama ile bir rapor oluşturabilirsiniz.

K+ sıklık ölçümü

Belirli bir tarayıcıda bir içeriği veya reklamı en az K kez gören kullanıcıların sayısını (önceden seçilmiş bir K değeri için) ölçmek isteyebilirsiniz.

Özel toplama, "Yaklaşık 89 kullanıcı, 581 Content ID'yi en az 3 kez gördü." gibi bir yanıt sağlayabilir. Bir sayaç, paylaşılan depolama alanında farklı sitelerden artırılıp bir iş parçasında okunabilir. Sayı K'ya ulaştığında Özel Toplama kullanılarak bir rapor gönderilebilir.

Çoklu dokunma ilişkilendirme

Pazarlama ilişkilendirmesi, reklamverenlerin pazarlama taktiklerinin ve sonraki reklam etkileşimlerinin satışlara veya dönüşümlere katkısını belirlemek için kullandığı bir yöntemdir.

Protected Audience API ile

Protected Audience API, yeniden hedefleme ve özel kitle kullanım alanlarını etkinleştirir. Gizli Toplama ise alıcı ve satıcı iş parçacıklarındaki etkinlikleri bildirmenize olanak tanır. API, açık artırma tekliflerinin dağılımını ölçme gibi görevler için kullanılabilir.

Protected Audience API iş parçasından, verilerinizi doğrudan contributeToHistogram() kullanarak toplayabilir ve Protected Audience API için özel bir uzantı olan contributeToHistogramOnEvent()'ü kullanarak verilerinizi bir tetikleyiciye göre raporlayabilirsiniz.

Kullanılabilir işlevler

Aşağıdaki işlevler, Shared Storage ve Protected Audience API iş parçacıklarında bulunan privateAggregation nesnesinde kullanılabilir.

contributeToHistogram()

Toplama anahtarının bucket ve toplanabilir değerin value olduğu privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> }) işlevini çağırabilirsiniz. bucket parametresi için bir BigInt gereklidir. value parametresi için tam sayı gereklidir.

Erişim ölçümü için paylaşılan depolama alanında nasıl çağrılabileceğine dair bir örnek aşağıda verilmiştir:

iframe.js

// Cross-site iframe code

async function measureReach() {
 // Register worklet
 await window.sharedStorage.worklet.addModule('worklet.js');

 // Run reach measurement operation
 await window.sharedStorage.run('reach-measurement', {
  data: { contentId: '1234' }
 });
}

measureReach();

worklet.js

// Shared storage worklet code

function convertContentIdToBucket(campaignId){
  // Generate aggregation key
}

// The scale factor is multiplied by the aggregatable value to
// maximize the signal-to-noise ratio. See "Noise and scaling"
// section in the Aggregation Fundamentals document to learn more.
const SCALE_FACTOR = 65536;

class ReachMeasurementOperation {
  async run(data) {
    const key = 'has-reported-content';
    // Read the flag from Shared Storage
    const hasReportedContent = await sharedStorage.get(key) === 'true';

    // Don't send report if the flag is set
    if (hasReportedContent) {
      return;
    }

    // Send histogram report
    // Set the aggregation key in `bucket`
    // Bucket examples: 54153254n or BigInt(54153254)
    // Set the scaled aggregatable value in `value`
    privateAggregation.contributeToHistogram({
      bucket: convertContentIdToBucket(data.contentId),
      value: 1 * SCALE_FACTOR
    });

    // Set the flag in Shared Storage
    await sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

Önceki kod örneği, siteler arası iframe içeriği her yüklendiğinde Private Aggregation'ı çağırır. Iframe kodu, iş parçacığını yükler ve iş parçası, içerik kimliğini bir toplama anahtarına (bucket) dönüştürerek Private Aggregation API'yi çağırır.

contributeToHistogramOnEvent()

Yalnızca Protected Audience API iş parçacıklarında, yalnızca belirli bir etkinlik gerçekleştiğinde rapor göndermek için tetikleyici tabanlı bir mekanizma sağlarız. Bu işlev, paketin ve değerin açık artırmanın o noktasında henüz mevcut olmayan sinyallere bağlı olmasına da olanak tanır.

privateAggregation.contributeToHistogramOnEvent(eventType, contribution) yöntemi, tetikleyici etkinliği belirten bir eventType ve etkinlik tetiklendiğinde gönderilecek contribution alır. Tetikleyici etkinlik, açık artırma sona erdikten sonra açık artırmanın kendisinden (ör. açık artırma kazanma veya kaybetme etkinliği) gelebilir ya da reklamı oluşturan korumalı bir çerçeveden gelebilir.

Açık artırma etkinlikleri için rapor göndermek üzere reserved.win, reserved.loss ve reserved.always olmak üzere iki ayrılmış anahtar kelime kullanabilirsiniz. Çitlenmiş bir çerçeveden gelen bir etkinlik tarafından tetiklenen bir rapor göndermek için özel etkinlik türü tanımlayın. Etkinliği çitle çevrili bir çerçeveden tetiklemek için Çitle Çevrili Çerçeveler Reklam Raporlama API'sinde bulunan fence.reportEvent() yöntemini kullanın.

Aşağıdaki örnekte, açık artırma kazanan etkinliği tetiklendiğinde bir gösterim raporu, reklamı oluşturan çitli çerçeveden bir click etkinliği tetiklenirse bir tıklama raporu gönderilir. Bu iki değer, tıklama oranını hesaplamak için kullanılabilir.

function generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals) {
  // …
  privateAggregation.contributeToHistogramOnEvent("reserved.win", {
      bucket: getImpressionReportBucket(),
      value: 1
  });
  privateAggregation.contributeToHistogramOnEvent("click", {
      bucket: getClickReportBuckets(), // 128-bit integer as BigInt
      value: 1
  });

Daha fazla bilgi edinmek için Genişletilmiş Gizli Toplama Raporlaması hakkında açıklama başlıklı makaleyi inceleyin.

enableDebugMode()

Üçüncü taraf çerezleri kullanılmaya devam edecek olsa da hata ayıklama modunu etkinleştirerek daha kolay hata ayıklama ve test yapmanızı sağlayan geçici bir mekanizma sunacağız. Hata ayıklama raporu, çereze dayalı ölçümlerinizi Private Aggregation ölçümlerinizle karşılaştırmanıza yardımcı olur ve API entegrasyonunuzu hızlı bir şekilde doğrulamanızı sağlar.

Çalışma alanında privateAggregation.enableDebugMode() çağrısı yapıldığında hata ayıklama modu etkinleştirilir. Bu mod, birleştirilebilir raporların şifrelenmemiş (net metin) yükünü içermesine neden olur. Ardından bu yük verimlerini Aggregation Service yerel test aracı ile işleyebilirsiniz.

Hata ayıklama modu yalnızca üçüncü taraf çerezlerine erişmesine izin verilen arayanlar tarafından kullanılabilir. Arayanın üçüncü taraf çerezlerine erişimi yoksa enableDebugMode() sessizce başarısız olur.

Ayrıca, BigInt'un hata ayıklama anahtarı olarak kullanılabileceği privateAggregation.enableDebugMode({ <debugKey: debugKey> }) çağrısını yaparak hata ayıklama anahtarını ayarlayabilirsiniz. Hata ayıklama anahtarı, çerez tabanlı ölçümden ve Private Aggregation ölçümünden alınan verileri ilişkilendirmek için kullanılabilir.

Bunlar, bağlam başına yalnızca bir kez çağrılabilir. Sonraki tüm çağrılar istisna oluşturur.

// Enables debug mode
privateAggregation.enableDebugMode();

// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });

Rapor doğrulaması

Private Aggregation API, kullanıcı gizliliğini korurken siteler arası ölçüm yapılmasını sağlar. Ancak kötü niyetli kişiler bu ölçümlerin doğruluğunu değiştirmeye çalışabilir. Bunu önlemek için raporların gerçekliğini doğrulamak üzere bir bağlam kimliği kullanabilirsiniz.

Bağlam kimliği ayarlamak, nihai toplu sonuçlara katkıda bulunurken verilerin doğru olmasını sağlar. Bu, aşağıdaki yöntemlerle yapılır:

  • Yasal olmayan veya sahte raporları önleme: Raporların yasal ve gerçek API çağrıları aracılığıyla oluşturulmasını sağlayarak kötü niyetli kişilerin rapor oluşturmasını zorlaştırın.
  • Raporun yeniden oynatılmasını önleme: Eski raporların yeniden kullanılmasıyla ilgili tüm girişimleri tespit edip reddeder. Böylece her raporun toplu sonuçlara yalnızca bir kez katkıda bulunması sağlanır.
makaleyi inceleyin.

Paylaşılan Depolama

Toplanabilir bir rapor gönderebilecek bir işlem çalıştırmak için Shared Storage'ı kullanırken iş parçasının dışında tahmin edilemeyen bir kimlik ayarlayabilirsiniz.

Bu kimlik, çalışma sayfasından oluşturulan rapora yerleştirilir. run() veya selectURL() Paylaşılan Depolama yöntemlerini çağırırken privateAggregationConfig anahtarının altındaki seçenekler nesnesi içinde belirtebilirsiniz.

Örneğin:

sharedStorage.run('measurement-operation', {
  privateAggregationConfig: {
    contextId: 'exampleId123456789abcdeFGHijk'
  }
});

Bu kimlik ayarlandıktan sonra, raporun Paylaşılan Depolama İşleminizden gönderildiğini doğrulamak için kullanabilirsiniz. Bilgi sızıntısını önlemek için, contributeToHistogram() çağrısının sayısından bağımsız olarak Shared Storage işlemi başına tam olarak bir rapor gönderilir (katkı yapılmamış olsa bile).

Private Aggregation API, birleştirilebilir raporları bir saate kadar rastgele bir gecikmeyle gönderir. Ancak bir raporu doğrulamak için bağlam kimliği ayarlamak bu gecikmeyi azaltır. Bu durumda, paylaşılan depolama alanı işleminin başlamasından itibaren 5 saniyelik sabit ve daha kısa bir gecikme olur.

Rapor doğrulaması için örnek iş akışı.
Rapor doğrulaması için örnek iş akışı.

Örnek iş akışı (yukarıdaki şemada gösterildiği gibi):

  1. Ortak Depolama işlemi, bir bağlam kimliği belirten Gizli Toplama yapılandırmasıyla çalıştırılır ve toplanabilir bir rapor oluşturulur.
  2. Bağlam kimliği, sunucunuza gönderilen oluşturulan birleştirilebilir rapora yerleştirilir.
  3. Sunucunuz, oluşturulan birleştirilebilir raporları toplar.
  4. Sunucunuzdaki işlemler, raporları gruplandırıp Toplama Hizmetiniz'e göndermeden önce her bir toplanabilir rapordaki bağlam kimliğini, depolanan bağlam kimliklerinizle karşılaştırarak geçerliliğini kontrol eder.

Bağlam kimliği doğrulaması

Toplayıcı sunucunuza gelen raporlar, Toplama Hizmeti'ne gönderilmeden önce birkaç farklı şekilde doğrulanabilir. Geçersiz bağlam kimliklerine sahip raporlar, bağlam kimliği aşağıdaki durumlarda reddedilebilir:

  • Bilinmiyor: Sisteminizin oluşturmadığı bir bağlam kimliği içeren bir rapor alırsanız raporu reddedebilirsiniz. Bu sayede, bilinmeyen veya kötü amaçlı kullanıcıların toplama ardışık düzeninize veri eklemesi engellenir.
  • Yinelenen: Aynı bağlam kimliğine sahip iki (veya daha fazla) rapor alırsanız hangi raporların silineceğini seçmeniz gerekir.
  • Spam algılamada işaretlendi:
    • Bir kullanıcıdan şüpheli etkinlik (ör. kullanıcının etkinliğinde ani bir değişiklik) algılarsanız raporunu işleme alırken reddedebilirsiniz.
    • Raporları, içerik kimlikleriyle ve alakalı sinyallerle (ör. kullanıcı aracısı, yönlendirme kaynağı vb.) birlikte saklayabilirsiniz. Daha sonra, kullanıcı davranışını analiz ederken ve yeni spam göstergelerini belirlerken, depolanan raporları ilişkili bağlam kimliklerine ve sinyallerine göre yeniden değerlendirebilirsiniz. Bu sayede, başlangıçta işaretlenmemiş olsalar bile şüpheli etkinlik gösteren kullanıcıların raporlarını silebilir.

Etkileşim kurma ve geri bildirim paylaşma

Private Aggregation API aktif olarak tartışılmakta olup gelecekte değiştirilebilir. Bu API'yi denedikten sonra geri bildiriminiz olursa bizimle paylaşın.