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

İlişkilendirme Raporları'nda hata ayıklama hakkında bölüm 2/3. Hata ayıklama raporlarınızı ayarlayın.

Sözlük

  • The reporting origin is the origin that sets the Attribution Reporting source and trigger headers. All reports generated by the browser are sent to this origin. In this guidance, we use https://adtech.example as the example reporting origin.
  • An attribution report (report for short) is the final report (event-level or aggregatable) that contains the measurement data you've requested.
  • A debug report contains additional data about an attribution report, or about a source or trigger event. Receiving a debug report does not necessarily mean that something is working incorrectly! There are two types of debug reports
  • A transitional debug report is a debug report that requires a cookie to be set in order to be generated and sent. Transitional debug reports will be unavailable if a cookie is not set, and once third-party cookies are deprecated. All debug reports described in this guide are transitional debug reports.
  • Success debug reports track successful generation of an attribution report. They relate directly to an attribution report. Success debug reports have been available since Chrome 101 (April 2022).
  • Verbose debug reports can track missing reports and help you determine why they're missing. They indicate cases where the browser did not record a source or trigger event, (which means it will not generate an attribution report), and cases where an attribution report can't be generated or sent for some reason. Verbose debug reports include a type field that describes the reason why a source event, trigger event or attribution report was not generated. Verbose debug reports are available starting in Chrome 109 (Stable in January 2023).
  • Debug keys are unique identifiers you can set on both the source side and the trigger side. Debug keys enable you to map cookie-based conversions and attribution-based conversions. When you've set up your system to generate debug reports and set debug keys, the browser will include these debug keys in all attribution reports and debug reports.

For more concepts and key terms used throughout our documentation, refer to the Privacy Sandbox glossary.

Uygulamayla ilgili sorularınız 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ı 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ılama özelliğinin arkasında kontrol edildiğ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 döndürürse 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 algılanabilir. 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 Geliştirici Araçları 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, soruna neden olan alanı belirleyip düzeltmenize yardımcı olur.

İ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ıklamasını kolaylaştırmak için tarayıcıdan gelen doğrulama hatalarını izleyebilirsiniz.

Hata ayıklama raporlarını almayı seçmek için Attribution-Reporting-Info yanıt başlığının bir parçası olarak report-header-errors ile yanıt verin.

Attribution-Reporting-Info: report-header-errors

Attribution-Reporting-Info'nun bir sözlük yapılandırılmış başlığıAttribution-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, aşağıdaki forma sahip nesnelerin JSON listesi olarak istek gövdesine 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
  }
}]
Ekran görüntüsü: başlık doğrulama aracı

Hata ayıklama raporlarını ayarlama: Başarı raporları ve ayrıntılı raporlar için ortak adımlar

Raporlama kaynağına aşağıdaki çerezi 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 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 çerezi ayarlamanız gerekmez. Başarılı 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'luk tabanda 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 tarafı hata ayıklama anahtarını, hata ayıklamayla ilgili olduğunu düşündüğünüz ek tetikleme süresi 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 yakalayın)
  • Tetikleyici hata ayıklama anahtarı olarak Çerez Kimliği + Tetikleyici zaman damgası (ve aynı zaman damgasını çerez tabanlı sisteminizde yakalayın)

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 bilgi için 3. Bölüm: Tarif Defteri'ne göz atın.

Aynı kaynak etkinlik kimliğine sahip bağımsız raporları ayırt edebilmek için kaynak tarafı hata ayıklama anahtarının source_event_id değerinden farklı olmasını sağlayı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: 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üzeyinde hem de toplu hale getirilebilir 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, yolunda ek bir debug dizesi içerecek şekilde ana ilişkilendirme uç noktasına benzer olmalıdır:

  • Etkinlik düzeyinde 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 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: Ayarlarınızın başarılı hata ayıklama raporları oluşturacağını onaylayın

  • chrome://attribution-internals adresini tarayıcınızda açın.
  • Hem Etkinlik Düzeyindeki 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 uygulamasında:
    • İlişkilendirme raporlarının doğru şekilde oluşturulduğundan emin olun.
    • Etkinlik Düzeyi Raporlar sekmesinde ve Toplanabilir Raporlar sekmesinde, başarı hata ayıklama raporlarının da oluşturulup oluşturulmadığını kontrol edin. Listede bunları mavi debug yoluyla tanıyabilirsiniz.
Ekran görüntüsü: İlişkilendirme dahili öğeleri
  • 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.
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 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ı oluşturma

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 uç nokta oluşturun

Hata ayıklama raporlarını toplamak için bir uç nokta oluşturun. Bu uç nokta, yolunda ek bir debug/verbose dizesi içerecek şekilde 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 üzerinden hemen ayrıntılı bir hata ayıklama raporu gönderir. Gelen ayrıntılı hata ayıklama raporlarını işleyecek 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ılı hata ayıklama raporlarının aksine, ayrıntılı raporlar için yalnızca bir uç nokta vardır. Etkinlik düzeyi 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 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şturulur ve 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. chrome://attribution-internals adresini tarayıcınızda açın.
  2. İlişkilendirme Raporları ile ayarlanan sitenizde bir ilişkilendirmeyi (dönüşüm) tetikleyin. Bu dönüşümden önce reklam etkileşimi (gösterim veya tıklama) olmadığı için, trigger-no-matching-source türünde ayrıntılı bir hata ayıklama raporunun oluşturulması beklenir.
  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 zamanda oluşturulan ayrıntılı hata ayıklama raporları, kaynak tarafı 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ı rapor 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, girişin türüne bağlıdır. 3. Bölüm: Hata ayıklama başlıklı makaledeki 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) bir ayrıntılı rapor. Kaynak veya tetikleyici kaydı başarısızlığının tek bir nedeni vardır. Bu nedenle, her başarısızlık 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. Bu durumun bir istisnası vardır: Başarısızlık 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