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

تتألّف واجهة برمجة تطبيقات علامة Google (gtag.js) من دالة واحدة، هي gtag()، بالبنية التالية:

gtag(<command>, <command parameters>);

• <command> هو أحد الأوامر التالية:
  • config
  • get
  • set
  • event
  • consent
• <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	اسم الحقل المطلوب الحصول عليه.
ردّ الاتصال	Function	(field) => console.log(field)	دالة سيتمّ استدعاؤها باستخدام الحقل المطلوب، أو undefined إذا لم يتمّ ضبطها.

FieldName

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

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

ملاحظة: إذا كنت تستخدم الأمر set مع أسماء الحقول هذه، ستكون الأولوية للقيمة التي تضبطها.

أمثلة

تحقيق وعود قيّمة

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 تحديد المَعلمات التي سيتم ربطها بكل حدث لاحق على الصفحة.

ملاحظة: ننصح باستخدام الأمر config أو event كلما أمكن ذلك.

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

ملاحظة مهمة: يجب أن يظهر مقتطف علامة Google على الصفحة نفسها، فوق أوامر event، وإلا لن يتم إرسال بياناتك.

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	أي عدد صحيح موجب	تُستخدَم لضبط وقت بالملي ثانية في انتظار طلب تعديل الموافقة.