تتألف واجهة برمجة تطبيقات علامة Google (gtag.js) من دالة واحدة، gtag()
، مع البنية التالية:
gtag(<command>, <command parameters>);
<command>
هو أحد الأوامر التالية:<command parameters>
هي المَعلمات التي يمكنك تمريرها إلىgtag()
. تختلف معلمات الأوامر وفقًا للأمر. يمكنك الرجوع إلى مرجع الأمر أدناه.
يمكنك استدعاء أوامر gtag()
في أي مكان على صفحتك، طالما أنّ أوامرك تظهر أسفل مقتطف علامة Google. لمعرفة كيفية إضافة المقتطف إلى إحدى الصفحات، اطّلِع على دليل التثبيت.
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 |
الهدف جلب قيم |
<حقل_اسم> | اسم الحقل | client_id | اسم الحقل الذي سيتم الحصول عليه. |
معاودة الاتصال | Function |
(field) => console.log(field) |
دالة سيتم استدعاءها باستخدام الحقل المطلوب، أو
|
اسم الحقل
يمكن أن يكون اسم الحقل هو اسم حقل مخصّص تضبطه باستخدام الأمر 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', {currency: 'USD'});
gtag('get', 'G-XXXXXXXXXX', 'currency', (currency) => {
// Do something with currency value you set earlier.
})
set
وتسمح لك هذه السياسة بضبط القيم التي تستمر في جميع مكالمات gtag()
اللاحقة على الصفحة.
gtag('set', {<parameter-value-pair>, <parameter-value-pair>});
<parameter-value-pair>
هو اسم مفتاح والقيمة التي تستمر في جميع مكالمات gtag()
. على سبيل المثال، يحدّد الرمز التالي قيمة country
إلى
'US'
وقيمة currency
إلى 'USD'
لجميع الأحداث اللاحقة على
الصفحة:
gtag('set', {
'country': 'US',
'currency': 'USD'
});
يختلف استخدام الأمر set
عن تمرير القيم مباشرةً إلى الأمر
event
. عند تمرير القيم مباشرةً إلى أمر event
، تنطبق هذه القيم فقط على الحدث الذي يتم تنشيطه. أما مع العلامة set
، تبقى القيم في الصفحة الحالية ويتم تمريرها مع جميع الأحداث اللاحقة. للتوضيح، عليك توضيح
المثالين التاليين:
gtag('event', 'login', {'method': 'Google'});
gtag('event', 'share');
و
gtag('set', {'method': 'Google'});
gtag('event', 'login');
gtag('event', 'share');
في المثال الأول، سيتم تمرير الحدث login
بقيمة method
'Google'
وسيتم تمرير حدث share
بدون أي مَعلمات. في المثال الثاني، سيتم تمرير كل من login
وshare
بقيمة method
'Google'
.
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' |
analytics_storage |
'granted' | 'denied' |
wait_for_update |
أي عدد صحيح موجب |
نطاق المَعلمة
يمكنك تحديد قيم المَعلمات للأحداث الفردية أو جميع الأحداث التي يتم إرسالها إلى
<TARGET_ID>
أو بشكل عام على مستوى جميع الأحداث. ويتم ذلك من خلال استخدام
الأوامر event
وconfig
وset
.
لا تعمل قيم المعلّمات التي تم ضبطها في نطاق واحد على تعديل القيم المحدّدة للمعلمة نفسها في نطاق مختلف. في المثال أدناه، لا يُعدِّل الأمر config
القيمة العامة لـ currency
التي تم تحديدها سابقًا مع الأمر set
. بعد تنفيذ كلا الأمرين، ستظل القيمة العامة لـ currency
'EUR'
.
// Set global currency to Euros
gtag('set', { 'currency': 'EUR' });
// Set currency for <TARGET_ID>
gtag('config','<TARGET_ID>', { 'currency': 'USD' });
أولوية المعلّمة
وإذا تم تحديد قيم مختلفة للمعلمة نفسها في نطاقات مختلفة، يتم استخدام قيمة واحدة فقط عند معالجة الأحداث. ستحظى قيم المَعلمات التي تم تحديد نطاقها على
event
بالأولوية على المعلّمات المستندة إلى config
، وتحظى المعلَمات config
بالأولوية على المعلّمات التي تم تحديد نطاقها عالميًا باستخدام set
.
// Set global currency to Euros
gtag('set', { 'currency': 'EUR' });
// 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>' });