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

تتكوّن واجهة برمجة التطبيقات لعلامة تتبُّع من 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>":

  • ‫<TARGET_ID> في الأمر gtag('config', <TARGET_ID>, ...) هو معرّف علامة يحدّد المكان الذي يجب أن ترسل إليه gtag.js بيانات الأحداث. قد تكون هذه الوجهة موقعًا على "إحصاءات Google" أو حسابًا على "إعلانات Google" أو إعدادات Floodlight أو علامة تتبُّع من Google لها وجهات متعددة.

  • معرِّف علامة التتبُّع، مثل GT-XXXXXX أو G-XXXXXX أو AW-YYYYYY، هو معرِّف لـ "علامة التتبُّع من Google". يمكنك إضافة هذا المعرّف إلى رمز موقعك الإلكتروني لتحميل علامة التتبُّع من Google.

  • يمكن إعداد علامة تتبُّع واحدة من Google (يتم تحديدها من خلال رقم تعريف العلامة) لإرسال البيانات إلى وجهات متعددة. مع أنّ بعض أرقام تعريف العلامات قد تبدو مطابقة لأرقام تعريف الوجهات، مثل G-XXXXXX لموقع على "إحصاءات Google" أو AW-YYYYYY لحساب على "إعلانات Google"، يشير <TARGET_ID> في الأمر config إلى النسخة المحدّدة من علامة التتبُّع من Google التي تم تحميلها على الصفحة.

  • يضبط الأمر gtag('config', ...) سلوك علامة التتبُّع من Google المرتبطة بـ <TARGET_ID> المحدّد. على الرغم من أنّ معرّف العلامة المضمّن في النص البرمجي src يحمّل عادةً علامة التتبُّع من Google، يمكنك استخدام أي معرّف علامة صالح مرتبط بحسابك في الأمر gtag('config').

  • يمكن أن تشتمل علامة تتبُّع واحدة من Google على أرقام تعريف علامات متعددة مرتبطة بها، وغالبًا ما يكون ذلك بسبب دمج العلامات. يمكن استخدام أي من هذه المعرّفات المرتبطة في مَعلمة النص البرمجي src لتحميل علامة التتبُّع من Google.

  • إذا كنت ترسل البيانات إلى وجهات متعددة أو تستخدم علامات تتبُّع متعددة، ما عليك سوى تضمين مقتطف علامة تتبُّع من Google واحد مع رقم تعريف علامة واحد في النص البرمجي src. بعد ذلك، يمكنك تضمين أمر gtag('config') لكل رقم تعريف علامة أو وجهة إضافية.

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