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

رابط برنامه‌نویسی کاربردی (API) تگ گوگل (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' });

اولویت پارامتر

اگر مقادیر مختلفی به یک پارامتر در حوزه‌های مختلف اختصاص داده شود، هنگام پردازش رویدادها فقط از یک مقدار واحد استفاده می‌شود. مقادیر پارامتر که در 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

به شما امکان می‌دهد اطلاعات پیکربندی بیشتری را به اهداف اضافه کنید. این معمولاً یک پیکربندی مخصوص محصول برای یک محصول است، اما اگر از هر دو سرویس گوگل ادز و گوگل آنالیتیکس استفاده می‌کنید، فقط یک بار نیاز به پیکربندی این گزینه دارید.

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

<TARGET_ID> یک شناسه تگ است که مشخص می‌کند gtag.js باید داده‌های رویداد را به کجا ارسال کند. این ممکن است یک مقصد مانند یک ویژگی Google Analytics یا یک حساب Google Ads باشد، یا ممکن است یک تگ Google باشد که چندین مقصد دارد. <additional_config_info> یک یا چند جفت پارامتر-مقدار است.

این مثال یک تگ را برای ارسال داده‌ها به حساب گوگل ادز پیکربندی می‌کند:

gtag('config', 'TAG_ID');

که در آن "TAG_ID" شناسه تگ برای تگ گوگل است.

برای نشان دادن نحوه ارسال اطلاعات پیکربندی اضافی، در اینجا مثالی آورده شده است که یک برچسب را برای ارسال داده‌ها به یک حساب 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	گ-XXXXXXXXXXXX	هدفی که قرار است مقادیر از آن دریافت شوند.
<نام_فیلد>	نام فیلد	شناسه مشتری	نام فیلدی که باید دریافت شود.
تماس برگشتی	Function	(field) => console.log(field)	تابعی که با فیلد درخواستی فراخوانی می‌شود، یا اگر مقدار آن تنظیم نشده باشد undefined .

نام فیلد

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

نام فیلد	اهداف پشتیبانی شده
شناسه_مشتری	گوگل آنالیتیکس ۴
شناسه جلسه	گوگل آنالیتیکس ۴
شماره_جلسه	گوگل آنالیتیکس ۴
جی‌کلید	تبلیغات گوگل نورافکن

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

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

مهم: قطعه کد تگ گوگل باید در همان صفحه، بالای دستورات 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'	رضایت برای ارسال داده‌های کاربر به گوگل برای اهداف تبلیغاتی را تعیین می‌کند.
ad_personalization	'granted' | 'denied'	رضایت برای تبلیغات شخصی‌سازی‌شده را تعیین می‌کند.
analytics_storage	'granted' | 'denied'	ذخیره‌سازی، مانند کوکی‌ها (وب) یا شناسه‌های برنامه (اپلیکیشن‌ها)، مربوط به تجزیه و تحلیل، مثلاً مدت زمان بازدید، را فعال می‌کند.
wait_for_update	هر عدد صحیح مثبت	مدت زمان انتظار برای دریافت به‌روزرسانی رضایت‌نامه را بر حسب میلی‌ثانیه تنظیم می‌کند.