مرجع API برچسب گوگل

API تگ Google (gtag.js) از یک تابع واحد به gtag() با نحو زیر تشکیل شده است:

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

• <command> یکی از دستورات زیر است:
  • config
  • get
  • set
  • event
  • consent
• <command parameters> پارامترهایی هستند که می توانید به gtag() بدهید. پارامترهای فرمان با توجه به دستور متفاوت است. به مرجع فرمان در زیر مراجعه کنید.

شما می توانید دستورات gtag() را در هر نقطه از صفحه خود فراخوانی کنید، تا زمانی که دستورات شما در زیر قطعه تگ گوگل ظاهر شوند. برای یادگیری نحوه افزودن قطعه به یک صفحه، راهنمای نصب را ببینید.

دامنه پارامتر

می‌توانید مقادیر پارامترها را به رویدادهای جداگانه، همه رویدادهای ارسال شده به یک <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' });

تقدم پارامتر

اگر مقادیر متفاوتی به یک پارامتر در حوزه‌های مختلف اختصاص داده شود، هنگام پردازش رویدادها فقط از یک مقدار استفاده می‌شود. مقادیر پارامترهای scoped به event بر پارامترهای scoped برای config ارجحیت دارند و پارامترهای config بر پارامترهایی که به صورت سراسری با استفاده از set scope داده شده اند اولویت دارند.

// 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 Ads و Google Analytics استفاده می‌کنید، فقط یک بار باید آن را پیکربندی کنید.

gtag('config', '<TARGET_ID>', {<additional_config_info>});

<TARGET_ID> شناسه‌ای است که به طور منحصربه‌فرد هدف را برای بازدیدها شناسایی می‌کند، مانند دارایی Google Analytics یا حساب Google Ads. <additional_config_info> یک یا چند جفت پارامتر-مقدار است.

این مثال یک برچسب را برای ارسال داده به حساب Google Ads پیکربندی می کند:

gtag('config', 'TAG_ID');

جایی که "TAG_ID" شناسه برچسب برای تگ Google است.

برای نشان دادن نحوه ارسال اطلاعات پیکربندی اضافی، در اینجا مثالی وجود دارد که یک برچسب را برای ارسال داده به حساب Analytics با پارامتر 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)

استدلال	تایپ کنید	مثال	توضیحات
<هدف>	string	G-XXXXXXXXXX	هدف برای واکشی مقادیر از.
<field_name>	نام فیلد	client_id	نام فیلد برای بدست آوردن.
پاسخ به تماس	Function	(field) => console.log(field)	تابعی که با فیلد درخواستی فراخوانی می شود، یا اگر تنظیم نشده باشد، undefined .

نام فیلد

نام فیلد می تواند نام یک فیلد سفارشی باشد که با دستور gtag('set') تنظیم کرده اید یا یکی از مقادیر زیر:

نام فیلد	اهداف پشتیبانی شده
client_id	گوگل آنالیتیکس 4
session_id	گوگل آنالیتیکس 4
gclid	تبلیغات گوگل نورافکن

توجه: اگر از دستور set با نام این فیلدها استفاده کنید، مقداری که تنظیم کرده اید اولویت دارد.

نمونه ها

ارزش یک وعده را دریافت کنید

const gclidPromise = new Promise(resolve => {
  gtag('get', 'DC-XXXXXXXX', 'gclid', resolve)
});

gclidPromise.then((gclid) => {
  // Do something with gclid...
})

رویداد را به پروتکل اندازه گیری ارسال کنید

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 استفاده کرده‌اید، همه برچسب‌های دیگر، برای مثال، برچسب‌های رویداد GA4 یا برچسب‌های بازاریابی مجدد Google Ads، می‌توانند به این داده‌ها دسترسی داشته باشند.

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	هر عدد صحیح مثبت	زمانی را بر حسب میلی ثانیه تنظیم می کند تا منتظر تماس به روز رسانی رضایت باشید.