İlişkilendirme Raporları'nda hata ayıklama ile ilgili 3 bölümden oluşan serinin 2. bölümü. 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.examplekullanı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
typealanı 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ınız mı var?
Hata ayıklama raporlarını ayarlarken herhangi bir sorunla karşılaşırsanız geliştirici destek deposunda sorun oluşturun. Sorun giderme konusunda size 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ılama ile sınırlı olduğundan 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 başlığını ayarladığınızı kontrol edin.)
Temel entegrasyon sorunlarını düzeltme
Hata ayıklama raporları, kaybı büyük ölçekte tespit edip analiz etmenize yardımcı olmak için yararlı olsa da bazı entegrasyon sorunları yerel olarak tespit edilebilir. Kaynak ve tetikleyici üstbilgisi 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.
DevTools sorunları farklı türlerde olabilir. invalid header
Sorunla karşılaşırsanız başlığı başlık doğrulama aracına kopyalayın. Bu, soruna neden olan alanı belirlemenize ve düzeltmenize yardımcı olur.
İlişkilendirme Raporları üstbilgilerini doğrulama
Attribution Reporting API ile ilgili başlıkları doğrulamak için başlık doğrulayıcıyı kullanabilirsiniz. API'de hata ayıklamayı kolaylaştırmak için tarayıcıdan kaynaklanan doğrulama hatalarını izleyebilirsiniz.
Hata ayıklama raporlarını almayı etkinleştirmek için Attribution-Reporting-Info yanıt üstbilgisinin bir parçası olarak report-header-errors ile yanıt verin.
Attribution-Reporting-Info: report-header-errors
Attribution-Reporting-Info'nun sözlük yapılı bir başlıkAttribution-Reporting-Info olduğunu ve bu nedenle boole report-header-errors anahtarının sağlanmasının true değerini ifade ettiğini unutmayın.
Hata ayıklama raporları, raporlama uç noktasına hemen gönderilir:
https://<reporting origin>/.well-known/attribution-reporting/debug/verbose
Rapor verileri, istek gövdesine şu biçime sahip nesnelerin JSON listesi olarak eklenir:
[{
"type": "header-parsing-error",
"body": {
"context_site": "https://source.example",
"header": "Attribution-Reporting-Register-Source",
"value": "!!!", // header value received in the response
"error": "invalid JSON" // optional error details that may vary across browsers or different versions of the same browser
}
}]
Hata ayıklama raporlarını ayarlama: Başarı raporları ve ayrıntılı raporlar için ortak adımlar
Raporlama kaynağında aşağıdaki çerezi ayarlayın:
Set-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly
Tarayıcı, hem kaynakta hem de tetikleyici kaydında bu çerezin varlığını kontrol eder. Başarı hata ayıklama raporu yalnızca çerez her iki seferde de mevcutsa oluşturulur.
Hata ayıklama raporlarının, üçüncü taraf çerezlerinin devre dışı bırakıldığı B modundaki tarayıcılarda etkinleştirilebileceğini unutmayın. Bu sayede, üçüncü taraf çerezleri desteğinin sonlandırılmasına yönelik test ve hazırlık çalışmaları kolaylaştırılır. B Modu'ndaki tarayıcılarda hata ayıklama raporlarını etkinleştirmek için hata ayıklama çerezini ayarlamanız gerekmez. Başarılı hata ayıklama raporları için hata ayıklama anahtarlarını 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 işaretsiz 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ı ayarlandığında oluşturulur.
- Kaynak tarafındaki hata ayıklama anahtarını, hata ayıklama için sizinle alakalı olduğunu düşündüğünüz ek kaynak zamanı bilgileriyle eşleyin.
- Tetikleyici tarafındaki hata ayıklama anahtarını, hata ayıklama için sizinle alakalı olduğunu düşündüğünüz ek tetikleme zamanı bilgileriyle eşleyin.
Örneğin, aşağıdaki hata ayıklama anahtarlarını ayarlayabilirsiniz:
- Kaynak hata ayıklama anahtarı olarak çerez kimliği + kaynak zaman damgası (ve aynı zaman damgasını çerez tabanlı sisteminizde yakalama)
- Çerez kimliği + tetikleyici hata ayıklama anahtarı olarak tetikleyici zaman damgası (ve aynı zaman damgasını çerez tabanlı sisteminizde yakalama)
Bu sayede, ilgili hata ayıklama raporlarını veya ilişkilendirme raporlarını aramak için çerez tabanlı dönüşüm bilgilerini kullanabilirsiniz. Daha fazla bilgiyi Bölüm 3: Yemek Kitabı'nda bulabilirsiniz.
Kaynak tarafındaki hata ayıklama anahtarını source_event_id'dan farklı yapın. Böylece, aynı kaynak etkinlik kimliğine sahip raporları birbirinden 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: source debug key Demo kodu: trigger debug key
Kurulum 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 raporlarda aynı hata ayıklama anahtarları kullanılır.
3. adım: Başarı hata ayıklama raporlarını toplamak için bir uç nokta ayarlayın
Hata ayıklama raporlarını toplamak için bir uç nokta ayarlayın. Bu uç nokta, yolda ek bir debug dizesiyle birlikte ana ilişkilendirme uç noktasına benzer olmalıdır:
- Etkinlik düzeyinde başarı hata ayıklama raporlarının uç noktası:
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ı, bu uç noktaya POST isteği kullanarak hemen bir hata ayıklama raporu gönderir. Gelen başarı hata ayıklama raporlarını işlemek için 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: toplanabilir hata ayıklama raporları uç noktası
4. adım: Kurulumunuzun başarılı hata ayıklama raporları oluşturacağını onaylayın
- Tarayıcınızda
chrome://attribution-internalsadresini açın. - Hem Etkinlik Düzeyinde Raporlar hem de Toplanabilir Raporlar sekmelerinde Hata Ayıklama Raporlarını Göster onay kutusunun işaretli olduğundan emin olun.
- İlişkilendirme Raporu'nu uyguladığınız siteleri açın. İlişkilendirme raporları oluşturmak için kullandığınız adımları tamamlayın. Aynı adımlar, başarı hata ayıklama raporları oluşturmak için de kullanılır.
chrome://attribution-internalsiçinde:- İlişkilendirme raporlarının doğru şekilde oluşturulduğunu kontrol edin.
- Etkinlik Düzeyindeki Raporlar sekmesi ve Toplanabilir Raporlar sekmesinde, başarı hata ayıklama raporlarının da oluşturulduğundan emin olun. Listede mavi
debugyoluyla tanıyabilirsiniz.
- 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ılı hata ayıklama raporlarını inceleyin
Başarılı hata ayıklama raporu, ilişkilendirme raporuyla aynıdır ve hem kaynak tarafı hem de tetikleyici tarafı 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
Hem Attribution-Reporting-Register-Source hem de Attribution-Reporting-Register-Trigger içinde debug_reporting değerini 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
}
4. adım: Ayrıntılı hata ayıklama raporlarını toplamak için bir uç nokta ayarlayın
Hata ayıklama raporlarını toplamak için bir uç nokta ayarlayın. Bu uç nokta, yolda ek bir debug/verbose dizesiyle birlikte ana ilişkilendirme uç noktasına benzer olmalıdır:
https://adtech.example/.well-known/attribution-reporting/debug/verbose
Ayrıntılı hata ayıklama raporları oluşturulduğunda (yani bir kaynak veya tetikleyici kaydedilmediğinde) tarayıcı, bu uç noktaya POST isteği kullanarak ayrıntılı bir hata ayıklama raporunu hemen gönderir. Ayrıntılı gelen hata ayıklama raporlarını işlemek için 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 vardır. 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
Ayrıntılı hata ayıklama raporlarının birçok türü olsa da ayrıntılı hata ayıklama kurulumunuzu yalnızca bir tür ayrıntılı hata ayıklama raporuyla kontrol etmeniz yeterlidir. Bu ayrıntılı hata ayıklama raporu türü doğru şekilde oluşturulup alınırsa tüm ayrıntılı hata ayıklama raporu türlerinin de doğru şekilde oluşturulup alınacağı anlamına gelir. Bunun nedeni, tüm ayrıntılı hata ayıklama raporlarının aynı yapılandırmayı kullanması ve aynı uç noktaya gönderilmesidir.
- Tarayıcınızda
chrome://attribution-internalsadresini açın. - İlişkilendirme Raporları ile ayarlanmış sitenizde bir ilişkilendirme (dönüşüm) tetikleyin. Bu dönüşümden önce reklam etkileşimi (gösterim veya tıklama) olmadığı için
trigger-no-matching-sourcetüründe ayrıntılı bir hata ayıklama raporu oluşturulmasını bekleyebilirsiniz. chrome://attribution-internalsbölümünde Ayrıntılı hata ayıklama raporları sekmesini açın vetrigger-no-matching-sourcetüründe ayrıntılı bir hata ayıklama raporunun oluşturulduğunu kontrol edin.- 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
Tetikleme sırasında oluşturulan ayrıntılı hata ayıklama raporları hem kaynak tarafı hem de tetikleme tarafı hata ayıklama anahtarını (tetikleme için eşleşen bir kaynak varsa) içerir. Kaynak zamanında oluşturulan ayrıntılı hata ayıklama raporları, kaynak tarafındaki hata ayıklama anahtarını içerir.
Tarayıcı tarafından gönderilen, ayrıntılı hata ayıklama raporları içeren bir 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 ayrıntılı raporda aşağıdaki alanlar bulunur:
Type- Raporun oluşturulmasına neyin neden olduğu. Tüm ayrıntılı rapor türleri ve her türe bağlı olarak hangi işlemin yapılacağı hakkında bilgi edinmek için Bölüm 3: Hata ayıklama yemek kitabındaki ayrıntılı raporlar referansını inceleyin.
Body- Raporun gövdesi. Bu durum, türüne bağlıdır. 3. Bölüm: Hata ayıklama yemek kitabı'ndaki ayrıntılı raporlar referansını inceleyin.
Bir isteğin gövdesinde en az bir, en fazla iki ayrıntılı rapor bulunur:
- Hata yalnızca etkinlik düzeyindeki raporları etkiliyorsa (veya yalnızca toplanabilir raporları etkiliyorsa) ayrıntılı bir rapor. Bir kaynak veya tetikleyici kaydı hatasının yalnızca bir nedeni vardır. Bu nedenle, hata başına ve rapor türü başına (etkinlik düzeyinde veya toplanabilir) yalnızca bir ayrıntılı rapor oluşturulabilir.
- Hata hem etkinlik düzeyindeki hem de toplu raporları etkiliyorsa iki ayrıntılı rapor (bir istisna vardır: Hata nedeni etkinlik düzeyindeki ve toplu raporlar için aynıysa yalnızca bir ayrıntılı rapor oluşturulur (örnek:
trigger-no-matching-source))
Sıradaki
3. bölüm: Hata ayıklama kılavuzu