تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

استخدِم 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` أو `sessionAttributes` `userData`	اختياري	مَعلمة مطلوبة. يجب ضبطها على إحدى قيم التعداد `EventSource`.
الأحداث التي يتم إرسالها كمصدر بيانات إضافي إلى وجهة في "إعلانات Google"	مَعلمة مطلوبة. اضبط أحد الخيارات التالية على الأقل: ‫`adIdentifiers` مع ضبط قيمة واحدة على الأقل من `gclid` أو `gbraid` أو `wbraid` `userData`	مطلوب	اختياريّ. في حال ضبطها، يجب أن تكون القيمة `WEB`.
الأحداث المُرسَلة كمصدر بيانات إضافي إلى وجهة في "إحصاءات Google"	مَعلمة مطلوبة. اضبط أحد الخيارات التالية على الأقل: `clientId` `adIdentifiers` مع ضبط `gclid` `userData`	مطلوب	اختياريّ. في حال ضبطها، يجب أن تكون القيمة `WEB`.

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

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

إضافة معلومات "إحصاءات 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

اختياريّ. User-ID الخاص بالمستخدم.

additionalEventParameters

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

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

لا ننصح بإضافة إدخالات لمعلمات أحداث "إحصاءات Google"‏ transactionId أو currency أو value. بدلاً من ذلك، املأ الحقول 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 على فئة المنتج.

لا ننصح بإضافة إدخالات لمعلمات عناصر "إحصاءات Google"‏ quantity أو price أو item_id. بدلاً من ذلك، املأ الحقول 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 في شريط الأدوات.
ألصِق نص الطلب المنسوخ في مربّع نص الطلب.
انقر على الزر تنفيذ، وأكمِل طلبات التفويض، وراجِع الردّ.

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

يعرض الطلب الناجح استجابة تتضمّن عنصرًا يحتوي على 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`