İlişkilendirme Raporlarında hata ayıklamayla ilgili Bölüm 2/3. Hata ayıklama raporlarınızı ayarlayın.
Sözlük
- Raporlama kaynağı, İlişkilendirme Raporlama kaynağı ve tetikleyici başlıklarını ayarlayan kaynaktır.
Tarayıcı tarafından oluşturulan tüm raporlar bu kaynağa gönderilir. Bu kılavuzda, örnek raporlama kaynağı olarak
https://adtech.example
kullanılmıştır. - İlişkilendirme raporu (kısaca rapor), istediğiniz ölçüm verilerini içeren nihai rapordur (etkinlik düzeyinde veya toplanabilir).
- Hata ayıklama raporu bir ilişkilendirme raporu veya bir kaynak ya da tetikleyici etkinliği hakkında ek veriler içerir. Hata ayıklama raporu almak bir şeylerin yolunda olduğu anlamına gelmez. İki tür hata ayıklama raporu vardır
- Geçişli hata ayıklama raporu, oluşturulup gönderilmesi için bir çerezin ayarlanmasını gerektiren hata ayıklama raporudur. Bir çerez ayarlanmazsa ve üçüncü taraf çerezleri kullanımdan kaldırıldığında geçişli hata ayıklama raporları kullanılamaz. Bu kılavuzda açıklanan tüm hata ayıklama raporları, geçişli hata ayıklama raporlarıdır.
- Başarı hata ayıklama raporları, ilişkilendirme raporunun başarılı bir şekilde oluşturulmasını izler. Bunlar doğrudan bir ilişkilendirme raporuyla ilişkilidir. Başarı hata ayıklama raporları, Chrome 101 sürümünden (Nisan 2022) beri kullanılabiliyor.
- Ayrıntılı hata ayıklama raporları, eksik raporları izleyebilir ve bunların neden eksik olduğunu belirlemenize yardımcı olabilir. Tarayıcının bir kaynağı kaydetmediği veya etkinliği tetiklemediği (yani ilişkilendirme raporu oluşturmadığı) ve herhangi bir nedenle ilişkilendirme raporunun oluşturulamadığı ya da gönderilemediği durumları gösterir.
Ayrıntılı hata ayıklama raporlarında kaynak etkinlik, tetikleyici etkinliği veya ilişkilendirme raporunun oluşturulmama nedenini açıklayan bir
type
alanı bulunur. Ayrıntılı hata ayıklama raporları, Chrome 109 sürümünden itibaren kullanıma sunulmuştur (Ocak 2023'te kararlı durumda). - Hata ayıklama anahtarları hem kaynak hem de tetikleyici tarafında ayarlayabileceğiniz benzersiz tanımlayıcılardır. Hata ayıklama anahtarları, çereze dayalı dönüşümleri ve ilişkilendirmeye dayalı dönüşümleri eşlemenizi sağlar. Sisteminizi hata ayıklama raporları oluşturacak ve hata ayıklama anahtarları ayarlayacak şekilde ayarladığınızda tarayıcı bu hata ayıklama anahtarlarını tüm ilişkilendirme raporlarına ve hata ayıklama raporlarına ekler.
Belgelerimizde kullanılan diğer kavramlar ve anahtar terimler için Özel Korumalı Alan sözlüğüne bakın.
Uygulamayla ilgili sorular mı var?
Hata ayıklama raporlarını ayarlarken herhangi bir sorunla karşılaşırsanız geliştirici destek depomuzda sorun oluşturun. Sorunu gidermenize yardımcı oluruz.
Hata ayıklama raporlarını ayarlamaya hazırlanma
Hata ayıklama raporlarını ayarlamadan önce aşağıdaki adımları uygulayın:
API entegrasyonu için en iyi uygulamaları uyguladığınızdan emin olun
Kodunuzun, özellik algılamanın arkasına geçildiğinden emin olun. API'nin Permissions-Policy tarafından engellenmediğinden emin olmak için aşağıdaki kodu çalıştırın:
if (document.featurePolicy.allowsFeature('attribution-reporting')) { // the Attribution Reporting API is enabled }
Bu özellik algılama kontrolü "doğru" değerini döndürürse kontrolün çalıştırıldığı bağlamda (sayfa) API'ye izin verilir.
(Test aşamasında gerekli değildir: Permissions-Policy ayarladığınızdan emin olun)
Temel entegrasyon sorunlarını giderme
Hata ayıklama raporları, kaybı geniş ölçekte tespit edip analiz etmenize yardımcı olur ancak bazı entegrasyon sorunları yerel olarak tespit edilebilir. Kaynak ve tetikleyici başlığındaki yanlış yapılandırma sorunları, JSON ayrıştırma sorunları, güvenli olmayan bağlam (HTTPS olmayan) ve API'nin çalışmasını engelleyen diğer sorunlar DevTools Sorunlar sekmesinde gösterilir.
Geliştirici Araçları sorunları farklı türlerde olabilir. Bir invalid header
sorunuyla karşılaşırsanız üst bilgiyi başlık doğrulayıcı aracına kopyalayın. Bu, soruna neden olan alanı belirleyip düzeltmenize yardımcı olur.
Hata ayıklama raporları ayarlama: Başarı raporları ve ayrıntılı raporlarda yaygın olarak kullanılan adımlar
Aşağıdaki çerezi raporlama kaynağına ayarlayın:
Set-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly
Tarayıcı, hem kaynak hem de tetikleyici kaydında bu çerezin olup olmadığını kontrol eder. Başarı hata ayıklama raporu yalnızca çerez her iki anda da mevcut olduğunda oluşturulur.
Demo kodu: hata ayıklama çerezi
Hata ayıklama raporlarının, üçüncü taraf çerezlerinin kullanımdan kaldırılmasına yönelik test ve hazırlıkları kolaylaştırmak amacıyla devre dışı bırakıldığı B Modu'ndaki tarayıcılar için etkinleştirilebileceğini unutmayın. B Modu'ndaki tarayıcılarda, hata ayıklama raporlarını etkinleştirmek için hata ayıklama çerezini ayarlamanıza gerek yoktur. Başarı hata ayıklama raporları için hata ayıklama anahtarları ayarlamak üzere 2. adıma geçin.
2. Adım: Hata ayıklama anahtarlarını ayarlayın
Her hata ayıklama anahtarı, 10 tabanlı dize olarak biçimlendirilmiş 64 bitlik imzalanmamış bir tam sayı olmalıdır. Her hata ayıklama anahtarını benzersiz bir kimlik yapın. Başarı hata ayıklama raporu yalnızca hata ayıklama anahtarları ayarlanmışsa oluşturulur.
- Kaynak tarafı hata ayıklama anahtarını, hata ayıklamanız için alakalı olduğunu düşündüğünüz ek kaynak zamanı bilgilerine eşleyin.
- Tetikleyici tarafı hata ayıklama anahtarını, hata ayıklamanız için alakalı olduğunu düşündüğünüz ek tetikleme zamanı bilgilerine eşleyin.
Örneğin, aşağıdaki hata ayıklama anahtarlarını ayarlayabilirsiniz:
- Kaynak hata ayıklama anahtarı olarak Çerez Kimliği ve Kaynak zaman damgası (ve aynı zaman damgasını çerez tabanlı sisteminize kaydedin)
- Tetikleyici hata ayıklama anahtarı olarak Çerez Kimliği ve Tetikleyici zaman damgası (ve aynı zaman damgasını çerez tabanlı sisteminize kaydedin)
Bu sayede karşılık gelen hata ayıklama raporlarını veya ilişkilendirme raporlarını aramak için çereze dayalı dönüşüm bilgilerini kullanabilirsiniz. Daha fazla bilgiyi 3. Bölüm: Yemek Defteri bölümünde bulabilirsiniz.
Kaynak taraflı hata ayıklama anahtarını source_event_id
öğesinden farklı hale getirerek aynı kaynak etkinlik kimliğine sahip farklı raporları ayırt edebilirsiniz.
Attribution-Reporting-Register-Source:
{
// … Usual fields for Attribution-Reporting-Register-Source
"debug_key":"647775351539539"
}
Attribution-Reporting-Register-Trigger:
{
// … Usual fields for Attribution-Reporting-Register-Trigger
"debug_key":"938321351539743"
}
Demo kodu: kaynak hata ayıklama anahtarı Demo kodu: tetikleyici hata ayıklama anahtarı
Başarı hata ayıklama raporlarını ayarlama
Bu bölümdeki örnek kod, hem etkinlik düzeyindeki hem de toplanabilir raporlar için başarı hata ayıklama raporları oluşturur. Etkinlik düzeyindeki ve toplanabilir raporlar aynı hata ayıklama anahtarlarını kullanır.
3. adım: Başarı hata ayıklama raporlarını toplamak için uç nokta oluşturun
Hata ayıklama raporlarını toplamak için bir uç nokta ayarlayın. Bu uç nokta, ana ilişkilendirme uç noktasına benzer olmalı ve yolda ek bir debug
dizesi bulunmalıdır:
- Etkinlik düzeyi başarı hata ayıklama raporları için uç nokta:
https://adtech.example/.well-known/attribution-reporting/debug/report-event-attribution
- Toplanabilir başarı hata ayıklama raporları için uç nokta:
https://adtech.example/.well-known/attribution-reporting/debug/report-aggregate-attribution
- Toplanabilir başarı hata ayıklama raporları için uç nokta:
Bir ilişkilendirme tetiklendiğinde, tarayıcı POST
isteği aracılığıyla bu uç noktaya hemen bir hata ayıklama raporu gönderir. Gelen başarı hata ayıklama raporlarını işlemek için gerekli sunucu kodunuz aşağıdaki gibi görünebilir (burada bir düğüm uç noktasında):
// Handle incoming event-Level Success Debug reports
adtech.post(
'/.well-known/attribution-reporting/debug/report-event-attribution',
async (req, res) => {
// Debug report is in req.body
res.sendStatus(200);
}
);
// Handle incoming aggregatable Success Debug reports
adtech.post(
'/.well-known/attribution-reporting/debug/report-aggregate-attribution',
async (req, res) => {
// Debug report is in req.body
res.sendStatus(200);
}
);
Demo kodu: Etkinlik düzeyinde hata ayıklama raporları uç noktası
Demo kodu: Birleştirilebilir hata ayıklama raporları uç noktası
4. Adım: Kurulumunuzun başarı hata ayıklama raporu oluşturacağını onaylayın
chrome://attribution-internals
sayfasını tarayıcınızda açın.- Hem Etkinlik Düzeyindeki Raporlar hem de Birleştirilebilir Raporlar sekmelerinde Hata Ayıklama Raporlarını Göster onay kutusunun işaretli olduğundan emin olun.
- İlişkilendirme Raporlamasını uyguladığınız siteleri açın. İlişkilendirme raporları oluşturmak için kullandığınız adımları tamamlayın. Bu adımlar başarıyla hata ayıklama raporları oluşturur.
chrome://attribution-internals
ürününde:- İlişkilendirme raporlarının doğru şekilde oluşturulup oluşturulmadığını kontrol edin.
- Etkinlik Düzeyindeki Raporlar ve Birleştirilebilir Raporlar sekmesinde, başarı hata ayıklama raporlarının da oluşturulduğundan emin olun. Bunları listede mavi
debug
yolu ile tanıyın.
- Sunucunuzda, uç noktanızın bu başarı hata ayıklama raporlarını hemen aldığını doğrulayın. Hem etkinlik düzeyinde hem de toplanabilir başarı hata ayıklama raporlarını kontrol ettiğinizden emin olun.
5. Adım: Başarı hata ayıklama raporlarını inceleyin
Başarı hata ayıklama raporu, ilişkilendirme raporuyla aynıdır ve hem kaynak tarafı hem de tetikleyici tarafındaki hata ayıklama anahtarlarını içerir.
{
"attribution_destination": "https://advertiser.example",
"randomized_trigger_rate": 0.0000025,
"report_id": "7d76ef29-d59e-4954-9fff-d97a743b4715",
"source_debug_key": "647775351539539",
"source_event_id": "760938763735530",
"source_type": "event",
"trigger_data": "0",
"trigger_debug_key": "156477391437535"
}
{
"aggregation_service_payloads": [
{
"debug_cleartext_payload": "omRkYXRhgqJldmFsdWVEAACAAGZidWNrZXRQPPhnkD+7c+wm1RjAlowp3KJldmFsdWVEAAARMGZidWNrZXRQJFJl9DLxbnMm1RjAlowp3GlvcGVyYXRpb25paGlzdG9ncmFt",
"key_id": "d5f32b96-abd5-4ee5-ae23-26490d834012",
"payload": "0s9mYVIuznK4WRV/t7uHKquHPYCpAN9mZHsUGNiYd2G/9cg87Y0IjlmZkEtiJghMT7rmg3GtWVPWTJU5MvtScK3HK3qR2W8CVDmKRAhqqlz1kPZfdGUB4NsXGyVCy2UWapklE/r7pmRDDP48b4sQTyDMFExQGUTE56M/8WFVQ0qkc7UMoLI/uwh2KeIweQCEKTzw"
}
],
"shared_info": "{\"api\":\"attribution-reporting\",\"attribution_destination\":\"https://advertiser.example\",\"debug_mode\":\"enabled\",\"report_id\":\"4a04f0ff-91e7-4ef6-9fcc-07d000c20495\",\"reporting_origin\":\"https://adtech.example\",\"scheduled_report_time\":\"1669888617\",\"source_registration_time\":\"1669852800\",\"version\":\"0.1\"}",
"source_debug_key": "647775351539539",
"trigger_debug_key": "156477391437535"
}
Ayrıntılı hata ayıklama raporları ayarlama
3. Adım: Kaynak ve tetikleyici başlıklarında ayrıntılı hata ayıklamayı etkinleştirin
debug_reporting
öğesini hem Attribution-Reporting-Register-Source
hem de Attribution-Reporting-Register-Trigger
içinde true
olarak ayarlayın.
Attribution-Reporting-Register-Source:
{
// … Usual fields for Attribution-Reporting-Register-Source
"debug_key":"938321351539743",
"debug_reporting": true // defaults to false if not present
}
Attribution-Reporting-Register-Trigger:
{
// … Usual fields for Attribution-Reporting-Register-Trigger
"debug_key":"938321351539743",
"debug_reporting": true // defaults to false if not present
}
Demo kodu: tetikleyici üst bilgisi
4. adım: Ayrıntılı hata ayıklama raporları toplamak için uç nokta oluşturun
Hata ayıklama raporlarını toplamak için bir uç nokta ayarlayın. Bu uç nokta, ana ilişkilendirme uç noktasına benzer olmalı ve yolda ek bir debug/verbose
dizesi bulunmalıdır:
https://adtech.example/.well-known/attribution-reporting/debug/verbose
Ayrıntılı hata ayıklama raporları oluşturulduğunda (bir kaynak veya tetikleyici kaydedilmezse) tarayıcı, POST
isteği aracılığıyla bu uç noktaya hemen bir ayrıntılı hata ayıklama raporu gönderir. Gelen ayrıntılı hata ayıklama raporlarını işlemek için gereken sunucu kodunuz aşağıdaki gibi görünebilir (burada bir düğüm uç noktasında):
// Handle incoming verbose debug reports
adtech.post(
'/.well-known/attribution-reporting/debug/verbose',
async (req, res) => {
// List of verbose debug reports is in req.body
res.sendStatus(200);
}
);
Başarı hata ayıklama raporlarının aksine, ayrıntılı raporlar için yalnızca bir uç nokta bulunur. Etkinlik düzeyindeki ve toplu raporlarla ilgili ayrıntılı raporların tümü aynı uç noktaya gönderilir.
Demo kodu: Ayrıntılı hata ayıklama raporları uç noktası
5. Adım: Kurulumunuzun ayrıntılı hata ayıklama raporları oluşturacağını onaylayın
Çok sayıda ayrıntılı hata ayıklama raporu türü olsa da ayrıntılı hata ayıklama ayarlarınızı yalnızca bir tür ayrıntılı hata ayıklama raporuyla kontrol etmeniz yeterlidir. Bu tür bir ayrıntılı hata ayıklama raporu doğru şekilde oluşturulup alınırsa tüm ayrıntılı hata ayıklama raporları aynı yapılandırmayı kullandığından ve aynı uç noktaya gönderildiğinden bu, her tür ayrıntılı hata ayıklama raporunun da doğru şekilde oluşturulup alınacağı anlamına gelir.
chrome://attribution-internals
sayfasını tarayıcınızda açın.- İlişkilendirme Raporlama ile ayarlanan sitenizde bir ilişkilendirmeyi (dönüşüm) tetikleyin. Bu dönüşümden önce reklam etkileşimi (gösterim veya tıklama) olmadığından,
trigger-no-matching-source
türünde ayrıntılı bir hata ayıklama raporu oluşturulur. chrome://attribution-internals
aracında Ayrıntılı hata ayıklama raporları sekmesini açın vetrigger-no-matching-source
türünde bir ayrıntılı hata ayıklama raporunun oluşturulduğundan emin olun.- Sunucunuzda, uç noktanızın bu ayrıntılı hata ayıklama raporunu hemen aldığını doğrulayın.
6. adım: Ayrıntılı hata ayıklama raporlarını inceleyin
Tetikleyici zamanında oluşturulan ayrıntılı hata ayıklama raporları, hem kaynak tarafı hem de tetikleyici tarafı hata ayıklama anahtarını (tetikleyici için eşleşen bir kaynak varsa) içerir. Kaynak zamanda oluşturulan ayrıntılı hata ayıklama raporları, kaynak tarafı hata ayıklama anahtarını içerir.
Ayrıntılı hata ayıklama raporları içeren ve tarayıcı tarafından gönderilen istek örneği:
[
{
"body": {
"attribution_destination": "http://arapi-advertiser.localhost",
"randomized_trigger_rate": 0.0000025,
"report_id": "92b7f4fd-b157-4925-999e-aad6361de759",
"source_debug_key": "282273499788483",
"source_event_id": "480041649210491",
"source_type": "event",
"trigger_data": "1",
"trigger_debug_key": "282273499788483"
},
"type": "trigger-event-low-priority"
},
{
"body": {
"attribution_destination": "http://arapi-advertiser.localhost",
"limit": "65536",
"source_debug_key": "282273499788483",
"source_event_id": "480041649210491",
"source_site": "http://arapi-publisher.localhost",
"trigger_debug_key": "282273499788483"
},
"type": "trigger-aggregate-insufficient-budget"
}
]
Her bir ayrıntılı rapor aşağıdaki alanları içerir:
Type
- Raporun oluşturulmasının nedeni. Tüm ayrıntılı rapor türleri ve her bir türe bağlı olarak yapılması gereken işlemler hakkında bilgi edinmek için 3. Bölüm: Hata ayıklama kılavuzundaki ayrıntılı rapor referansını inceleyin.
Body
- Rapor gövdesi. Bu değer, türüne bağlıdır. 3. Bölüm: Hata ayıklama kılavuzundaki ayrıntılı rapor referansını inceleyin.
İsteğin gövdesi en az bir, en fazla iki ayrıntılı rapor içerir:
- Hata yalnızca etkinlik düzeyindeki raporları etkiliyorsa (veya yalnızca toplanabilir raporları etkiliyorsa) bir ayrıntılı rapor. Kaynak veya tetikleyici kayıt hatasının yalnızca tek bir nedeni vardır. Bu nedenle, her hata ve rapor türü (etkinlik düzeyinde veya toplanabilir) başına bir ayrıntılı rapor oluşturulabilir.
- Hata hem etkinlik düzeyinde hem de toplanabilir raporları etkiliyorsa iki ayrıntılı rapor. Bir istisna söz konusudur: Hata nedeni etkinlik düzeyindeki ve toplanabilir raporlar için aynıysa yalnızca bir ayrıntılı rapor oluşturulur (örnek:
trigger-no-matching-source
)