Private Aggregation API'ye genel bakış

Protected Audience verilerini ve Paylaşılan Depolama'daki siteler arası verileri kullanarak birleştirilmiş veri raporları oluşturun.

Private Aggregation API, web'in kullandığı kritik özellikleri sağlamak amacıyla siteler arası verilerin gizliliği koruyarak toplanması ve raporlanması amacıyla tasarlanmıştır.

Uygulama durumu

Teklif Durum
Paylaşılan depolama alanı için rapor doğrulamasıyla geçersiz Private Aggregation API raporlarını önleyin
Explainer		 Chrome'da mevcut
Gizli Toplama hata ayıklama modunun kullanılabilirliği 3PC uygunluğuna bağlıdır
GitHub sorunu		 Chrome M119'da kullanılabilir
Rapor gecikmesini azaltma
Açıklayıcı		 Chrome M119'da kullanılabilir
Google Cloud için Private Aggregation API ve Aggregation Service desteği
Explainer		 Chrome M121'de kullanılabilir
Birleştirilebilir rapor yükleri için dolgu
Açıklayıcı		 Chrome M119'da kullanılabilir
Açık Artırma Rapor Alıcısı raporları için Özel Toplama hata ayıklama modu kullanılabilir
Açıklayıcı		 Chrome M123'te bekleniyor
Filtreleme kimliği desteği
Açıklama		 İlk lansmanın 2024'ün 2. çeyreğinde Chrome'da yapılması bekleniyor.

Private Aggregation API nedir?

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

Bu API şu anda bir işlem (sendHistogramReport()) sağlamaktadır ancak gelecekte daha fazlası desteklenebilir. Histogram işlemi, tanımladığınız her paketteki (API'de toplama anahtarı olarak bilinir) kullanıcılar arasında veri toplamanıza olanak tanır. Histogram çağrınız değerleri toplar ve gürültü uygulanmış toplu sonucu özet rapor biçiminde döndürür. Örneğin, raporda her bir kullanıcının içeriğinizi gördüğü site sayısı gösterilebilir veya üçüncü taraf komut dosyanızda bir hatayla karşılaşılabilir. Bu işlem, başka bir API'nin iş uygulaması içinde gerçekleştirilir.

Örneğin, daha önce demografik ve coğrafi verileri Paylaşılan Depolama Alanı'na kaydettiyseniz, Özel Toplama API'sını kullanarak New York'taki kaç kullanıcının içeriğinizi siteler arası gördüğünü yaklaşık olarak belirten bir histogram oluşturabilirsiniz. Bu ölçüm için toplama yapmak amacıyla coğrafya boyutunu toplama anahtarına kodlayabilir ve kullanıcıları toplanabilir değerde sayabilirsiniz.

Temel kavramlar

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

Toplanabilir raporlar, toplama ve toplu işlem için sunucunuza gönderilir. Toplu raporlar daha sonra Toplama Hizmeti tarafından işlenir ve bir özet raporu oluşturulur.

Private Aggregation API ile ilgili temel kavramlar hakkında daha fazla bilgi edinmek için Private Aggregation API ile ilgili temel bilgiler belgesini inceleyin.

İlişkilendirme Raporlarından Farklılıklar

Private Aggregation API ile birçok benzerlik mevcuttur Attribution Reporting API. İlişkilendirme Raporları, dönüşümleri ölçmek için tasarlanmış bağımsız bir API'dir. Özel Toplama ise Protected Audience API ve Paylaşılan Depolama gibi API'ler ile birlikte siteler arası ölçümler için oluşturulur. Her iki API de, özet raporlar oluşturmak için Toplama Hizmeti arka ucu tarafından kullanılan birleştirilebilir raporlar üretir.

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

Bu API'yi test et

Private Aggregation API, chrome://flags/#privacy-sandbox-ads-apis adresinde Privacy Sandbox Ads API'leri deneme işareti etkinleştirilerek yerel olarak test edilebilir.

Bu API'leri kullanmak için Özel Korumalı Alan Reklamları API'leri denemesini etkin olarak ayarlayın
Bu API'leri kullanmak için Özel Korumalı Alan Reklamları API'leri denemesini etkin olarak ayarlayın

Deneme ve katılımda test yapma hakkında daha fazla bilgi edinin.

Demoyu kullan

Private Aggregation API for Shared Storage demosuna goo.gle/shared-storage-demo adresinden ve koda GitHub'dan erişilebilir. Demo, istemci taraflı işlemleri uygular ve sunucunuza gönderilen toplanabilir bir rapor üretir.

Gelecekte Protected Audience API için Private Aggregation API demo yayınlanacaktır.

Kullanım alanları

Gizli Toplama, siteler arası ölçüm için genel amaçlı bir API'dir. Paylaşılan Depolama ve Protected Audience API iş akışlarında kullanılabilir. İlk adım, özellikle hangi bilgileri toplamak istediğinize karar vermektir. Bu veri noktaları, toplama anahtarlarınızın temelini oluşturur.

Payl deplm alanlı

Paylaşılan Depolama, sızıntıları önlemek için siteler arası verileri güvenli bir ortamda okuyup yazmanıza olanak tanır. Private Aggregation API ise Paylaşılan Depolama alanında 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, "Yaklaşık 317 benzersiz kullanıcı Content ID 861'i gördü" gibi bir yanıt sağlayabilir.

Paylaşılan Depolama Alanı'nda, kullanıcının içeriği önceden görüp görmediğini belirtmek için bir işaret ayarlayabilirsiniz. İşaretin mevcut olmadığı ilk ziyarette, Özel Toplama çağrısı yapılır ve ardından işaret ayarlanır. Siteler arası ziyaretler de dahil olmak üzere kullanıcının sonraki ziyaretlerinde Paylaşılan Depolama'yı kontrol edebilir ve işaret ayarlanmışsa Özel Toplama'ya rapor göndermeyi atlayabilirsiniz.

Demografi ölçümü

Farklı sitelerde içeriğinizi gören kullanıcıların demografik özelliklerini ölçmek isteyebilirsiniz.

Özel Toplama, "18-45 yaş aralığında ve Almanya'dan yaklaşık 317 benzersiz kullanıcı" 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, toplama anahtarında yaş grubu ve ülke boyutlarını kodlayarak Özel Toplama ile bir rapor oluşturabilirsiniz.

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

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

Özel Toplama, "Yaklaşık 89 kullanıcı Content ID 581'i en az 3 kez görmüştür" gibi bir yanıt sağlayabilir. Sayaç, Paylaşılan Depolama alanında farklı sitelerden artırılabilir ve bir iş akışı içinde okunabilir. Sayı K değerine ulaştığında, Gizli Toplama aracılığıyla bir rapor gönderilebilir.

Protected Audience API ile

Protected Audience API, yeniden hedefleme ve özel kitle kullanım alanlarını etkinleştirir. Gizli Toplama, alıcı ve satıcı iş akışlarından gelen etkinlikleri raporlamanıza olanak tanır. API, açık artırma tekliflerinin dağıtımını ölçme gibi görevler için kullanılabilir.

Protected Audience API iş akışında, verilerinizi doğrudan sendHistogramReport() kullanarak toplayabilir ve Protected Audience API'nin özel uzantısı olan reportContributionForEvent() aracılığıyla tetikleyiciye göre raporlayabilirsiniz.

Kullanılabilir işlevler

Aşağıdaki işlevler, Paylaşılan Depolama ve Protected Audience API iş akışlarında bulunan privateAggregation nesnesinde kullanılabilir.

contributeToHistogram()

privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> }) yöntemini çağırabilirsiniz. Burada toplama anahtarı bucket, toplanabilir değer ise value şeklindedir. bucket parametresi için BigInt gereklidir. value parametresi için bir tam sayı gerekir.

Erişim ölçümü için Paylaşılan Depolama'da nasıl çağrılabileceğine dair bir örnek:

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 this.sharedStorage.get(key) === 'true';

    // Do not 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 this.sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

Yukarıdaki kod örneği, siteler arası iframe içeriği her yüklendiğinde Özel Toplama işlemini çağırır. iframe kodu iş uygulamasını yükler ve iş uygulaması, Content ID'yi bir toplama anahtarına (paket) dönüştürerek Private Aggregation API'yi çağırır.

contributeToHistogramOnEvent()

Yalnızca Protected Audience API iş akışları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, grup ve değerin açık artırmanın o noktasında henüz kullanılamayan sinyallere bağlı olmasını da sağlar.

privateAggregation.reportContributionForEvent(eventType, contribution) yöntemi, tetikleyici etkinliği belirten bir eventType alır ve etkinlik tetiklendiğinde göndermek için contribution değerini alır. Tetikleyici etkinlik, açık artırma sona erdikten sonra açık artırmanın kendisinden (ör. açık artırmanın kazanılması veya kaybedilmesi) ya da reklamı oluşturan sınırlandırılmış bir çerçeveden gelebilir. Açık artırma etkinlikleriyle ilgili bir rapor göndermek için reserved.win, reserved.loss ve reserved.always olmak üzere iki ayrılmış anahtar kelime kullanabilirsiniz. Bir etkinlik tarafından sınırlanmış bir çerçeveden tetiklenen bir rapor göndermek için özel bir etkinlik türü tanımlayın. Etkinliği sınırlı bir çerçeveden tetiklemek için Fenced Frames Ads Reporting API'deki fence.reportEvent() yöntemini kullanın.

Aşağıdaki örnekte, açık artırma kazanma etkinliği tetiklendiğinde bir gösterim raporu ve reklamın oluşturulduğu sınırlanmış çerçeveden bir click etkinliği tetiklenirse bir tıklama raporu gönderir. 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 Raporlama açıklamasına bakın.

enableDebugMode()

Üçüncü taraf çerezleri hâlâ kullanılabilir olsa da, hata ayıklama modunu etkinleştirerek hata ayıklamayı ve test yapmayı kolaylaştıran geçici bir mekanizma sağlayacağız. Hata ayıklama raporu, çereze dayalı ölçümlerinizi Özel Toplama ölçümlerinizle karşılaştırırken faydalı olur ve API entegrasyonunuzu hızlı bir şekilde doğrulamanıza olanak tanır.

İş akışında privateAggregation.enableDebugMode() çağrılması, hata ayıklama modunu etkinleştirir. Bu da, toplanabilir raporların şifrelenmemiş (cleartext) yükü içermesine neden olur. Daha sonra bu yükleri, 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. Bu, üçüncü taraf çerezlerinin desteği sonlandırıldığında hata ayıklama modunun artık kullanılamayacağı anlamına gelir.

Hata ayıklama anahtarını, privateAggregation.enableDebugMode({ <debugKey: debugKey> }) çağrısı yaparak da ayarlayabilirsiniz. Burada BigInt, hata ayıklama anahtarı olarak kullanılabilir. Hata ayıklama anahtarı, çerez tabanlı bir ölçümdeki verileri ve Özel Toplama ölçümündeki verileri ilişkilendirmek için kullanılabilir. Bunlar bağlam başına yalnızca bir kez çağrılabilir. Bundan sonraki çağrılar yoksayılır.

// Enables debug mode
privateAggregation.enableDebugMode();

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

Doğrulamayı bildirin

Paylaşılan Depolama için, paylaşılan depolama işlemi çağrısına bir bağlam kimliği ekleyerek aldığınız birleştirilebilir raporların meşru olduğunu doğrulayabilirsiniz. Kimlik gönderilen rapora eklenir ve daha sonra bu kimliği, raporun paylaşılan depolama alanı işleminizden gönderildiğini doğrulamak için kullanabilirsiniz.

Bu özellik, Chrome M114 ve sonraki sürümlerde test edilebilir. Protected Audience API için rapor doğrulaması henüz teste hazır değildir.

Daha fazla bilgi edinmek için rapor doğrulama açıklamasına bakın.

Etkileşimde bulunun ve geri bildirim paylaşın

Private Aggregation API şu anda etkin olarak tartışılıyor ve gelecekte değiştirilebilir. Bu API'yi deneyip geri bildirimde bulunursanız memnuniyet duyarız.