تتألف واجهة برمجة التطبيقات لعلامة Google (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)
الوسيطة | Type | مثال | الوصف |
---|---|---|---|
<target> | string |
G-XXXXXXXXXX |
الهدف المطلوب جلب القيم منه. |
<field_name> | FieldName | client_id | اسم الحقل المطلوب الحصول عليه. |
رد الاتصال | Function |
(field) => console.log(field) |
يشير ذلك المصطلح إلى دالة سيتم استدعاؤها مع الحقل المطلوب، أو
|
FieldName
يمكن أن يكون اسم الحقل هو اسم حقل مخصّص تعيّنه باستخدام الأمر gtag('set')
، أو إحدى القيم التالية:
اسم الحقل | الأهداف المتوافقة |
---|---|
client_id |
|
session_id |
|
gclid |
|
أمثلة
تحقيق قيمة وعودة
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>
هو إما:
- حدث مقترَح ويمكن أن يتضمّن كل حدث مقترَح المَعلمات المقترَحة.
- حدث مخصّص. الحدث المخصّص هو اسم حدث عشوائي تُنشئه باستخدام مَعلمات عشوائية (أي مخصّصة). على سبيل المثال، اطّلِع على كيفية استخدام الأحداث المخصّصة في "إحصاءات Google".
يتألّف <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 |
أي عدد صحيح موجب | تحدِّد هذه السياسة وقتًا بالملي ثانية لانتظار طلب تعديل الموافقة. |