İlişkilendirme Raporları için hata ayıklama raporları oluşturma

İlişkilendirme raporlarında hata ayıklamayla ilgili 3 bölümden 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.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ınız mı var?

Hata ayıklama raporlarını ayarlarken herhangi bir sorunla karşılaşırsanız geliştirici destek depomuzda bir sorun kaydı oluşturun. Sorun gidermenize yardımcı oluruz.

Hata ayıklama raporları oluşturmaya 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ından kilitli 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ür ise API'ye, kontrolün çalıştırıldığı bağlamda (sayfada) izin verilir.

  • (Test aşamasında gerekli değildir: İzinler-Politika ayarladığınızı kontrol edin)

Temel entegrasyon sorunlarını düzeltme

Hata ayıklama raporları, kaybı geniş ölçekte tespit etmenize ve analiz etmenize yardımcı olsa da bazı entegrasyon sorunları yerel olarak tespit edilebilir. Kaynak ve tetikleyici üstbilgisi yapılandırma hataları, 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 ile ilgili bir sorunla karşılaşırsanız başlığı başlık doğrulayıcı aracına kopyalayın. Bu sayede soruna neden olan alanı tespit edip düzeltebilirsiniz.

İlişkilendirme raporlama üstbilgilerini doğrulama

Attribution Reporting API ile ilgili başlıkları doğrulamak için başlık doğrulayıcıyı kullanabilirsiniz. API hata ayıklama işlemini 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 üst bilgisinin 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ılandırılmış bir başlıkAttribution-Reporting-Info olduğunu unutmayın. Bu nedenle, boole report-header-errors anahtarının sağlanması doğru bir değeri ifade eder.

Hata ayıklama raporları hemen raporlama uç noktasına gönderilir:

https://<reporting origin>/.well-known/attribution-reporting/debug/verbose

Rapor verileri, istek gövdesine şu biçime sahip nesnelerin JSON listesi olarak dahil edilir:

[{
  "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
  }
}]
Ekran görüntüsü: üstbilgi doğrulama aracı

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ı, bu çerezin hem kaynakta hem de tetikleyici kaydında bulunup bulunmadığını kontrol eder. Başarı hata ayıklama raporu yalnızca çerez her iki zamanda da mevcutsa oluşturulur.

Demo kodu: debug cookie

Hata ayıklama raporlarının, üçüncü taraf çerezleri desteğinin sonlandırılmasına yönelik testleri ve hazırlıkları kolaylaştırmak için üçüncü taraf çerezlerinin devre dışı bırakıldığı B Modu'ndaki tarayıcılarda etkinleştirilebileceğini unutmayın. B modundaki tarayıcılarda, hata ayıklama raporlarını etkinleştirmek için hata ayıklama çerezini ayarlamanız gerekmez. Başarı hata ayıklama raporları için hata ayıklama anahtarları ayarlamak üzere 2. adıma atlayın.

2. adım: Hata ayıklama anahtarlarını ayarlayın

Her hata ayıklama anahtarı, 10 tabanlı bir dize olarak biçimlendirilmiş 64 bitlik, imzasız bir tam sayı olmalıdır. Her hata ayıklama anahtarının benzersiz bir kimlik olmasını sağlayın. Başarı hata ayıklama raporu yalnızca hata ayıklama anahtarları ayarlanmışsa oluşturulur.

  • Kaynak taraflı hata ayıklama anahtarını, hata ayıklama için alakalı olduğunu düşündüğünüz ek kaynak zamanı bilgileriyle eşleyin.
  • Tetikleyici taraflı hata ayıklama anahtarını, hata ayıklama için alakalı olduğunu düşündüğünüz ek tetikleyici 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 çerez tabanlı sisteminizde aynı zaman damgasını yakalayabilirsiniz)
  • Tetikleyici hata ayıklama anahtarı olarak çerez kimliği + Tetikleyici zaman damgası (ve çerez tabanlı sisteminizde aynı zaman damgasını yakalayabilirsiniz)

Böylece, ilgili hata ayıklama raporlarını veya ilişkilendirme raporlarını aramak için çerez tabanlı dönüşüm bilgilerini kullanabilirsiniz. Daha fazla bilgiyi 3. Bölüm: Tarif Defteri'nde bulabilirsiniz.

Aynı kaynak etkinlik kimliğine sahip raporları ayırt edebilmek için kaynak taraflı hata ayıklama anahtarını source_event_id'ten farklı yapın.

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

Başarı hata ayıklama raporlarını ayarlama

Bu bölümdeki örnek kod, hem etkinlik düzeyinde hem de toplanabilir raporlar için başarı hata ayıklama raporları oluşturur. Etkinlik düzeyindeki ve birleştirilebilir raporlar aynı hata ayıklama anahtarlarını kullanır.

3. adım: Başarılı hata ayıklama raporlarını toplamak için bir uç nokta oluşturun

Hata ayıklama raporlarını toplamak için bir uç nokta oluşturun. Bu uç nokta, ana ilişkilendirme uç noktasına benzer olmalıdır ve yolda ek bir debug dizesi bulunur:

  • Etkinlik düzeyindeki 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

Bir ilişkilendirme tetiklendiğinde tarayıcı, bu uç noktaya POST isteği göndererek hemen bir hata ayıklama raporu gönderir. Gelen başarı hata ayıklama raporlarını işleyen sunucu kodunuz aşağıdaki gibi görünebilir (buradaki bir düğüm uç noktası):

// 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-internals'ü açın.
  • Hem Etkinlik Seviyesinde Raporlar hem de Toplanabilir 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. Aynı adımlar, başarı hata ayıklama raporları oluşturur.
  • chrome://attribution-internals'te:
    • İlişkilendirme raporlarının doğru şekilde oluşturulup oluşturulmadığını kontrol edin.
    • Etkinlik düzeyindeki raporlar sekmesinde ve Toplanabilir raporlar sekmesinde, başarı hata ayıklama raporlarının da oluşturulup oluşturulmadığını kontrol edin. Bu öğeleri listede mavi debug yollarıyla tanıyabilirsiniz.
Ekran görüntüsü: İlişkilendirmenin iç işleyişi
  • Sunucunuzda, uç noktanızın bu başarılı hata ayıklama raporlarını hemen aldığını doğrulayın. Hem etkinlik düzeyindeki hem de toplanabilir başarı hata ayıklama raporlarını kontrol ettiğinizden emin olun.
Ekran görüntüsü: Raporlama kaynağı sunucu günlükleri

5. Adım: Başarılı hata ayıklama raporlarını gözlemleyin

Başarılı hata ayıklama raporu, ilişkilendirme raporuyla aynıdır ve hem kaynak taraflı hem de tetikleyici taraflı 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ını ayarlama

3. Adım: Kaynak ve tetikleyici üstbilgilerinde ayrıntılı hata ayıklama özelliğini etkinleştirin

Hem Attribution-Reporting-Register-Source hem de Attribution-Reporting-Register-Trigger içinde debug_reporting öğesini 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: source header

Demo kodu: trigger header

4. Adım: Ayrıntılı hata ayıklama raporlarını toplamak için bir uç nokta oluşturun

Hata ayıklama raporlarını toplamak için bir uç nokta oluşturun. Bu uç nokta, ana ilişkilendirme uç noktasına benzer olmalıdır 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 (yani bir kaynak veya tetikleyici kaydedilmediğinde) tarayıcı, bu uç noktaya POST isteği üzerinden hemen ayrıntılı bir hata ayıklama raporu gönderir. Gelen ayrıntılı hata ayıklama raporlarını işleyen sunucu kodunuz aşağıdaki gibi görünebilir (buradaki 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ılı hata ayıklama raporlarının aksine, ayrıntılı raporlar için yalnızca bir uç nokta vardır. Etkinlik düzeyindeki ve birleştirilmiş 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 raporu türleri çok sayıda 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 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 raporları da doğru şekilde oluşturulup alınır. Bunun nedeni, tüm ayrıntılı hata ayıklama raporlarının aynı yapılandırmayı kullanması ve aynı uç noktaya gönderilmesidir.

  1. Tarayıcınızda chrome://attribution-internals'ü açın.
  2. Sitenizde, İlişkilendirme Raporlaması ile ayarlanmış bir ilişkilendirme (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ündeki ayrıntılı bir hata ayıklama raporunun oluşturulmasını bekleyebilirsiniz.
  3. chrome://attribution-internals'te Ayrıntılı hata ayıklama raporları sekmesini açın ve trigger-no-matching-source türündeki ayrıntılı bir hata ayıklama raporunun oluşturulup oluşturulmadığını kontrol edin.
  4. 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ı gözlemleyin

Tetikleme zamanında oluşturulan ayrıntılı hata ayıklama raporları hem kaynak taraflı hem de tetikleyici taraflı hata ayıklama anahtarını (tetikleyici için eşleşen bir kaynak varsa) içerir. Kaynak zamanında oluşturulan ayrıntılı hata ayıklama raporları, kaynak taraflı 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"
  }
]

Ayrıntılı raporların her biri aşağıdaki alanları içerir:

Type
Raporun oluşturulmasına neyin neden olduğu. Tüm ayrıntılı rapor türleri ve her türe göre hangi işlemin yapılacağı hakkında bilgi edinmek için 3. Bölüm: Hata ayıklama yemek kitabı'ndaki ayrıntılı rapor referansını inceleyin.
Body
Raporun gövdesi. Bu durum, ürünün türüne bağlıdır. 3. Bölüm: Hata ayıklama yemek kitabı'ndaki ayrıntılı raporlar referansını inceleyin.

İsteğ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. Kaynak veya tetikleyici kaydı hatasının yalnızca bir nedeni vardır. Bu nedenle, her hata ve rapor türü (etkinlik düzeyinde veya toplanabilir) için bir ayrıntılı rapor oluşturulabilir.
  • Hata hem etkinlik düzeyindeki hem de toplanabilir raporları etkiliyorsa iki ayrıntılı rapor oluşturulur. Bununla birlikte, 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).

Sıradaki

3. Bölüm: Hata ayıklama tarif defteri