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

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

استخدِم Data Manager API في أيّ من السيناريوهات التالية:

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

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

  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. بالنسبة إلى الأحداث غير الإلكترونية، يجب أن يكون إجراء الإحالة الناجحة إجراء إحالة ناجحة في "إعلانات Google" مع ضبط type على UPLOAD_CLICKS.

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

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

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

قد يتضمّن كل حدث معرّفات إعلانات، مثل 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
customer_type NEW
customer_value_bucket HIGH

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

الحدث رقم 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
customer_type RETURNING

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

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

الحدث رقم 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
customer_type NEW
customer_value_bucket HIGH

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

الحدث رقم 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
customer_type RETURNING

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

بالإضافة إلى ذلك، يجب تجزئة عناوين البريد الإلكتروني والأسماء المعرِّفة وأسماء العائلة المنسَّقة باستخدام خوارزمية 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
customer_type NEW
customer_value_bucket HIGH

في ما يلي بيانات الحدث الثاني بعد التنسيق والتجزئة والترميز باستخدام ترميز 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
customer_type RETURNING

تحويل البيانات إلى 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"
            }
         }
      ],
      "userProperties": {
        "customerType": "RETURNING"
      }
   }
}

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

اجمع بين 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"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "NEW",
         "customerValueBucket": "HIGH"
       }
     },
     {
       "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"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "RETURNING"
       }
     }
  ],
  "validateOnly": true
}
  1. عدِّل العناصر النائبة في نص الرسالة، مثل OPERATING_ACCOUNT_ID وCONVERSION_ACTION_1_ID، باستخدام قيم حسابك ووجهتك.
  2. اضبط قيمة validateOnly على true للتحقّق من صحة الطلب بدون تطبيق التغييرات. عندما تكون مستعدًا لتطبيق التغييرات، اضبط validateOnly على false.
  3. يُرجى العِلم أنّ هذا المثال لا يستخدم التشفير.

إرسال الطلب

  1. انسخ نص الطلب باستخدام زر النسخ في أعلى يسار النموذج.
  2. انقر على الزر API في شريط الأدوات.
  3. ألصِق نص الطلب المنسوخ في مربّع نص الطلب.
  4. انقر على الزر تنفيذ (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 الحدث إلى جميع الوجهات في الطلب.

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