تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

الوسيطة	Type	مثال	الوصف
<target>	`string`	G-XXXXXXXXXX	الهدف المطلوب جلب القيم منه.
<field_name>	FieldName	client_id	اسم الحقل المطلوب الحصول عليه.
رد الاتصال	`Function`	`(field) => console.log(field)`	يشير ذلك المصطلح إلى دالة سيتم استدعاؤها مع الحقل المطلوب، أو `undefined` في حال عدم ضبط السياسة.

FieldName

يمكن أن يكون اسم الحقل هو اسم حقل مخصّص تعيّنه باستخدام الأمر 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', {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`	أي عدد صحيح موجب	تحدِّد هذه السياسة وقتًا بالملي ثانية لانتظار طلب تعديل الموافقة.