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

تتألف واجهة برمجة تطبيقات علامة 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)

دالة سيتم استدعاءها باستخدام الحقل المطلوب، أو undefined إذا لم يتم ضبطها.

اسم الحقل

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

اسم الحقل الأهداف المتاحة
client_id
  • إحصاءات Google‏ 4
  • Universal Analytics في "إحصاءات Google"
session_id
  • إحصاءات Google‏ 4
gclid
  • إعلانات Google
  • Floodlight

أمثلة

الاستفادة من الوعد 

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> هو أي مما يلي:

<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'
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>' });