تمت ترجمة هذه الصفحة بواسطة 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_ADS أو GOOGLE_ANALYTICS_PROPERTY، واضبط قيمة accountId على رقم تعريف عميل "إعلانات Google" أو رقم تعريف الموقع على "إحصاءات Google". إذا كانت قيمة accountType هي GOOGLE_ANALYTICS_PROPERTY، يجب أن تكون بيانات اعتماد الطلب خاصة بمستخدم في "إحصاءات Google" لديه دور المحرِّر أو المشرف للموقع.

بالنسبة إلى الإحالات الناجحة غير الإلكترونية و"الإحالات الناجحة المحسّنة للعملاء المحتملين"، يجب أن يكون الحساب التشغيلي حسابًا على "إعلانات Google"، لذا اضبط قيمة accountType على GOOGLE_ADS واضبط قيمة accountId على رقم تعريف العميل في "إعلانات Google".

loginAccount

الحساب الذي يمكن للمستخدم الذي يملك بيانات الاعتماد الوصول إليه.

إذا كانت بيانات اعتماد OAuth خاصة بمستخدم لديه إذن الوصول إلى حساب إداري على "إعلانات Google" يتضمّن operatingAccount كأحد حساباته الفرعية، يجب توفير loginAccount. اضبط قيمة accountId الخاصة بـ loginAccount على معرّف الحساب الإداري، واضبط قيمة accountType الخاصة بـ loginAccount على GOOGLE_ADS.

إذا كانت بيانات اعتماد OAuth خاصة بمستخدم لديه إذن وصول مباشر إلى operatingAccount، لن تحتاج إلى ضبط loginAccount وسيتم ضبطها تلقائيًا على operatingAccount. ومع ذلك، ننصحك بضبط loginAccount على accountId وaccountType وoperatingAccount نفسها. يساعد ذلك في تجنُّب المشاكل في حال تغيّر مجموعة الحسابات التي يمكن للمستخدم الوصول إليها.

productDestinationId

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

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

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