Private Aggregation API'ye genel bakış

Protected Audience'daki verileri ve Shared Storage'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 toplamak ve raporlamak üzere geliştirilmiştir.

Uygulama durumu

Private Aggregation API nedir?

Private Aggregation API, geliştiricilerin Protected Audience API'den alınan verilerle ve Shared Storage'dan alınan siteler arası verilerle 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 biriktirir ve özet rapor şeklinde gürültü eklenmiş toplu bir sonuç döndürür. Örneğin, raporda her kullanıcının içeriğinizi kaç sitede gördüğü veya üçüncü taraf komut dosyanızda bir hatayla karşılaştığı gösterilebilir. Bu işlem başka bir API'nin iş biriminde gerçekleştirilir.

Örneğin, daha önce Shared Storage'da demografik ve coğrafi veriler kaydettiyseniz Private Aggregation API'yi kullanarak New York City'deki yaklaşık kaç kullanıcının siteler arası içeriğinizi gördüğünü gösteren bir histogram oluşturabilirsiniz. Bu ölçüm için toplama işlemi yapmak üzere 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 bir değerle çağırdığınızda tarayıcı, toplanabilir bir rapor oluşturur.

Toplanabilir raporlar, toplanıp gruplandırılmak üzere 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 temel özellikleri başlıklı belgeyi inceleyin.

Attribution Reporting'den farklılıklar

Private Aggregation API, Attribution Reporting API ile birçok benzerlik gösterir. 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 oluşturulmuştur. Her iki API de, özet raporlar oluşturmak için Toplama Hizmeti arka ucu tarafından kullanılan toplanabilir raporlar üretir.

İlişkilendirme raporları, farklı zamanlarda gerçekleşen bir gösterim etkinliğinden ve bir 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 bölümündeki tüm reklam gizliliği API'lerini etkinleştirin.

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

Demoyu kullanma

Shared Storage için Private Aggregation API demosuna goo.gle/shared-storage-demo adresinden erişilebilir. Kod ise GitHub'da mevcuttur. Demoda, istemci tarafı işlemler uygulanır ve sunucunuza gönderilen toplanabilir bir rapor oluşturulur.

Protected Audience API için Private Aggregation API demosunun ileride yayınlanması planlanmaktadı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şlevlerinde 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ı ile

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

Kullanıcının içeriği daha önce görüp görmediğini belirtmek için Shared Storage'da bir işaret ayarlayabilirsiniz. İşaretin mevcut olmadığı ilk ziyarette Private Aggregation'a bir çağrı yapılır ve ardından işaret ayarlanır. Kullanıcının sonraki ziyaretlerinde (siteler arası ziyaretler dahil) Shared Storage'ı kontrol edebilir ve işaret ayarlanmışsa Private Aggregation'a rapor göndermeyi atlayabilirsiniz. Bu ölçümleri uygulama yöntemleri hakkında daha fazla bilgi edinmek için erişim teknik belgemize göz atın.

Demografi ölçümü

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

Özel toplama, "Almanya'da 18 ile 45 yaş aralığında yaklaşık 317 benzersiz kullanıcı var" gibi bir yanıt verebilir. Üçüncü taraf bağlamındaki demografi verilerine erişmek için Shared Storage'ı kullanın. Daha sonra, yaş grubu ve ülke boyutlarını toplama anahtarına kodlayarak Private Aggregation ile bir rapor oluşturabilirsiniz.

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

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

Özel toplama, "Yaklaşık 89 kullanıcı, 581 numaralı Content ID'yi 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şçik içinde okunabilir. Sayım K'ya ulaştığında Private Aggregation kullanılarak rapor gönderilebilir.

Çok noktalı 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. Private Aggregation ise alıcı ve satıcı iş parçacıklarındaki etkinlikleri raporlamanıza 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ş biriminden, verilerinizi doğrudan contributeToHistogram() kullanarak toplayabilir ve Protected Audience API'nin özel bir uzantısı olan contributeToHistogramOnEvent()'yi kullanarak verilerinizi bir tetikleyiciye göre raporlayabilirsiniz.

Kullanılabilir işlevler

Shared Storage ve Protected Audience API işlevlerinde kullanılabilen privateAggregation nesnesinde aşağıdaki işlevler bulunur.

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 BigInt gereklidir. value parametresi için tam sayı değeri gereklidir.

Aşağıda, erişim ölçümü için Shared Storage'da 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';

    // 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şleti yükler ve işleti, içerik kimliği bir toplama anahtarına (paket) dönüştürülmüş şekilde Private Aggregation API'yi çağırır.

contributeToHistogramOnEvent()

Yalnızca Protected Audience API iş parçacıklarında, belirli bir etkinlik gerçekleştiğinde rapor göndermek için tetikleyici tabanlı bir mekanizma sunarız. Bu işlev, bucket ve değerin açık artırmanın o noktasında henüz kullanılamayan 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) ya da reklamı oluşturmuş bir sınırlı alandan gelebilir.

Açık artırma etkinlikleriyle ilgili rapor göndermek için reserved.win, reserved.loss ve reserved.always olmak üzere iki ayrılmış anahtar kelime kullanabilirsiniz. Sınırlı çerçevedeki bir etkinlik tarafından 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'de bulunan fence.reportEvent() yöntemini kullanın.

Aşağıdaki örnekte, açık artırma kazanma etkinliği tetiklendiğinde bir gösterim raporu gönderilir ve reklamı oluşturmuş olan sınırlı ç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 Extended Private Aggregation Reporting açıklayıcı başlıklı makaleye göz atın.

enableDebugMode()

Üçüncü taraf çerezleri kullanılmaya devam ederken hata ayıklama modunu etkinleştirerek daha kolay hata ayıklama ve test yapılmasına olanak tanıyan geçici bir mekanizma sunacağız. Hata ayıklama raporu, çerez tabanlı ölçümlerinizi Private Aggregation ölçümlerinizle karşılaştırmanızda faydalıdır ve API entegrasyonunuzu hızlı bir şekilde doğrulamanıza olanak tanır.

İşletimde privateAggregation.enableDebugMode() işlevi çağrıldığında hata ayıklama modu etkinleştirilir. Bu durum, toplanabilir raporların şifrelenmemiş (açık metin) yükü içermesine neden olur. Daha sonra bu yükleri Aggregation Service yerel test aracıyla 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.

privateAggregation.enableDebugMode({ <debugKey: debugKey> }) çağırarak da hata ayıklama anahtarını ayarlayabilirsiniz. Burada BigInt, hata ayıklama anahtarı olarak kullanılabilir. Hata ayıklama anahtarı, çerez tabanlı ölçümden elde edilen verileri Private Aggregation ölçümünden elde edilen verilerle 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) });

Doğrulamayı bildirme

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 manipüle etmeye çalışabilir. Bunu önlemek için raporların gerçekliğini doğrulamak üzere bağlam kimliği kullanabilirsiniz.

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

• Yasa dışı veya sahte raporları önleme: Raporların yasal ve gerçek API çağrıları aracılığıyla oluşturulduğunu doğrulayarak kötü niyetli kişilerin rapor oluşturmasını zorlaştırın.
• Raporların yeniden oynatılmasını önleme: Eski raporların yeniden kullanılmaya çalışılmasını tespit edip reddederek her raporun toplu sonuçlara yalnızca bir kez katkıda bulunmasını sağlar.

Ortak Depolama

Birleştirilebilir rapor gönderebilen bir işlemi çalıştırmak için Shared Storage'ı kullanırken iş parçacığı dışında tahmin edilemeyen bir kimlik ayarlayabilirsiniz.

Bu kimlik, iş biriminden oluşturulan rapora yerleştirilir. run() veya selectURL() Paylaşılan Depolama yöntemlerini çağırırken privateAggregationConfig anahtarı altındaki seçenekler nesnesinde belirtebilirsiniz.

Örneğin:

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

Bu kimlik ayarlandıktan sonra, raporun Paylaşılan Depolama iş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, Shared Storage işlemi başına tam olarak bir rapor gönderilir (katkı yapılmamış olsa bile).

Private Aggregation API, toplanabilir 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, SharedStorage işleminin başlamasından itibaren 5 saniyelik sabit ve daha kısa bir gecikme olur.

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

1. Ortak Depolama işlemi, bir bağlam kimliği belirten bir Gizli Toplama yapılandırmasıyla çalıştırılır ve toplu bir rapor oluşturulur.
2. Bağlam kimliği, sunucunuza gönderilen oluşturulmuş toplama raporuna yerleştirilir.
3. Sunucunuz, oluşturulan toplu raporları toplar.
4. Sunucunuzdaki işlemler, raporları gruplandırıp Toplama Hizmeti'ne göndermeden önce geçerliliğini doğrulamak için her toplanabilir rapordaki bağlam kimliğini depolanan bağlam kimliklerinizle karşılaştırır.

Bağlam kimliği doğrulama

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

• Bilinmiyor: Sisteminizin oluşturmadığı bir bağlam kimliğiyle gelen raporları silebilirsiniz. Bu, bilinmeyen veya kötü amaçlı kişilerin toplama işlem hattınıza veri eklemesini engeller.
• Yinelenen: Aynı bağlam kimliğine sahip iki (veya daha fazla) rapor alırsanız hangi raporu sileceğinizi seçmeniz gerekir.
• Spam algılamada işaretlenmiş:
  • Bir kullanıcının etkinliğinde ani bir değişiklik gibi şüpheli bir etkinlik tespit ederseniz raporunu işlerken bu raporu silebilirsiniz.
  • Raporları, bağlam kimlikleriyle ve alakalı sinyallerle (ör. kullanıcı aracısı, yönlendirme kaynağı vb.) birlikte saklayabilirsiniz. Daha sonra, kullanıcı davranışını analiz edip yeni spam göstergeleri belirledikçe, depolanan raporları ilişkili bağlam kimliklerine ve sinyallere göre yeniden değerlendirebilirsiniz. Bu sayede, başlangıçta işaretlenmemiş olsalar bile şüpheli etkinlik gösteren kullanıcıların raporlarını silebilirsiniz.

Etkileşim kurma ve geri bildirim paylaşma

Private Aggregation API aktif olarak tartışılmaktadır ve gelecekte değişebilir. Bu API'yi denerseniz geri bildiriminizi bizimle paylaşmanızı rica ederiz.

• GitHub: Açıklamayı okuyun, soru sorun ve tartışmaya katılın.
• Geliştirici desteği: Privacy Sandbox Developer Support deposunda soru sorun ve tartışmalara katılın.
• Private Aggregation ile ilgili en son duyurular için Shared Storage API grubuna ve Protected Audience API grubuna katılın.