مرجع واجهة برمجة التطبيقات لعلامة Google

يتكوّن Google Tag API‏ (gtag.js) من دالة واحدة، gtag()، مع البنية التالية:

gtag(<command>, <command parameters>);

‫<command> هو أحد الأوامر التالية:
- config
- get
- set
- event
- consent
<command parameters> هي المَعلمات التي يمكنك تمريرها إلى gtag(). تختلف مَعلمات الأوامر حسب الأمر، لذا يُرجى الرجوع إلى مرجع الأوامر.

يمكنك استدعاء أوامر gtag() في أي مكان على صفحتك، طالما أنّ أوامرك تظهر أسفل مقتطف علامة تتبُّع من Google. لمعرفة كيفية إضافة المقتطف إلى صفحة، يُرجى الاطّلاع على دليل التثبيت.

نطاق المَعلمة

يمكنك تحديد نطاق قيم المَعلمات لتشمل أحداثًا فردية أو جميع الأحداث المُرسَلة إلى <TARGET_ID> معيّن أو على مستوى جميع الأحداث. ويتم ذلك باستخدام الأوامر event وconfig وset.

لا تؤدّي قيم المَعلمات التي تم ضبطها في نطاق معيّن إلى تعديل القيم التي تم ضبطها لنفس المَعلمة في نطاق مختلف. في المثال التالي، لا يعدّل الأمر config القيمة العامة لـ campaign_id التي تم تعيينها سابقًا باستخدام الأمر set. بعد تنفيذ كلا الأمرَين، ستظل القيمة العامة لـ campaign_id هي '1234'.

// Set global campaign ID
gtag('set', { 'campaign_id': '1234' });

// Set campaign ID for <TARGET_ID>
gtag('config','<TARGET_ID>', { 'campaign_id': 'ABCD' });

أولوية المَعلمات

إذا تمّ تعيين قيم مختلفة للمَعلمة نفسها في نطاقات مختلفة، سيتمّ استخدام قيمة واحدة فقط عند معالجة الأحداث. ستكون الأولوية لقيم المَعلمات التي يقتصر نطاقها على event على المَعلمات التي يقتصر نطاقها على config، كما أنّ الأولوية لمَعلمات config ستكون على المَعلمات التي يقتصر نطاقها على مستوى العالم باستخدام set.

// Set campaign information at the global scope
gtag('set', { 'campaign_name': 'Black Friday Sale' });

// Set currency for <TARGET_ID1> to 'USD'
gtag('config','<TARGET_ID1>', { 'currency': 'USD' });

// Process a conversion event with currency: 'GBP'
gtag('event','conversion', { 'currency': 'GBP', 'send_to': '<TARGET_ID1>' });

// Process a conversion event with currency: 'EUR'
gtag('event','conversion');

// Process a conversion event with currency: 'USD'
gtag('event','conversion', { 'send_to': '<TARGET_ID1>' });

`config`

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

gtag('config', '<TARGET_ID>', {<additional_config_info>});

النقاط الرئيسية حول <TARGET_ID>:

<TARGET_ID> في الأمر gtag('config', <TARGET_ID>, ...) هو رقم تعريف علامة يحدّد المكان الذي يجب أن ترسل إليه gtag.js بيانات الأحداث. قد تكون هذه الوجهة موقعًا، مثل موقع على "إحصاءات Google" أو حساب على "إعلانات Google" أو إعداد Floodlight أو علامة تتبُّع من Google تتضمّن وجهات متعدّدة.
معرّف العلامة، مثل GT-XXXXXX أو G-XXXXXX أو AW-YYYYYY، هو معرّف لـ "علامة تتبُّع من Google". تضيف هذا المعرّف إلى رمز موقعك الإلكتروني لتحميل علامة التتبّع من Google.
يمكن ضبط علامة تتبُّع واحدة من Google (يتم تحديدها من خلال رقم تعريف العلامة) لإرسال البيانات إلى وجهات متعددة. على الرغم من أنّ بعض أرقام تعريف العلامات قد تبدو مطابقة لأرقام تعريف الوجهات، مثل G-XXXXXX لموقع على "إحصاءات Google" أو AW-YYYYYY لحساب على "إعلانات Google"، يشير <TARGET_ID> في الأمر config إلى النسخة المحدّدة من علامة Google التي تم تحميلها على الصفحة.
يضبط الأمر gtag('config', ...) سلوك علامة تتبُّع من Google المرتبطة بمعرّف <TARGET_ID> المحدّد. في حين أنّ معرّف العلامة المضمّن في النص البرمجي src يحمّل عادةً علامة تتبُّع من Google، يمكنك استخدام أي معرّف علامة صالح مرتبط بحسابك في الأمر gtag('config').
يمكن أن تشتمل علامة تتبُّع واحدة من Google على أرقام تعريف علامات متعددة مرتبطة بها، وغالبًا ما يكون ذلك بسبب دمج العلامات. يمكن استخدام أيّ من هذه المعرّفات المرتبطة في مَعلمة src النص البرمجي لتحميل علامة تتبُّع من Google.
إذا كنت ترسِل البيانات إلى وجهات متعدّدة أو تستخدِم علامات متعدّدة، ما عليك سوى تضمين مقتطف واحد من علامة تتبُّع من Google مع رقم تعريف علامة واحد في النص البرمجي src. بعد ذلك، أدرِج أمر gtag('config') لكل معرّف علامة أو وجهة إضافية.

<additional_config_info> هي زوج واحد أو أكثر من أزواج القيَم والمَعلمات.

يضبط هذا المثال علامة لإرسال البيانات إلى حساب على "إعلانات Google":

gtag('config', 'TAG_ID');

حيث يمثّل "TAG_ID" رقم تعريف العلامة لعلامة تتبُّع من Google.

لتوضيح كيفية إرسال معلومات إعداد إضافية، إليك مثال يضبط علامة لإرسال البيانات إلى حساب على "إحصاءات Google" يتضمّن المَعلمة send_page_view التي تمرّر القيمة false، والمَعلمة groups التي تمرّر القيمة 'agency'.

gtag('config', 'TAG_ID', {
  'send_page_view': false,
  'groups': 'agency'
});

`get`

تتيح لك هذه الواجهة الحصول على قيم مختلفة من gtag.js، بما في ذلك القيم التي تم تحديدها باستخدام الأمر set.

gtag('get', '<target>', '<field_name>', callback)

الوسيطة	النوع	مثال	الوصف
<target>	`string`	G-XXXXXXXXXX	الهدف الذي يجب جلب القيم منه
<field_name>	FieldName	client_id	اسم الحقل الذي يجب جلبه
callback	`Function`	`(field) => console.log(field)`	دالة سيتم استدعاؤها باستخدام قيمة الحقل الذي تم طلبه، أو `undefined` إذا لم يتم ضبط الحقل

FieldName

يمكن أن يكون اسم الحقل هو اسم حقل مخصّص تم ضبطه باستخدام الأمر gtag('set')، أو إحدى القيم التالية:

اسم الحقل	الاستهدافات المتوافقة
client_id	إحصاءات Google‏ 4
session_id	إحصاءات Google‏ 4
session_number	إحصاءات Google‏ 4
gclid	إعلانات Google Floodlight

أمثلة

الحصول على قيمة في Promise

const gclidPromise = new Promise(resolve => {
  gtag('get', 'DC-XXXXXXXX', 'gclid', resolve)
});

gclidPromise.then((gclid) => {
  // Do something with gclid...
})

إرسال حدث إلى Measurement Protocol

gtag('get', 'G-XXXXXXXXXX', 'client_id', (clientID) => {
  sendOfflineEvent(clientID, "tutorial_begin")
});

function sendOfflineEvent(clientID, eventName, eventData) {
  // Send necessary data to your server...
}

الحصول على قيمة تحدّدها

gtag('set', {campaign_name: 'Spring_Sale'});

gtag('get', 'G-XXXXXXXXXX', 'campaign_name', (campaign_name) => {
  // Do something with currency value you set earlier.
})

`set`

يتيح لك الأمر set تحديد المَعلمات التي سيتم ربطها بكل حدث لاحق على الصفحة.

gtag('set', {<parameter-value-pair>, <parameter-value-pair>});

على سبيل المثال، يمكنك مشاركة مَعلمات الحملة ليتمكّن من الوصول إليها عدّة علامات على الصفحة نفسها.

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

gtag('set', 'campaign', {
  'id': 'abc',
  'source': 'google',
  'name': 'black_friday_promotion',
  'term': 'running+shoes',
});

`event`

استخدِم الأمر event لإرسال بيانات الحدث.

gtag('event', '<event_name>', {<event_params>});

يمكن أن يكون <event_name> أيًا مما يلي:

حدث مقترَح يمكن أن يتضمّن كل حدث مقترَح مَعلمات مقترَحة.
حدث مخصّص الحدث المخصّص هو اسم حدث عشوائي تحدّده، مع مَعلمات عشوائية. لمزيد من المعلومات، اطّلِع على مقالة إعداد الأحداث.

<event_params> هي زوج واحد أو أكثر من أزواج القيَم والمَعلمات. يتم فصل كل زوج بفاصلة.

يؤدي الأمر event التالي إلى تشغيل الحدث المقترَح screen_view مع مَعلمتَين: app_name وscreen_name.

gtag('event', 'screen_view', {
  'app_name': 'myAppName',
  'screen_name': 'Home'
});

`consent`

استخدِم الأمر consent لضبط الموافقة.

gtag('consent', {<consent_arg>}, {<consent_params>});

لمزيد من المعلومات حول السلوك الذي تحدّده هذه المَعلمات، يُرجى الاطّلاع على مقالة الموافقة في مركز المساعدة.

‫<consent_arg> هي إحدى القيمتين 'default' أو 'update'. يتم استخدام 'default' لضبط مَعلمات الموافقة التلقائية التي يجب استخدامها، ويتم استخدام 'update' لتعديل هذه المَعلمات بعد أن يوضّح المستخدم موافقته.

يمكن استخدام <consent_params> التالية:

اسم الحقل	القيم المسموح بها	الوصف
`ad_storage`	`'granted'` \| `'denied'`	لتفعيل عملية تخزين المعلومات، مثل ملفات تعريف الارتباط (المواقع الإلكترونية) أو معرّفات الأجهزة (التطبيقات)، المرتبطة بالإعلانات
`ad_user_data`	`'granted'` \| `'denied'`	لإعداد الموافقة على إرسال بيانات المستخدمين إلى Google لأغراض إعلانية
`ad_personalization`	`'granted'` \| `'denied'`	من أجل ضبط الموافقة على الإعلانات المخصَّصة.
`analytics_storage`	`'granted'` \| `'denied'`	لتفعيل عملية تخزين المعلومات، مثل ملفات تعريف الارتباط (المواقع الإلكترونية) أو معرّفات التطبيقات (التطبيقات)، المرتبطة بالإحصاءات، مثل مدة الزيارة
`wait_for_update`	أي عدد صحيح موجب	تضبط هذه السمة وقتًا بالملّي ثانية للانتظار إلى حين تلقّي طلب تعديل الموافقة.