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

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

gtag(<command>, <command parameters>);
  • ‫<command> هو أحد الأوامر التالية:
  • <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> هو معرّف يحدّد بشكل فريد الهدف من الزيارات، مثل موقع على "إحصاءات 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)
الوسيطة النوع مثال الوصف
<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 لضبط الموافقة.

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 أي عدد صحيح موجب تضبط هذه السمة وقتًا بالملّي ثانية للانتظار إلى حين تلقّي طلب تعديل الموافقة.