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 mevcut |
Özel Toplama hata ayıklama modunun kullanılabilirliği 3PC uygunluğuna bağlıdır GitHub sorunu |
Chrome M119 sürümünde kullanılabilir |
Rapor gecikmesi azaltılıyor Açıklayıcı |
Chrome M119 sürümünde kullanılabilir |
Google Cloud için Private Aggregation API ve Aggregation Service desteği Açıklayıcı |
Chrome M121 sürümünde kullanılabilir |
Birleştirilebilir rapor yükleri için dolgu Açıklayıcı |
Chrome M119 sürümünde kullanılabilir |
Açık Artırma Raporu Alıcıları raporlaması için kullanılabilen Özel Toplama hata ayıklama modu Açıklayıcı |
Chrome M123 sürümünde bekleniyor |
Filtreleme kimliği desteği Açıklayıcı |
Chrome M128 sürümünde bekleniyor |
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 bilinmektedir. 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. Ö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. Bu ölçümleri uygulama yöntemleri hakkında daha fazla bilgi edinmek için erişim teknik belgemizi 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, "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 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 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.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
. 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 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 durum, üçüncü tarafın
çerezlerin desteği sonlandırıldı ve hata ayıklama modu artık kullanılamayacak.
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.
- GitHub: Açıklayıcıyı okuyun, soruları sorun ve tartışmalara katılın.
- Geliştirici desteği: Özel Korumalı Alan Geliştirici Desteği deposunda soru sorun ve tartışmalara katılın.
- Özel Birleştirme ile ilgili en son duyurular için Shared Storage API grubuna ve Protected Audience API grubuna katılın.