İlişkilendirme Raporlama için bağlı hizmetlere, teknik karar mercilerine yönelik üst düzey genel bakış.
Attribution Reporting API, reklam teknolojilerinin ve reklamverenlerin, bir reklam tıklaması veya görüntülemesinin satın alma gibi bir dönüşümle sonuçlandığı durumu ölçmesine olanak tanır. Bu API, iş ihtiyaçlarınıza bağlı olarak istemci tarafı ve sunucu tarafı entegrasyonlarının bir kombinasyonunu kullanır.
Devam etmeden önce İlişkilendirme Raporlamasına genel bakış bölümünü okuduğunuzdan emin olun. Bu, API'nin amacını ve farklı çıkış raporlarının (etkinlik düzeyinde rapor ve özet raporları) akışını anlamanıza yardımcı olur. Bilmediğiniz terimlerle karşılaşırsanız Özel Korumalı Alan sözlüğüne bakın.
Bu makale kimler için hazırlanmıştır?
Bu makaleyi aşağıdaki durumlarda okumalısınız:
- Reklam teknolojisi veya reklamverenin teknik karar merciiyseniz. Operasyonlar, DevOps, veri bilimi, BT, pazarlama alanlarında veya teknik uygulama kararları verdiğiniz başka bir rolde çalışabilirsiniz. API'lerin, gizliliği korumaya yönelik ölçümlerde nasıl çalıştığını merak ediyorsunuz.
- Geliştirici, sistem operatörü, sistem mimarı veya veri bilimci gibi bir teknik uzmansanız, bu API ve Toplama Hizmeti ortamıyla denemeler oluşturacaksınız.
Bu makalede, Attribution Reporting API için hizmetlerin nasıl çalıştığına dair kapsamlı, uçtan uca bir açıklama bulacaksınız. Teknik uzmansanız bu API ile yerel olarak denemeler yapabilirsiniz.
Genel bakış
Attribution Reporting API özel kurulum, istemci tarafı yapılandırmalar ve sunucu dağıtımları gerektiren birçok hizmetten oluşur. Neye ihtiyacınız olduğuna karar vermek için önce:
- Tasarımla ilgili kararlar alma. Toplamak istediğiniz bilgileri tanımlayın, herhangi bir kampanyadan beklediğiniz dönüşümleri tanımlayın ve hangi rapor türünün toplanacağını belirleyin. Nihai çıktı, şu iki rapor türünden biri veya ikisi de olabilir: etkinlik düzeyindeki raporlar ve özet raporlar.
Raporlamayı desteklemek için birlikte çalışan iki (ve bazen üç) bileşen her zaman vardır:
- Web sitesi ile tarayıcı arasında iletişim. Çerez tabanlı sistemlerde, dönüşümler ve reklam etkileşimlerine ait bilgiler, sizin veya bir analiz hizmetinin daha sonra bu etkinliklere katılabilmesini sağlayan bir tanımlayıcıya eklenir. Bu API sayesinde tarayıcı, analiz için yayınlanmadan önce talimatlarınıza dayanarak dönüşümleri reklam tıklamaları/görüntülemeleriyle ilişkilendirir. Bu nedenle, reklam oluşturma kodunuz ve dönüşüm izleme özelliğiniz:
- Tarayıcıya, hangi dönüşümlerin hangi reklam tıklamaları veya gösterimleriyle ilişkilendirilmesi gerektiğini bildirin.
- Nihai raporlara dahil edilecek diğer verileri belirtin.
- Veri toplama. Kullanıcıların tarayıcılarında oluşturulan raporları almak için bir toplayıcı uç noktasına ihtiyacınız vardır. Tarayıcılardan elde edilen çıkış, iki olası rapordan biri olabilir: etkinlik düzeyindeki raporlar ve toplanabilir raporlar (şifrelenmiş olup özet raporları oluşturmak için kullanılır).
Birleştirilebilir raporlar topladıysanız üçüncü bir bileşene ihtiyacınız vardır:
- Özet rapor oluşturma. Özet rapor oluşturmak amacıyla raporları işlemek için toplu olarak toplanabilir raporları kullanma ve Toplama Hizmeti'ni kullanma.
Tasarım kararları
İlişkilendirme Raporlarının temel ilkelerinden biri, tasarıma dair önceden verilen kararlardır. Hangi kategorilerde hangi verileri toplayacağınıza ve bu verileri ne sıklıkla işleyeceğinize siz karar verirsiniz. Çıkış raporları, kampanyalarınız veya işinizle ilgili analizler sağlar.
Çıkış raporu şöyle olabilir:
- Etkinlik düzeyindeki raporlar, belirli bir reklam tıklamasını veya görüntülemesini (reklam tarafında) dönüşüm tarafındaki verilerle ilişkilendirir. Siteler arasında kullanıcı kimliğinin birleştirilmesini sınırlandırarak kullanıcı gizliliğini korumak için, dönüşüm tarafı verileri çok sınırlıdır ve veriler gürültülüdür (diğer bir deyişle, vakaların küçük bir yüzdesinde gerçek raporlar yerine rastgele veriler gönderilir).
- Özet raporları reklam tarafındaki belirli bir etkinliğe bağlı değildir. Bu raporlar, daha ayrıntılı dönüşüm verilerinin yanı sıra tıklama ve görüntüleme verilerini dönüşüm verileriyle birleştirmek için esneklik sunar.
Rapor seçiminiz, hangi verileri toplamanız gerektiğini belirler.
Nihai çıktıyı karar alırken kullandığınız araçlar için bir girdi olarak da düşünebilirsiniz. Örneğin, kaç dönüşümün toplam harcama değerine yol açtığını belirlemek için özet raporlar oluşturursanız bu, ekibinizin daha yüksek bir toplam harcama elde etmek için sonraki reklam kampanyanızda neleri hedeflemesi gerektiğine karar vermesine yardımcı olabilir.
Neyi ölçmek istediğinize karar verdikten sonra Attribution Reporting API için istemci tarafını ayarlayabilirsiniz.
Web sitesi ile tarayıcı arasında iletişim
![Yayıncının web sitesindeki ilişkilendirme kaynakları, reklamverenin web sitesindeki tetikleyicilerle bağlantı kurar.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/attribution-sources-a-pu-b04d5ed143672.png?authuser=5&hl=tr)
İlişkilendirme etkinliği akışı
Reklam görüntüleyen bir yayıncı sitesi düşünün. Her reklamveren veya reklam teknolojisi sağlayıcı, reklamlarıyla kurulan etkileşimler hakkında bilgi edinmek ve dönüşümleri doğru reklamla ilişkilendirmek ister. Raporlar (hem etkinlik düzeyinde hem de toplanabilir) aşağıdaki gibi oluşturulur:
Yayıncı sitesinde,
attributionsrc
özel özelliğiyle bir reklam öğesi (<a>
veya<img>
etiketi) yapılandırılır. Bunun değeri bir URL'dir (örneğin,https://adtech.example/register-source/ad_id=...
).Tıklandığında bir kaynağı kaydedecek bağlantı örneğini burada bulabilirsiniz:
<a href="https://shoes.example/landing" attributionsrc="http://adtech.example/register-source?..." target="_blank"> Click me</a>
Görüntülendiğinde kaynağın kaydedilmesine neden olacak resim örneği aşağıda verilmiştir:
<img href="https://advertiser.example/landing" attributionsrc="https://adtech.example/register-source?..."/>
Alternatif olarak, HTML öğeleri yerine JavaScript çağrıları kullanılabilir.
window.open()
kullanan JavaScript örneğini aşağıda bulabilirsiniz. Özel karakterlerle ilgili sorunları önlemek için URL'nin URL olarak kodlandığını unutmayın.const encodedUrl = encodeURIComponent( 'https://adtech.example/attribution_source?ad_id=...'); window.open( "https://shoes.example/landing", "_blank", attributionsrc=${encodedUrl});
- Kullanıcı reklamı tıkladığında veya görüntülediğinde tarayıcı,
attributionsrc
adresine (genellikle bir reklamveren veya reklam teknolojisi sağlayıcı uç noktası) birGET
isteği gönderir. Bu isteği aldıktan sonra reklamveren veya reklam teknolojisi sağlayıcı, dönüşümlerin daha sonra bu reklamla ilişkilendirilebilmesi için tarayıcıya, reklamla etkileşimler için kaynak etkinlikleri kaydetmesi talimatını verir. Reklamveren veya reklam teknolojisi sağlayıcı bunu yapmak için yanıtına özel bir HTTP başlığı ekler. Bu özel veri, kaynak etkinlikle (reklam tıklaması veya görüntüleme) ilgili bilgi sağlayan özel verilere eklenir. Söz konusu reklam için bir dönüşüm gerçekleşirse bu özel veriler, nihayetinde ilişkilendirme raporunda gösterilir.
Daha sonra, kullanıcı reklamverenin sitesini ziyaret eder.
Reklamverenin sitesindeki alakalı sayfaların her birinde (örneğin, satın alma onay sayfası veya ürün sayfası), bir dönüşüm pikseli (
<img>
öğesi) veya JavaScript çağrısı,https://adtech.example/conversion?param1=...¶m2=...
öğesine bir istek yapar.Bu URL'deki hizmet (genellikle reklamveren veya reklam teknolojisi sağlayıcı) isteği alır. Bunu bir dönüşüm olarak sınıflandırmaya karar verir. Bu yüzden tarayıcıya bir dönüşüm kaydetme, yani ilişkilendirmeyi tetikleme talimatı vermesi gerekir. Bunu yapmak için reklamveren veya reklam teknolojisi sağlayıcı, piksel isteğine verilen yanıta dönüşümle ilgili özel veriler içeren özel bir HTTP başlığı ekler.
Kullanıcının yerel cihazındaki tarayıcı bu yanıtı alır ve dönüşüm verilerini orijinal kaynak etkinlikle (reklam tıklaması veya görüntüleme) eşleştirir. Daha fazla bilgi için Kaynakları tetikleyicilerle eşleştirme bölümüne bakın.
Tarayıcı,
attributionsrc
adresine gönderilecek bir rapor planlar. Bu rapor şunları içerir:- Reklam teknolojisi sağlayıcısının veya reklamverenin 3. adımda kaynak etkinliğe eklediği özel ilişkilendirme yapılandırma verileri.
- 6. adımdaki özel dönüşüm verisi kümesi.
Daha sonra tarayıcı, raporları
attributionsrc
politikasında tanımlanan uç noktaya, gecikme ve parazitle birlikte gönderir. Toplanabilir raporlar şifrelenir, ancak etkinlik düzeyindeki raporlar şifrelenmez.
İlişkilendirme tetikleyicileri (reklamverenin web sitesi)
İlişkilendirme tetikleyicisi tarayıcıya dönüşümleri yakalamasını bildiren etkinliktir.
Reklamveren için en önemli dönüşümleri (satın alma işlemleri gibi) yakalamanızı öneririz. Özet raporlara birden çok dönüşüm türü ve meta veri yakalanabilir.
Bu, toplu sonuçların bu etkinlikler için ayrıntılı ve doğru olmasını sağlar.
Kaynakları tetikleyicilerle eşleştirme
İlişkilendirme tetikleyicisi yanıtı aldığında tarayıcı, hem ilişkilendirme tetikleyicisinin kaynağı hem de sayfa URL'sinin eTLD+1 kısmıyla eşleşen bir kaynak bulmak için yerel depolama alanına erişir.
Örneğin, tarayıcı shoes.example/shoes123
üzerinde adtech.example
kaynağından bir ilişkilendirme tetikleyicisi aldığında, yerel depolama alanında hem adtech.example
hem de shoes.example
ile eşleşen bir kaynak arar.
Bir tetikleyicinin belirli bir kaynakla ne zaman eşleneceğini belirlemek için filtreler (veya özel kurallar) ayarlanabilir. Örneğin, yalnızca belirli bir ürün kategorisine ilişkin dönüşümleri sayacak bir filtre ayarlayın ve diğer tüm kategorileri göz ardı edin. Filtreler ve önceliklendirme modelleri, daha gelişmiş ilişkilendirme raporlamasına olanak tanır.
Yerel depolama alanında birden fazla ilişkilendirme kaynağı bulunursa, tarayıcı en son depolanan kaynağı seçer. İlişkilendirme kaynaklarına öncelik verilen bazı durumlarda, tarayıcı en yüksek önceliğe sahip kaynağı seçer.
Veri toplama
Karşılık gelen kaynakla eşleştirilen ilişkilendirme tetikleyicileri birlikte, tarayıcı tarafından reklam teknolojisine ait sunucudaki raporlama uç noktasına (bazen toplama uç noktası veya toplama hizmeti olarak da adlandırılır) rapor olarak gönderilir. Bu raporlar, etkinlik düzeyinde raporlar veya toplanabilir raporlar olabilir.
Birleştirilebilir raporlar özet raporlar oluşturmak için kullanılır. Birleştirilebilir rapor, reklam teknolojisi tarafından toplanmadan önce kullanıcının cihazında tarayıcı tarafından oluşturulan ve şifrelenen reklamdan (yayıncının sitesinde) ve dönüşüm verilerinden (reklamverenin sitesinden) toplanan verilerin kombinasyonudur.
Etkinlik düzeyindeki raporlar 2 ila 30 gün gecikmelidir. Toplanabilir raporlar, bir saat içinde rastgele bir gecikmeyle gönderilir ve etkinlikler katkı bütçesine uygun olmalıdır. Bu seçimler gizliliği korur ve bireysel kullanıcının işlemlerinin istismar edilmesini önler.
Yalnızca etkinlik düzeyindeki raporlarla ilgileniyorsanız ihtiyacınız olan son altyapı parçası budur. Ancak özet raporlar oluşturmak istiyorsanız toplanabilir raporları ek bir hizmetle işlemeniz gerekir.
Özet rapor oluşturma
Özet raporlar oluşturmak amacıyla, birleştirilmiş raporları işlemek için reklam teknolojisi tarafından işletilen Toplama Hizmeti'ni kullanırsınız. Toplama Hizmeti, kullanıcı gizliliğini korumak için gürültü ekler ve nihai özet raporunu döndürür.
![Toplanabilir raporlar toplanır, gruplanır ve reklam teknolojisi ortamına gönderilir.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/aggregatable-reports-are-a0830fd543e6f.png?authuser=5&hl=tr)
Toplanan ve toplanabilir raporların gruplanmasından sonra grup, Toplama Hizmeti tarafından işlenir. Bir koordinatör, şifre çözme anahtarlarını yalnızca Toplama Hizmeti'nin onaylanmış sürümlerine verir. Toplama Hizmeti verilerin şifresini çözer, verileri toplar ve sonuçları özet rapor olarak döndürmeden önce gürültü ekler.
Toplu olarak toplanabilir raporlar
Birleştirilebilir raporların işlenmeden önce toplu hale getirilmesi gerekir. Toplu, stratejik olarak gruplandırılmış, toplanabilir raporlardan oluşur. Stratejiniz büyük olasılıkla belirli bir dönemi (günlük veya haftalık gibi) yansıtır. Bu işlem, raporlama uç noktanız olarak işlev gören sunucuda da gerçekleşebilir.
Sinyal-gürültü oranının yüksek olması için gruplar çok sayıda rapor içermelidir.
![Daha uzun zaman dilimleri, daha az gürültülü sonuçlar sağlar.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/larger-periods-lead-les-4d4edffb3d2d6.png?authuser=5&hl=tr)
Yıllık indirim gibi daha yüksek hacim beklediğiniz belirli etkinlikleri yakalamanızı sağlamak için grup dönemleri herhangi bir zamanda değişebilir. Toplu işleme süresi, ilişkilendirme kaynaklarını veya tetikleyicileri değiştirmeye gerek kalmadan değiştirilebilir.
Toplama Hizmeti
Toplama Hizmeti, özet raporu oluşturmak için birleştirilebilir raporları işlemekten sorumludur. Toplanabilir raporlar şifrelenir ve yalnızca güvenilir yürütme ortamında (TEE) çalışan Toplama Hizmeti tarafından okunabilir.
Toplama Hizmeti, verilerin şifresini çözmek ve veri toplamak için koordinatörden şifre çözme anahtarları ister. Şifresi çözülüp toplandıktan sonra sonuçlar, gizliliği korumak için gürültü eklenir ve özet rapor olarak döndürülür.
Uygulayıcılar, Toplama Hizmeti'ni yerel olarak test etmek için birleştirilebilir şifresiz metin raporları oluşturabilir. Alternatif olarak, Nitro Enclaves ile AWS'de şifrelenmiş raporlarla test yapabilirsiniz.
Sonraki adım
Herkese uygun bir API geliştirmek için sizinle görüşmeler yapmak istiyoruz.
API hakkında görüşün
Diğer Özel Korumalı Alan API'lerinde olduğu gibi bu API de belgelenir ve herkese açık olarak tartışılır.
API ile denemeler yapma
Attribution Reporting API ile ilgili olarak denemeler yapabilir ve görüşmelere katılabilirsiniz.