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

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

بيانات الأحداث هي مصدر بيانات إضافي للإحالات الناجحة لعلامتك، وذلك لزيادة إشارات التفاعل مع الإعلان إلى أقصى حد وتعزيز بياناتك وأداء حملاتك بشكل عام.

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

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

  1. حضِّر Destination لتلقّي بيانات الأحداث.
  2. حضِّر بيانات الحدث لإرسالها.
  3. أنشئ طلبًا للحصول على IngestionService للأحداث.
  4. أرسِل الطلب باستخدام "مستكشف Google APIs".
  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
last_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ë
last_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
last_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ë
last_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
last_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
last_name 6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F
region_code PT
postal_code 1229-076

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

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

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

يُرجى الرجوع إلى المستندات المرجعية Event للحصول على القائمة الكاملة للحقول المتاحة. املأ أيّ حقل تتوفّر فيه قيمة للحدث.

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

{
   "adIdentifiers": {
      "gclid": "GCLID_2"
   },
   "conversionValue": 3.25,
   "currency": "EUR",
   "timestamp": "2025-06-10T23:42:33-05:00",
   "transactionId": "DEF999911111",
   "eventSource": "EVENT_SOURCE_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",
       "timestamp": "2025-06-10T20:07:01Z",
       "transactionId": "ABC798654321",
       "eventSource": "EVENT_SOURCE_WEB",
       "userData": {
         "userIdentifiers": [
           {
             "address": {
               "givenName": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
               "lastName": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
               "regionCode": "US",
               "postalCode": "94045"
             }
           }
         ]
       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 3.25,
       "currency": "EUR",
       "timestamp": "2025-06-11T04:42:33Z",
       "transactionId": "DEF999911111",
       "eventSource": "EVENT_SOURCE_WEB",
       "userData": {
         "userIdentifiers": [
           {
             "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
           },
           {
             "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
           },
           {
             "address": {
               "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
               "lastName": "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. انقر على الزر واجهة برمجة التطبيقات على يسار الصفحة، ثم على الزر التجربة الآن في القسم الموسّع.
  4. ألصِق نص الطلب المنسوخ في مربّع نص الطلب.
  5. انقر على الزر تنفيذ وأكمِل طلبات التفويض وراجِع الردّ.

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

يعرض الطلب الناجح استجابة تتضمّن عنصرًا يحتوي على 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",
   "timestamp": "2025-06-10T20:07:01Z",
   "transactionId": "ABC798654321",
   "eventSource": "EVENT_SOURCE_WEB",
   "destinationReferences": [
      "conversion_action_1"
   ]
}

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

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