مرجع میانای برنامه‌سازی کاربردی برچسب Google

میانای برنامه‌سازی کاربردی برچسب Google‏ (gtag.js) از یک تابع واحد، gtag()، با نحو زیر تشکیل شده است:

gtag(<command>, <command parameters>);
  • ‫<command> یکی از فرمان‌های زیر است:
  • <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 Ads و Google Analytics استفاده می‌کنید، فقط یک‌بار باید آن را پیکربندی کنید.

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

نکات کلیدی درباره <TARGET_ID>:

  • <TARGET_ID> در فرمان gtag('config', <TARGET_ID>, ...) یک «شناسه برچسب» است که مشخص می‌کند gtag.js باید داده‌های رویداد را به کجا ارسال کند. این مقصد می‌تواند دارایی Google Analytics، حساب Google Ads، پیکربندی Floodlight، یا برچسب Google با چند مقصد باشد.

  • «شناسه برچسب»—مثل GT-XXXXXX،‏ G-XXXXXX، یا AW-YYYYYY—شناسه‌ای برای برچسب Google شما است. این شناسه را به کد وب‌سایتتان اضافه می‌کنید تا برچسب Google بار شود.

  • یک برچسب Google (که با شناسه برچسب آن شناسایی می‌شود) می‌تواند برای ارسال داده به چندین مقصد پیکربندی شود. اگرچه برخی‌از شناسه‌های برچسب ممکن است شبیه به شناسه‌های مقصد باشند، مانند G-XXXXXX برای دارایی Google Analytics یا AW-YYYYYY برای حساب Google Ads، اما <TARGET_ID> در فرمان config به نمونه خاصی از برچسب Google بارشده در صفحه اشاره دارد.

  • فرمان gtag('config', ...) رفتار برچسب Google مرتبط با آن <TARGET_ID> خاص را پیکربندی می‌کند. درحالی‌که «شناسه برچسب» موجود در اسکریپت src معمولاً برچسب Google را بار می‌کند، می‌توانید از هر «شناسه برچسب» معتبری که با حسابتان در فرمان gtag('config') مرتبط است استفاده کنید.

  • یک برچسب Google می‌تواند چندین شناسه برچسب مرتبط با خود داشته باشد، که اغلب به‌دلیل ادغام برچسب‌ها است. هرکدام از این شناسه‌های منسوب را می‌توان در پارامتر src در دستورگان برای بار کردن برچسب Google استفاده کرد.

  • اگر داده‌ها را به چند مقصد ارسال می‌کنید یا از چند برچسب استفاده می‌کنید، فقط باید یک تکه‌کد برچسب Google با یک شناسه برچسب در اسکریپت src اضافه کنید. سپس برای هر شناسه برچسب یا مقصد اضافی، یک فرمان gtag('config') اضافه می‌کنید.

<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)
متغیر مستقل نوع مثال شرح
<target> string G-XXXXXXXXXX

هدف برای واکشی مقادیر از آن.
<field_name> FieldName client_id نام فیلد برای دریافت.
بازخوانی Function (field) => console.log(field)

تابعی که با فیلد درخواست‌شده فراخوانی می‌شود، یا undefined اگر تنظیم نشده باشد.

FieldName

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

نام فیلد هدف‌های پشتیبانی‌شده
client_id
  • Google Analytics 4
session_id
  • Google Analytics 4
session_number
  • Google Analytics 4
gclid
  • Google Ads
  • Floodlight

مثال‌ها

دریافت مقدار در Promise 

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 استفاده کرده‌اید، همه برچسب‌های دیگر، برای مثال برچسب‌های «رویداد 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'
});

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