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

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

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

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

لا تتوفّر هذه الميزة إلا للحسابات المدرَجة في قائمة السماح. يُرجى ملء النموذج إذا كنت مهتمًا بإضافة حسابك على "إعلانات Google" أو موقعك على "إحصاءات Google".

ملاحظة: لن يتم نقل البيانات من مصدر البيانات الإضافي الذي تربطه إلى عروض الأسعار المستندة إلى الإحالات الناجحة خلال فترة تجريبية مدتها 14 يومًا. لا ينطبق ذلك على مصدر البيانات الحالي لـ "علامات التتبُّع من Google".
إرسال بيانات الأحداث إلى الإحالات الناجحة غير الإلكترونية أو الإحالات الناجحة المحسّنة للعملاء المحتملين في "إعلانات Google"

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

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

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

إعداد الوجهات

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

    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "PRODUCT_DESTINATION_ID"
    }

في ما يلي حقول Destination. يمكنك الاطّلاع على إعداد الوجهات لمزيد من التفاصيل والأمثلة حول وجهات السيناريوهات المختلفة.

operatingAccount

الحساب الذي يتلقّى الأحداث

بالنسبة إلى الأحداث المُرسَلة كمصدر بيانات إضافي، يمكن أن يكون الحساب التشغيلي إمّا حسابًا على "إعلانات Google" أو موقعًا على "إحصاءات Google".

إذا كانت قيمة accountType هي GOOGLE_ANALYTICS_PROPERTY، يجب أن تكون بيانات اعتماد الطلب خاصة بمستخدم "إحصاءات Google" لديه دور المحرّر أو المشرف للموقع.

بالنسبة إلى الإحالات الناجحة غير الإلكترونية و"الإحالات الناجحة المحسّنة للعملاء المحتملين"، يجب أن يكون الحساب التشغيلي حسابًا على "إعلانات Google".

loginAccount: الحساب الذي يكون فيه حساب Google الخاص ببيانات الاعتماد مستخدمًا

productDestinationId

معرّف العنصر في operatingAccount الذي يتلقّى الأحداث.

بالنسبة إلى الأحداث المُرسَلة كمصدر بيانات إضافي، يجب أن يكون productDestinationId أحد ما يلي:

معرّف إحالة ناجحة في "إعلانات Google" تم ضبط type على WEBPAGE. في واجهة مستخدم "إعلانات Google"، يكون مصدر الإحالة الناجحة لإجراء الإحالة الناجحة WEBPAGE هو الموقع الإلكتروني.
رقم تعريف القياس الخاص بمصدر بيانات الموقع الإلكتروني في "إحصاءات Google" لا يمكنك إرسال الأحداث كمصدر بيانات إضافي إلى مصدر بيانات تطبيق iOS أو تطبيق Android على "إحصاءات Google".

بالنسبة إلى الإحالات الناجحة غير الإلكترونية أو الإحالات الناجحة المحسّنة للعملاء المحتملين، يجب أن يكون productDestinationId هو معرّف إجراء إحالة ناجحة في "إعلانات Google" مع ضبط type على UPLOAD_CLICKS. في واجهة مستخدم "إعلانات Google"، يكون مصدر الإحالة الناجحة لإجراء إحالة ناجحة من النوع UPLOAD_CLICKS هو الموقع الإلكتروني (الاستيراد من النقرات).

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

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

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

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

معلومات عن المستخدِم يتم تقييمها في وقت الحدث، مثل قيمة العميل أو ما إذا كان عميلاً جديدًا أو متكرّرًا أو أعاد التفاعل.
بيانات سلة التسوّق
مَعلمات أحداث أو خصائص مستخدمين إضافية لوجهة، مثل client_id أو user_id في "إحصاءات Google".

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

الحدث 1

الحدث رقم 1
`conversion_time`	`2025-06-10 15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`30.03`
`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`
`client_id`	`1234567890.1761581763`
`user_id`	`user_ABC12345`
`ad_unit_name`	`Banner_01`
`event_name`	`purchase`
السلع في سلة التسوّق
`item_id`	`SKU_12345`
`item_name`	`Stan and Friends Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`2.22`
`item_index`	`0`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`10.01`
`item_quantity`	`3`

الحدث 2

الحدث رقم 2
`conversion_time`	`June 10, 2025 11:42:33PM America/New_York`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`42.02`
`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`
`client_id`	`9876543210.1761582117`
`user_id`	`user_DEF9876`
`ad_unit_name`	`Banner_02`
`event_name`	`purchase`
السلع في سلة التسوّق
`item_id`	`SKU_12346`
`item_name`	`Google Grey Women's Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`3.33`
`item_index`	`1`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`21.01`
`item_quantity`	`2`

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

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

الحدث 1

الحدث رقم 1
`conversion_time`	`2025-06-10T15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`30.03`
`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`
`client_id`	`1234567890.1761581763`
`user_id`	`user_ABC12345`
`ad_unit_name`	`Banner_01`
`event_name`	`purchase`
السلع في سلة التسوّق
`item_id`	`SKU_12345`
`item_name`	`Stan and Friends Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`2.22`
`item_index`	`0`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`10.01`
`item_quantity`	`3`

الحدث 2

الحدث رقم 2
`conversion_time`	`2025-06-10T23:42:33-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`42.02`
`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`
`client_id`	`9876543210.1761582117`
`user_id`	`user_DEF9876`
`ad_unit_name`	`Banner_02`
`event_name`	`purchase`
السلع في سلة التسوّق
`item_id`	`SKU_12346`
`item_name`	`Google Grey Women's Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`3.33`
`item_index`	`1`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`21.01`
`item_quantity`	`2`

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

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

الحدث 1

الحدث رقم 1
`conversion_time`	`2025-06-10T15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`30.03`
`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`
`client_id`	`1234567890.1761581763`
`user_id`	`user_ABC12345`
`ad_unit_name`	`Banner_01`
`event_name`	`purchase`
السلع في سلة التسوّق
`item_id`	`SKU_12345`
`item_name`	`Stan and Friends Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`2.22`
`item_index`	`0`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`10.01`
`item_quantity`	`3`

الحدث 2

الحدث رقم 2
`conversion_time`	`2025-06-10T23:42:33-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`42.02`
`currency`	`EUR`
`gclid`	`GCLID_2`
`emails`	`3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250` `223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4`
`given_name`	`2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450`
`family_name`	`6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F`
`region_code`	`PT`
`postal_code`	`1229-076`
`customer_type`	`RETURNING`
`client_id`	`9876543210.1761582117`
`user_id`	`user_DEF9876`
`ad_unit_name`	`Banner_02`
`event_name`	`purchase`
السلع في سلة التسوّق
`item_id`	`SKU_12346`
`item_name`	`Google Grey Women's Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`3.33`
`item_index`	`1`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`21.01`
`item_quantity`	`2`

تحويل البيانات إلى عناصر `Event`

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

اضبط eventTimestamp على الوقت الذي وقع فيه الحدث.

يجب أن تتضمّن أحداث "إحصاءات Google" eventTimestamp خلال آخر 72 ساعة.

اضبط الحقول المطلوبة لحالة الاستخدام.

حالة الاستخدام	المعرّفات	`transactionId`	`eventSource`
الإحالات الناجحة غير الإلكترونية أو الإحالات الناجحة المحسّنة للعملاء المحتملين	مَعلمة مطلوبة. اضبط أحد الخيارات التالية على الأقل: `adIdentifiers` مع ضبط قيمة واحدة على الأقل من `gclid` أو `gbraid` أو `wbraid` سمات الجلسة `userData`	اختياري	مَعلمة مطلوبة. يجب ضبطها على إحدى قيم enum الخاصة بـ `EventSource`.
الأحداث التي يتم إرسالها كمصدر بيانات إضافي إلى وجهة في "إعلانات Google"	مَعلمة مطلوبة. اضبط أحد الخيارات التالية على الأقل: ‫`adIdentifiers` مع ضبط قيمة واحدة على الأقل من `gclid` أو `gbraid` أو `wbraid` `userData`	مطلوب	اختياريّ. في حال ضبطها، يجب أن تكون القيمة `WEB`.
الأحداث التي يتم إرسالها كمصدر بيانات إضافي إلى وجهة في "إحصاءات Google"	مَعلمة مطلوبة. اضبط أحد الخيارات التالية على الأقل: `clientId` `adIdentifiers` مع ضبط `gclid` `userData`	مطلوب	اختياريّ. في حال ضبطها، يجب أن تكون القيمة `WEB`.

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

ملاحظة: لا تتيح "إعلانات Google" و"إحصاءات Google" مطابقة عناوين IP للمستخدِمين النهائيين في المنطقة الاقتصادية الأوروبية أو المملكة المتحدة أو سويسرا. أضِف منطقًا لاستبعاد مشاركة عناوين IP بشكل مشروط مع المستخدمين من هذه المناطق، وتأكَّد من تزويد المستخدمين بمعلومات واضحة وشاملة حول البيانات التي يتم جمعها في مواقعك الإلكترونية وتطبيقاتك ومواقعك الأخرى، والحصول على الموافقة حيثما يقتضي القانون أو أي سياسات سارية من Google. اطّلِع على صفحة لمحة عن عمليات استيراد الإحالات الناجحة غير الإلكترونية لمزيد من التفاصيل.

إضافة سمات الجلسة

إذا كنت ترسِل إحالات ناجحة غير إلكترونية أو إحالات ناجحة محسّنة للعملاء المحتملين، أضِف سمات الجلسة عندما لا تتوفّر معرّفات إعلانات أخرى، مثل معرّف النقرة من Google أو WBRAID. يمكنك أيضًا تضمين سمات الجلسة بالإضافة إلى معرّفات الإعلانات الأخرى.

تقدّم سمات الجلسة المزيد من السياق والإشارات حول تفاعل المستخدِم مع موقعك الإلكتروني، ما يمكن أن يُحسِّن من دقة قياس الإحالات الناجحة وإعداد التقارير وتقديم عروض الأسعار.

في Data Manager API، يمكنك استخدام طريقتَين لإرسال سمات الجلسة:

يُنصح بما يلي: اضبط الحقل sessionAttributes الخاص بـ adIdentifiers على سلسلة سمات الجلسة المشفّرة بترميز base64. اتّبِع التعليمات الواردة في مقالة كيفية تسجيل المَعلمة session_attributes لتعديل صفحات إرسال النموذج من أجل تسجيل السلسلة المرمّزة.
إذا لم تتمكّن من استخدام JavaScript، سجِّل حقول سمات الجلسة الفردية وأضِف كل حقل إلى قائمة experimentalFields كـ ExperimentalField منفصل:
- gad_campaignid
- session_start_time_usec
- gad_source
- landing_page_url
- landing_page_referrer
إذا كانت لديك قيمة لسمة الجلسة landing_page_user_agent، أرسِلها في الحقل userAgent من adIdentifiers.landingPageDeviceInfo.

في ما يلي أفضل الممارسات عند إرسال أزواج مفتاح/قيمة فردية:
- إرسال gad_campaignid وsession_start_time_usec باستمرار هذه الحقول ضرورية لتحديد المصدر بدقة.
- لا تقدّم قيمة landing_page_url غير دقيقة أو جزئية، مثل سلسلة عنصر نائب أو مسار تطبيق داخلي أو عنوان URL غير مكتمل. احذف landing_page_url إذا لم يكن لديك عنوان URL دقيق وكامل.
في ما يلي جزء من حدث نموذجي يتضمّن إدخالات في experimentalFields وgad_campaignid وsession_start_time_usec، وبرنامج وكيل المستخدم في الحقل landingPageDeviceInfo:
```
{
  ...,
  "experimentalFields": [
    {
      "field": "gad_campaignid",
      "value": "21288051566"
    },
    {
      "field": "session_start_time_usec",
      "value": "1767711548052000"
    }
  ],
  "adIdentifiers": {
    "landingPageDeviceInfo": {
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36"
    }
  }
}
```

إضافة معلومات "إحصاءات Google"

إذا كانت وجهات حدث مُرسَل كمصدر بيانات إضافي تتضمّن موقعًا على "إحصاءات Google"، املأ الحقول التالية كما هو موضّح:

eventName

مَعلمة مطلوبة. اسم الحدث في "إحصاءات Google".

transactionId

مطلوب المعرّف الفريد للحدث.

معرّف واحد على الأقل

يجب ضبط حقل واحد على الأقل من الحقول التالية:

clientId: معرّف فريد لمثيل مستخدم لبرنامج عميل على الويب. اطّلِع على إرسال حدث إلى Measurement Protocol.
adIdentifiers.gclid: هو معرّف نقرة من Google.
userData: معرّفات المستخدم، مثل عناوين البريد الإلكتروني أو أرقام الهواتف أو معلومات العنوان

destinationReferences

مطلوبة إذا كانت قائمة destinations على مستوى الطلب تتضمّن أكثر من Destination واحدة من "إحصاءات Google". أضِف إدخالاً إلى destinationReferences لتحديد وجهة "إحصاءات Google" التي يجب أن تتلقّى الحدث. اطّلِع على مقالة إرسال الأحداث إلى وجهات متعدّدة لمزيد من المعلومات عن مراجع الوجهات.

إذا لم يتم ضبط destinationReferences أو كان يتضمّن عدّة إدخالات تشير إلى وجهات "إحصاءات Google"، سترفض واجهة برمجة التطبيقات Data Manager الحدث مع ظهور الخطأ MULTIPLE_DESTINATIONS_FOR_GOOGLE_ANALYTICS_EVENT.

userId

اختياريّ. تمثّل هذه السمة معرّف المستخدم.

additionalEventParameters

اختيارية، ولكن ننصح بها املأ هذه القائمة بأي مَعلمات أحداث في "إحصاءات Google" لا يتم تسجيلها في حقول Event الأخرى. يمكن أن تتضمّن المَعلمات مَعلمات إضافية يُنصح بها من حدث purchase، أو مَعلمات أخرى تريد تسجيلها. استخدِم اسم مَعلمة "إحصاءات Google" الخاص بـ parameterName في EventParameter.

على سبيل المثال، إذا كانت لديك الضرائب المرتبطة بمعاملة، أضِف إدخالاً إلى additionalEventParameters مع ضبط parameterName على tax، وضبط value على تكلفة الضريبة.

لا ننصح بإضافة إدخالات لمعلمات أحداث transactionId أو currency أو value في "إحصاءات Google". بدلاً من ذلك، املأ الحقول transactionId وcurrency وconversionValue في Event، والتي لها الأولوية على أي إدخالات في additionalEventParameters.

إضافة بيانات سلة التسوّق لأحداث الشراء

املأ الحقل cartData في Event بمعلومات حول السلع التي تم شراؤها. لكل سلعة تم شراؤها، أضِف عنصر Item إلى قائمة items ضمن CartData، واملأ الحقول التالية كما هو موضّح:

itemId

مطلوب: تمثّل هذه السمة معرّفًا فريدًا للسلعة.

unitPrice

مَعلمة مطلوبة. سعر الوحدة غير شامل للضرائب أو تكاليف الشحن أو الخصومات على مستوى الحدث (على مستوى المعاملة).

إذا كان المنتج يتضمّن خصمًا على مستوى المنتج، استخدِم سعر الوحدة المخفّض. على سبيل المثال، إذا كان سعر الوحدة 27.67 والخصم على الوحدة 6.66، اضبط unitPrice على 21.01.

quantity

مَعلمة مطلوبة. كمية الوحدات التي تم شراؤها من هذه السلعة المحدّدة.

additionalItemParameters

املأ هذه القائمة بأي مَعلمات على مستوى المنتج أو الخدمة لم يتم تسجيلها في حقول Item الأخرى. استخدِم اسم مَعلمة عنصر "إحصاءات Google" في parameterName الخاص بـ ItemParameter.

على سبيل المثال، إذا كانت لديك العلامة التجارية والفئة الخاصة بمنتج، أضِف إدخالاً إلى additionalItemParameters الخاص بالمنتج مع ضبط parameterName على item_brand وضبط value على اسم العلامة التجارية، وإدخالاً آخر مع ضبط parameterName على item_category وضبط value على فئة المنتج.

لا ننصح بإضافة إدخالات لمعلمات عناصر quantity أو price أو item_id في "إحصاءات Google". بدلاً من ذلك، املأ الحقول itemId وunitPrice وquantity في Item، والتي لها الأولوية على أي إدخالات في additionalItemParameters.

في ما يلي نموذج Event للبيانات المنسّقة والمجزّأة والمشفّرة من الحدث الثاني، مع بيانات إضافية لخدمة "إحصاءات Google":

{
  "adIdentifiers": {
     "gclid": "GCLID_2"
  },
  "conversionValue": 42.02,
  "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"
  },
  "eventName": "purchase",
  "clientId": "9876543210.1761582117",
  "userId": "user_DEF9876",
  "additionalEventParameters": [
    {
      "parameterName": "ad_unit_name",
      "value": "Banner_02"
    }
  ],
  "cartData": {
    "transactionDiscount": 6.66,
    "items": [
      {
        "itemId": "SKU_12346",
        "quantity": 2,
        "unitPrice": 21.01,
        "additionalItemParameters": [
          {
            "parameterName": "item_name",
            "value": "Google Grey Women's Tee"
          },
          {
            "parameterName": "affiliation",
            "value": "Google Merchandise Store"
          },
          {
            "parameterName": "coupon",
            "value": "SUMMER_FUN"
          },
          {
            "parameterName": "discount",
            "value": "3.33"
          },
          {
            "parameterName": "index",
            "value": "1"
          },
          {
            "parameterName": "item_brand",
            "value": "Google"
          },
          {
            "parameterName": "item_category",
            "value": "Apparel"
          },
          {
            "parameterName": "item_category2",
            "value": "Adult"
          },
          {
            "parameterName": "item_category3",
            "value": "Shirts"
          },
          {
            "parameterName": "item_category4",
            "value": "Crew"
          },
          {
            "parameterName": "item_category5",
            "value": "Short sleeve"
          },
          {
            "parameterName": "item_list_id",
            "value": "related_products"
          },
          {
            "parameterName": "item_list_name",
            "value": "Related Products"
          }
        ]
      }
    ]
  }
}

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

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

{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  ],
  "encoding": "HEX",
  "events": [
     {
       "adIdentifiers": {
         "gclid": "GCLID_1"
       },
       "conversionValue": 30.03,
       "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"
       },
       "eventName": "purchase",
       "clientId": "1234567890.1761581763",
       "userId": "user_ABC12345",
       "additionalEventParameters": [
         {
           "parameterName": "ad_unit_name",
           "value": "Banner_01"
         }
       ],
       "cartData": {
         "transactionDiscount": 6.66,
         "items": [
           {
             "itemId": "SKU_12345",
             "quantity": 3,
             "unitPrice": 10.01,
             "additionalItemParameters": [
               {
                 "parameterName": "item_name",
                 "value": "Stan and Friends Tee"
               },
               {
                 "parameterName": "affiliation",
                 "value": "Google Merchandise Store"
               },
               {
                 "parameterName": "coupon",
                 "value": "SUMMER_FUN"
               },
               {
                 "parameterName": "discount",
                 "value": "2.22"
               },
               {
                 "parameterName": "index",
                 "value": "0"
               },
               {
                 "parameterName": "item_brand",
                 "value": "Google"
               },
               {
                 "parameterName": "item_category",
                 "value": "Apparel"
               },
               {
                 "parameterName": "item_category2",
                 "value": "Adult"
               },
               {
                 "parameterName": "item_category3",
                 "value": "Shirts"
               },
               {
                 "parameterName": "item_category4",
                 "value": "Crew"
               },
               {
                 "parameterName": "item_category5",
                 "value": "Short sleeve"
               },
               {
                 "parameterName": "item_list_id",
                 "value": "related_products"
               },
               {
                 "parameterName": "item_list_name",
                 "value": "Related Products"
               }
             ]
           }
         ]

       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 42.02,
       "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"
       },
       "eventName": "purchase",
       "clientId": "9876543210.1761582117",
       "userId": "user_DEF9876",
       "additionalEventParameters": [
         {
           "parameterName": "ad_unit_name",
           "value": "Banner_02"
         }
       ],
       "cartData": {
         "transactionDiscount": 6.66,
         "items": [
           {
             "itemId": "SKU_12346",
             "quantity": 2,
             "unitPrice": 21.01,
             "additionalItemParameters": [
               {
                 "parameterName": "item_name",
                 "value": "Google Grey Women's Tee"
               },
               {
                 "parameterName": "affiliation",
                 "value": "Google Merchandise Store"
               },
               {
                 "parameterName": "coupon",
                 "value": "SUMMER_FUN"
               },
               {
                 "parameterName": "discount",
                 "value": "3.33"
               },
               {
                 "parameterName": "index",
                 "value": "1"
               },
               {
                 "parameterName": "item_brand",
                 "value": "Google"
               },
               {
                 "parameterName": "item_category",
                 "value": "Apparel"
               },
               {
                 "parameterName": "item_category2",
                 "value": "Adult"
               },
               {
                 "parameterName": "item_category3",
                 "value": "Shirts"
               },
               {
                 "parameterName": "item_category4",
                 "value": "Crew"
               },
               {
                 "parameterName": "item_category5",
                 "value": "Short sleeve"
               },
               {
                 "parameterName": "item_list_id",
                 "value": "related_products"
               },
               {
                 "parameterName": "item_list_name",
                 "value": "Related Products"
               }
             ]
           }
         ]
       }
     }
  ],
  "validateOnly": true
}

عدِّل العناصر النائبة في النص الأساسي، مثل OPERATING_ACCOUNT_ID و PRODUCT_DESTINATION_ID، باستخدام قيم حسابك ووجهتك.
اضبط قيمة validateOnly على true للتحقّق من صحة الطلب بدون تطبيق التغييرات. عندما تكون مستعدًا لتطبيق التغييرات، اضبط validateOnly على false.
يُرجى العِلم أنّ هذا المثال لا يستخدم التشفير.

إرسال الطلب

انسخ نص الطلب باستخدام زر النسخ في أعلى يسار النموذج.
انقر على الزر API في شريط الأدوات.
ألصِق نص الطلب المنسوخ في مربّع نص الطلب.
انقر على الزر تنفيذ (Execute)، وأكمِل طلبات التفويض، وراجِع الردّ.

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

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

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

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

ردود حالات الفشل

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

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

{
  "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"
          }
        ]
      }
    ]
  }
}

يؤدي استخدام emailAddress غير مجزأ وذو ترميز سداسي فقط إلى ظهور الاستجابة التالية:

{
  "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": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "PRODUCT_DESTINATION_ID",
      "reference": "destination_a"
    },
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_2_TYPE",
        "accountId": "OPERATING_ACCOUNT_2_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_2_TYPE",
        "accountId": "LOGIN_ACCOUNT_2_ID"
      },

      "productDestinationId": "777111122",
      "reference": "destination_b"
    }
  ]

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

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

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

إذا كان الحدث يتضمّن وجهات متعدّدة، ترسل واجهة برمجة التطبيقات Data Manager الحقول ذات الصلة إلى كل وجهة. على سبيل المثال، إذا كان الحدث يتضمّن وجهة في "إعلانات Google" ووجهة في "إحصاءات Google"، يتضمّن واجهة برمجة التطبيقات حقول "إحصاءات Google"، مثل clientId أو eventName، عند إرسال الحدث إلى وجهة "إحصاءات Google"، ويتضمّن حقول "إعلانات Google"، مثل customVariables، عند إرسال الحدث إلى وجهة "إعلانات Google".

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

ضبط المصادقة وإعداد بيئتك باستخدام مكتبة برامج للعملاء
تعرَّف على متطلبات التنسيق والتجزئة والترميز لكل نوع من أنواع البيانات.
كيفية تشفير بيانات المستخدمين
كيفية استرداد بيانات التشخيص لطلباتك
مزيد من المعلومات حول أفضل الممارسات
مزيد من المعلومات عن الحدود والحصص

نظرة عامة على الأحداث

إرسال الأحداث تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

إعداد الوجهات

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

الحدث 1

الحدث 2

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

الحدث 1

الحدث 2

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

الحدث 1

الحدث 2

تحويل البيانات إلى عناصر Event

إضافة سمات الجلسة

إضافة معلومات "إحصاءات Google"

إضافة بيانات سلة التسوّق لأحداث الشراء

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

إرسال الطلب

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

ردود حالات الفشل

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

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

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

تحويل البيانات إلى عناصر `Event`