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.

Özel Toplama, web'in temel aldığı önemli özellikleri sağlamak için API, siteler arası verilerin toplanıp raporlanması için tasarlanmıştır: bir yöntem izlemelisiniz.

Uygulama durumu

Teklif Durum
Paylaşılan Depolama Alanı 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 sağlayıcı 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
Google Cloud için Private Aggregation API ve Aggregation Service desteği
Açıklama		 Chrome M121 sürümünde kullanılabilir
Toplanabilir rapor yükü için dolgu
Açıklama		 Chrome M119'da kullanılabilir
auctionReportBuyers raporlaması için özel toplama hata ayıklama modu kullanılabilir
Açıklama		 Chrome M123'te kullanılabilir
Filtreleme kimliği desteği
Açıklayıcı		 Chrome M128'de kullanılabilir
İstemci tarafı katkı birleştirme
Açıklama		 Chrome M129'da kullanılabilir

Private Aggregation API nedir?

Private Aggregation API, geliştiricilerin birleştirilmiş veri raporları oluşturmasına olanak tanır Protected Audience API'den gelen verilerle ve Paylaşılan Depolama'daki siteler arası veriler.

Bu API'nin ana işlevi contributeToHistogram() olarak bilinir. Histogram işlemi, verileri bir araya getirmenizi (API'de toplama anahtarı olarak bilinir) tüm kullanıcılar için geçerlidir. Histogram çağrınız değer toplar ve gürültü uygulanmış toplu bir sonuç döndürür. özet rapor biçimidir. Örneğin raporda veya üçüncü taraf komut dosyanızda bir hatayla karşılaşan siteler. 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. 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 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, "861 Content ID'sini yaklaşık 317 benzersiz kullanıcı gördü." gibi bir yanıt sağlayabilir.

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 ardından 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. Bu ölçümleri uygulama yöntemleri hakkında daha fazla bilgi edinmek için erişim teknik makalemizi inceleyin.

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, "Yaklaşık 89 kullanıcı, 581 Content ID'yi en az 3 kez gördü." gibi bir yanıt sağlayabilir. Sayaç, farklı sitelerden Paylaşılan Depolama alanında artırılabilir ve bir iş akışında okunabilir. Sayı K'ya ulaştığında Özel Toplama aracılığıyla rapor gönderilebilir.

Çoklu dokunma ilişkilendirme

Bu kılavuz, reklam teknisyenlerinin Paylaşılan Depolama + Özel Toplama'da MTA'yı nasıl uygulayacağını anlayabilmesi için geliştirici sitesinde yayınlanacaktır.

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 contributeToHistogram() kullanarak bir araya getirebilir ve Protected Audience API'nin özel uzantısı olan contributeToHistogramOnEvent() 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 bir BigInt gereklidir. value parametresi için tam sayı bir sayı gereklidir.

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 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 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ş 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ş 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.contributeToHistogramOnEvent(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. Ç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 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 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 Ö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 erişim izni olan arayanlar tarafından kullanılabilir üçüncü taraf çerezleridir. Arayanın üçüncü taraf çerezlerine erişimi yoksa enableDebugMode(), otomatik olarak başarısız olur. Bu, üçüncü taraf çerezleri için destek 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.

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.