مرجع واجهة برمجة التطبيقات لعلامة 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> هو رقم تعريف علامة يحدّد المكان الذي يجب أن ترسل إليه gtag.js بيانات الأحداث. قد تكون هذه الوجهة موقعًا، مثل موقع على "إحصاءات Google" أو حساب على "إعلانات Google"، أو قد تكون علامة تتبُّع من Google تتضمّن وجهات متعدّدة. <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)

FieldName

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

أمثلة

الحصول على قيمة في 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> التالية: