إرسال الأحداث

يمكنك الاطّلاع على هذا الدليل السريع للتعرّف على كيفية إرسال بيانات الأحداث.

بيانات الأحداث هي مصدر بيانات إضافي لإحالاتك الناجحة التي يتم تتبُّعها باستخدام العلامة، وذلك بهدف زيادة إشارات التفاعل مع الإعلانات وتعزيز بياناتك وأدائك بشكل عام.

اختَر إصدار الدليل الذي تريد الاطّلاع عليه:

في هذا التشغيل السريع، ستكمل الخطوات التالية:

  1. إعداد Destination لتلقّي بيانات الأحداث
  2. جهِّز بيانات الأحداث لإرسالها.
  3. أنشئ طلب IngestionService للأحداث.
  4. أرسِل الطلب باستخدام Google APIs Explorer.
  5. فهم استجابات النجاح والفشل

التحضير لرحلة إلى وجهة

قبل إرسال البيانات، عليك إعداد الوجهة التي سيتم إرسال البيانات إليها. إليك نموذج Destination يمكنك استخدامه:

    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  • اضبط قيمة accountId الخاصة بـ operatingAccount على رقم تعريف حساب "إعلانات Google" الذي سيتلقّى بيانات الحدث. يجب أن تكون قيمة product الخاصة بـ operatingAccount هي GOOGLE_ADS.

  • اضبط productDestinationId على رقم تعريف إجراء الإحالة الناجحة للأحداث. يجب أن يكون إجراء الإحالة الناجحة إجراء إحالة ناجحة في "إعلانات Google" مع ضبط type على WEBPAGE.

    يوضّح هذا الدليل كيفية إنشاء طلب يرسل كل حدث إلى إجراء الإحالة الناجحة نفسه. إذا كنت تريد إرسال أحداث لعدّة إجراءات إحالات ناجحة في الطلب نفسه، اطّلِع على وجهات متعدّدة.

إعداد بيانات الأحداث

ضع في اعتبارك بيانات الحدث التالية. يتطابق كل جدول مع حدث إحالة ناجحة واحد. يتضمّن كل حدث إحالة ناجحة طابعًا زمنيًا للحدث، وإجراء الإحالة الناجحة، وقيمة الإحالة الناجحة.

قد يتضمّن كل حدث معرّفات إعلانات، مثل gclid، أو معرّفات مستخدمين، مثل عناوين البريد الإلكتروني وأرقام الهواتف ومعلومات العناوين.

في ما يلي بيانات الحدث الأول:

الحدث رقم 1
conversion_time 2025-06-10 15:07:01-05:00
conversion_action_id 123456789
transaction_id ABC798654321
conversion_value 1.99
currency USD
gclid GCLID_1
emails
given_name John
family_name Smith-Jones
region_code us
postal_code 94045

في ما يلي بيانات الحدث الثاني:

الحدث رقم 2
conversion_time June 10, 2025 11:42:33PM America/New_York
conversion_action_id 123456789
transaction_id DEF999911111
conversion_value 3.25
currency eur
gclid GCLID_2
emails

zoe@EXAMPLE.COM

cloudy.sanfrancisco@gmail.com
given_name zoë
family_name pérez
region_code PT
postal_code 1229-076

تنسيق البيانات

نسِّق الحقول وفقًا لما هو محدّد في دليل التنسيق. في ما يلي بيانات الحدث الأول بعد تنسيقه:

الحدث رقم 1
conversion_time 2025-06-10 15:07:01-05:00
conversion_action_id 123456789
transaction_id ABC798654321
conversion_value 1.99
currency USD
gclid GCLID_1
emails
given_name john
family_name smith-jones
region_code US
postal_code 94045

في ما يلي بيانات الحدث الثاني بعد التنسيق:

الحدث رقم 2
conversion_time 2025-06-10T23:42:33-05:00
conversion_action_id 123456789
transaction_id DEF999911111
conversion_value 3.25
currency EUR
gclid GCLID_2
emails

zoe@example.com

cloudysanfrancisco@gmail.com
given_name zoë
family_name pérez
region_code PT
postal_code 1229-076

تجزئة البيانات وترميزها

بالإضافة إلى ذلك، يجب تجزئة عناوين البريد الإلكتروني والأسماء المعرِّفة وأسماء العائلة المنسَّقة باستخدام خوارزمية SHA-256 وترميزها باستخدام الترميز السداسي العشري أو Base64. في ما يلي بيانات الحدث الأول بعد التنسيق والتجزئة والترميز باستخدام الترميز السداسي العشري:

الحدث رقم 1
conversion_time 2025-06-10 15:07:01-05:00
conversion_action_id 123456789
transaction_id ABC798654321
conversion_value 1.99
currency USD
gclid GCLID_1
emails
given_name 96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A
family_name DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081
region_code US
postal_code 94045

في ما يلي بيانات الحدث الثاني بعد التنسيق والتجزئة والترميز باستخدام ترميز hex:

الحدث رقم 2
conversion_time 2025-06-10T23:42:33-05:00
conversion_action_id 123456789
transaction_id DEF999911111
conversion_value 3.25
currency EUR
gclid GCLID_2
emails

3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250

223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4
given_name 2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450
family_name 6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F
region_code PT
postal_code 1229-076

تحويل البيانات إلى Event

حوِّل البيانات المنسَّقة والمجزّأة لكل حدث إلى Event. املأ الحقول المطلوبة التالية:

  • ‫event_timestamp: الوقت الذي وقع فيه الحدث.
  • ‫transaction_id: المعرّف الفريد للفعالية.
  • ‫event_source: تمثّل مصدر الحدث. في حال تحديدها، يجب أن تكون WEB.
  • ad_identifiers أو user_data: يجب أن يتضمّن الحدث معرّفًا إعلانيًا أو بيانات مستخدم. أرسِل كليهما إذا كانا متاحَين للحدث.

راجِع مستندات Event المرجعية للاطّلاع على القائمة الكاملة للحقول المتاحة. املأ أي حقل يتضمّن قيمة للحدث.

في ما يلي نموذج Event للبيانات المنسَّقة والمجزّأة والمشفّرة من الحدث الثاني:

{
   "adIdentifiers": {
      "gclid": "GCLID_2"
   },
   "conversionValue": 3.25,
   "currency": "EUR",
   "eventTimestamp": "2025-06-10T23:42:33-05:00",
   "transactionId": "DEF999911111",
   "eventSource": "WEB",
   "userData": {
      "userIdentifiers": [
         {
            "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
         },
         {
            "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
         },
         {
            "address": {
              "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
              "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
              "regionCode": "PT",
              "postalCode": "1229-076"
            }
         }
      ]
   }
}

إنشاء نص الطلب

اجمع بين Destination وEvents لنص الطلب:

{
  "destinations": [
    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  ],
  "encoding": "HEX",
  "events": [
     {
       "adIdentifiers": {
         "gclid": "GCLID_1"
       },
       "conversionValue": 1.99,
       "currency": "USD",
       "eventTimestamp": "2025-06-10T20:07:01Z",
       "transactionId": "ABC798654321",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "address": {
               "givenName": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
               "familyName": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
               "regionCode": "US",
               "postalCode": "94045"
             }
           }
         ]
       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 3.25,
       "currency": "EUR",
       "eventTimestamp": "2025-06-11T04:42:33Z",
       "transactionId": "DEF999911111",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
           },
           {
             "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
           },
           {
             "address": {
               "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
               "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
               "regionCode": "PT",
               "postalCode": "1229-076"
             }
           }
         ]
       }
     }
  ],
  "validateOnly": true
}
  1. عدِّل العناصر النائبة في نص الرسالة، مثل OPERATING_ACCOUNT_ID وCONVERSION_ACTION_1_ID، باستخدام قيم حسابك ووجهتك.
  2. اضبط validateOnly على true للتحقّق من صحة الطلب بدون تطبيق التغييرات. عندما تكون مستعدًا لتطبيق التغييرات، اضبط validateOnly على false.
  3. يُرجى العِلم أنّ هذا الطلب لا يستخدم التشفير.

إرسال الطلب

  1. انسخ نص الطلب باستخدام زر النسخ في أعلى يسار النموذج.
  2. انتقِل إلى صفحة events.ingest.
  3. انقر على الزر API على يسار الصفحة، ثم على الزر تجربة في القسم الموسّع.
  4. ألصِق نص الطلب المنسوخ في مربّع نص الطلب.
  5. انقر على الزر تنفيذ (Execute)، وأكمِل طلبات التفويض، وراجِع الردّ.

الردود الناجحة

يعرض الطلب الناجح استجابة تتضمّن عنصرًا يحتوي على requestId.

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}

ردود الفشل

يؤدي الطلب غير الناجح إلى رمز حالة استجابة خطأ، مثل 400 Bad Request، واستجابة تتضمّن تفاصيل الخطأ.

على سبيل المثال، يؤدي email_address الذي يحتوي على سلسلة نصية عادية بدلاً من قيمة بترميز سداسي عشري إلى ظهور الرد التالي:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0].user_data.user_identifiers",
            "description": "Email is not hex encoded.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

يؤدي استخدام email_address غير مجزّأ وله ترميز سداسي عشري فقط إلى عرض الاستجابة التالية:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

إرسال الأحداث إلى وجهات متعدّدة

إذا كانت بياناتك تحتوي على أحداث لوجهات مختلفة، يمكنك إرسالها في الطلب نفسه باستخدام مراجع الوجهات.

على سبيل المثال، إذا كان لديك حدث لمعرّف إجراء الإحالة الناجحة 123456789 وحدث آخر لمعرّف إجراء الإحالة الناجحة 777111122، أرسِل الحدثَين في طلب واحد من خلال ضبط reference لكل Destination. يكون reference من اختيار المستخدم، والشرط الوحيد هو أن يكون لكل Destination reference فريد. في ما يلي قائمة destinations المعدّلة للطلب:

  "destinations": [
    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "123456789"
      "reference": "conversion_action_1"
    },
    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "777111122"
      "reference": "conversion_action_2"
    }
  ]

اضبط destination_references لكل Event لإرساله إلى وجهة واحدة أو أكثر محدّدة. على سبيل المثال، إليك Event مخصّصًا فقط لأول Destination، وبالتالي لا تحتوي قائمة destination_references الخاصة به إلا على reference الخاص بأول Destination:

{
   "adIdentifiers": {
      "gclid": "GCLID_1"
   },
   "conversionValue": 1.99,
   "currency": "USD",
   "eventTimestamp": "2025-06-10T20:07:01Z",
   "transactionId": "ABC798654321",
   "eventSource": "WEB",
   "destinationReferences": [
      "conversion_action_1"
   ]
}

الحقل destination_references هو قائمة، لذا يمكنك تحديد وجهات متعدّدة لحدث معيّن. في حال عدم ضبط destination_references لأحد Event، سترسل Data Manager API الحدث إلى جميع الوجهات في الطلب.

الخطوات التالية