Private Aggregation API'ye genel bakış

Korunan Kitle'deki verileri ve Ortak Depolama'daki siteler arası verileri kullanarak toplu veri raporları oluşturun.

Web'in kullandığı kritik özellikleri sağlamak için Gizli Toplama API'si, siteler arası verileri gizliliği koruyacak şekilde toplamak ve raporlamak için tasarlanmıştır.

Uygulama durumu

Proposal Status
Prevent invalid Private Aggregation API reports with report verification for Shared Storage
Explainer		 Available in Chrome
Private Aggregation debug mode availability dependent on 3PC eligibility
GitHub issue		 Available in Chrome M119
Reducing report delay
Explainer		 Available in Chrome M119
Private Aggregation contribution timeout for Shared Storage
Explainer		 Available in M119
Support for Private Aggregation API and Aggregation Service for Google Cloud
Explainer		 Available in Chrome M121
Padding for aggregatable report payloads
Explainer		 Available in Chrome M119
Private Aggregation debug mode available for auctionReportBuyers reporting
Explainer		 Available in Chrome M123
Filtering ID support
Explainer		 Available in Chrome M128
Client-side contribution merging
Explainer		 Available in Chrome M129

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. Histografik işlem, 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 Paylaşılan Depolama'ya 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 Gizli Toplama 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 birleştirilebilir bir değerle çağırdığınızda tarayıcı, birleştirilebilir bir rapor oluşturur.

Toplanabilir raporlar, toplanma ve gruplandırma 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 benzerliğe sahiptir. 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. Özel 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 Özel Toplama API'sinin 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ı

Private Aggregation, siteler arası ölçüm için genel amaçlı bir API'dir ve Shared Storage ile 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ı

Ortak Depolama, sızıntıyı önlemek için siteler arası verileri güvenli bir ortamda okumanıza ve yazmanıza olanak tanır. Özel Toplama API'si ise Ortak Depolama'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.

Paylaşılan Depolama'da, kullanıcının içeriği görüp görmediğini belirtmek için bir işaret belirleyebilirsiniz. İşaretin bulunmadığı ilk ziyarette, Özel Toplama'ya bir çağrı 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 Paylaşılan Depolama'yı kontrol edebilir ve Özel 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örmüş kullanıcıların demografisini ölçmek isteyebilirsiniz.

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

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

Önceden seçilmiş bir K değeri için belirli bir tarayıcıda bir içeriği veya reklamı en az K kez gören kullanıcıların sayısını ö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

Reklam teknolojilerinin, paylaşılan depolama alanı + özel toplama içinde MTA'yı nasıl uygulayacağını anlayabilmesi için bu rehberlik geliştirici sitesinde yayınlanacaktır.

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()'u kullanarak verilerinizi tetikleyiciye göre raporlayabilirsiniz.

Kullanılabilir işlevler

Aşağıdaki işlevler, Paylaşılan Depolama 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 Özel Toplama'yı ç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 Özel Toplama 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, grubun 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 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 ise 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ş Özel Toplama Raporlaması açıklamalı kılavuzuna göz atın.

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, çerez tabanlı ölçümlerinizi Gizli Toplama ö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 Toplama Hizmeti 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 Özel Toplama ölçümünden gelen 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ına olanak tanır. 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, kötü niyetli kişilerin rapor oluşturmasını zorlaştıracak şekilde yasal ve gerçek API çağrıları aracılığıyla oluşturulduğundan emin olun.
  • Raporların 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.

Paylaşılan Depolama

Toplanabilir bir rapor gönderebilen bir işlem çalıştırmak için Ortak Depolama'yı 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ılarının sayısından bağımsız olarak, paylaşılan depolama alanı 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 sabit ve daha kısa bir gecikme (5 saniye) olur.

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

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

  1. Paylaşılan Depolama Alanı işlemi, bir bağlam kimliği belirten özel bir 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 Hizmetinize göndermeden önce her bir birleştirilebilir 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ı kişilerin 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ı reddedebilirsiniz.

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.