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

İ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

  • 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 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
  }
}]
Üstbilgi doğrulama aracı
Ü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ı, 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.

Demo kodu: debug cookie

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

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-internals adresini 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-internals iç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 debug yoluyla tanıyabilirsiniz.
İlişkilendirme iç işleyişi
İlişkilendirme iç işleyişi
  • 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.
Raporlama kaynak sunucusu günlükleri
Raporlama kaynağı sunucu günlükleri

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
}

Demo kodu: kaynak başlığı

Demo kodu: trigger header

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.

  1. Tarayıcınızda chrome://attribution-internals adresini açın.
  2. İ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-source türünde ayrıntılı bir hata ayıklama raporu oluşturulmasını bekleyebilirsiniz.
  3. chrome://attribution-internals bölümünde Ayrıntılı hata ayıklama raporları sekmesini açın ve trigger-no-matching-source türünde ayrıntılı bir hata ayıklama raporunun oluşturulduğunu 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ı 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