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

FieldName

يمكن أن يكون اسم الحقل هو اسم حقل مخصّص أعددته باستخدام السمة gtag('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 تحديد المعلمات التي سيتم ربطها بكل الحدث اللاحق على الصفحة.

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> التالية: