Private Aggregation API'ye genel bakış

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

Private Aggregation API, web'in kullandığı önemli özellikleri sağlamak amacıyla siteler arası verilerin gizliliği koruyarak toplanması ve raporlanması için 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 alınan verilerle ve Shared Storage'daki siteler arası verilerle birleştirilmiş veri raporları oluşturmasına olanak tanır.

Bu API şu anda sendHistogramReport() adlı bir işlem sunuyor ancak gelecekte daha fazla işlem desteklenebilir. Histogram işlemi, tanımladığınız her bir paketteki (API'de toplama anahtarı olarak bilinir) kullanıcılar genelinde verileri birleştirmenize olanak tanır. Histogram çağrınız değer toplar ve özet rapor biçiminde gürültü uygulanmış toplu bir sonuç döndürür. Örneğin rapor, her bir kullanıcının içeriğinizi kaç sitede gördüğünü veya üçüncü taraf komut dosyanızda bir hatayla karşılaştığını gösterebilir. Bu işlem başka bir API'nin iş akışı içinde gerçekleştirilir.

Örneğin, daha önce Paylaşılan Depolama Alanı'na demografik ve coğrafi veriler kaydettiyseniz Özel Birleştirme API'sını kullanarak, New York City'deki kaç kullanıcının siteler arası içeriğinizi yaklaşık olarak gördüğünü size gösteren bir histogram oluşturabilirsiniz. Bu ölçüm için toplama yapmak üzere coğrafi boyutu toplama anahtarında 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, toplanma ve gruplandırma için sunucunuza gönderilir. Toplu 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 temel bilgileri belgesine bakın.

İlişkilendirme Raporlarından Farklar

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. Özel Toplama 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 Raporları, farklı zamanlarda gerçekleşen bir gösterim etkinliğinden ve dönüşüm etkinliğinden toplanan verileri ilişkilendirir. Özel Toplama, siteler arası tek bir etkinliği ölçer.

Bu API'yi test et

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

Denemede ve katılmada test yapma hakkında daha fazla bilgi edinin.

Demoyu kullanın

Paylaşılan Depolama Alanı için Private Aggregation API demosuna goo.gle/shared-storage-demo adresinden erişilebilir. Kodu GitHub'da bulabilirsiniz. Demo, istemci taraflı işlemleri uygular ve sunucunuza gönderilen birleştirilebilir rapor üretir.

Gelecekte Protected Audience API için Private Aggregation API'nin demosu yayınlanacaktır.

Kullanım alanları

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

Paylaşılan depolama birimi ile

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, "Content ID 861'i yaklaşık 317 benzersiz kullanıcı gördü" gibi bir yanıt verebilir.

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

Demografi ölçümü

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

Özel Toplama, "18-45 yaşları arasında ve Almanya'da olan yaklaşık 317 benzersiz kullanıcı" gibi bir yanıt verebilir. Üçüncü taraf bağlamından demografi verilerine erişmek için Paylaşılan Depolama Alanı'nı 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çilen K değeri için, bir içerik parçasını veya bir reklamı belirli bir tarayıcıda en az K kez gören kullanıcıların sayısını ölçmek isteyebilirsiniz.

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

Protected Audience API ile

Protected Audience API, yeniden hedefleme ve özel kitle kullanım alanları sağlar. Özel Toplama ise alıcı ve satıcı iş akışlarındaki etkinlikleri raporlamanıza olanak tanır. API, açık artırma tekliflerinin dağılımını ölçmek gibi görevler için kullanılabilir.

Protected Audience API iş akışından verilerinizi doğrudan sendHistogramReport() kullanarak bir araya getirebilir ve Protected Audience API'nin özel uzantısı olan reportContributionForEvent() ile bir tetikleyiciye göre verilerinizi raporlayabilirsiniz.

Kullanılabilir işlevler

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

contributeToHistogram()

Toplama anahtarının bucket, toplanabilir değeri ise value olarak belirlenmiş privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> }) öğesini çağırabilirsiniz. bucket parametresi için BigInt gerekir. value parametresi için bir tam sayı gerekir.

Aşağıda, bu alanın erişim ölçümü için Paylaşılan Depolama Alanı'nda nasıl çağrılabileceğine dair bir örnek 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 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 yüklendiğinde Özel Toplama'yı çağırır. iframe kodu, iş akışını yükler ve işlet, toplama anahtarına (paket) dönüştürülmüş Content ID ile Özel Birleştirme API'sini çağırır.

contributeToHistogramOnEvent()

Yalnızca Protected Audience API iş akışlarında, yalnızca belirli bir olay gerçekleşirse 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 mevcut olmayan sinyallere bağlı olmasına da olanak tanır.

privateAggregation.reportContributionForEvent(eventType, contribution) yöntemi, tetikleme etkinliğini belirten bir eventType ve etkinlik tetiklendiğinde gönderilecek contribution değerini alır. Tetikleyici etkinlik, açık artırma sona erdikten sonra açık artırmanın kendisinden gelebilir (ör. açık artırma galibiyeti veya mağlubiyet durumu) ya da reklamı oluşturan, sınırlanmış bir çerçeveden gelebilir. Açık artırma etkinlikleri hakkında rapor göndermek için iki ayrılmış anahtar kelime kullanabilirsiniz: reserved.win, reserved.loss ve reserved.always. Sınırlandırılmış bir çerçevedeki etkinliğin tetiklediği bir raporu göndermek için özel bir etkinlik türü tanımlayın. Etkinliği sınırlanmış bir çerçeveden tetiklemek için Fenced Frames Ads Reporting API'de bulunan fence.reportEvent() yöntemini kullanın.

Aşağıdaki örnek, açık artırma kazanma etkinliği tetiklendiğinde bir gösterim raporu ve reklamı oluşturan sınırlı ç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ş Özel Toplama Raporlaması açıklayıcısı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ğlarız. Hata ayıklama raporu, çereze dayalı ölçümlerinizi Özel Toplama ölçümlerinizle karşılaştırmak açısından kullanışlıdır ve API entegrasyonunuzu hızlı bir şekilde doğrulamanıza olanak tanır.

İş akışında privateAggregation.enableDebugMode() çağrıldığında, hata ayıklama modu etkinleştirilir. Bu da toplanabilir raporların şifrelenmemiş (cleartext) yükü içermesine neden olur. Daha sonra bu yükleri 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. 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ı, hata ayıklama anahtarı olarak BigInt kullanılabileceği privateAggregation.enableDebugMode({ <debugKey: debugKey> }) çağırarak da ayarlayabilirsiniz. Hata ayıklama anahtarı, çerez tabanlı bir ölçümden gelen verileri 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 çağrılar bir istisnaya neden olur.

// Enables debug mode
privateAggregation.enableDebugMode();

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

Doğrulamayı bildir

Paylaşılan depolama alanı için, paylaşılan depolama alanı işlem çağrısına bir bağlam kimliği ekleyerek aldığınız toplanabilir raporların meşru olduğunu doğrulayabilirsiniz. Kimlik, gönderilen rapora eklenir. Daha sonra bu kimliği kullanarak raporun paylaşılan depolama alanı işleminizden gönderildiğini doğrulayabilirsiniz.

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

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

Etkileşimde bulunun ve geri bildirim paylaşın

Private Aggregation API şu anda aktif olarak inceleniyor ve gelecekte değiştirilebilir. Bu API'yi deneyip geri bildirimlerinizi bizimle paylaşırsanız seviniriz.