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

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

gtag(<command>, <command parameters>);
  • <command> یکی از دستورات زیر است:
  • <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> :

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

  • شناسه‌ی تگ - مانند GT-XXXXXX ، G-XXXXXX یا AW-YYYYYY - شناسه‌ای برای تگ گوگل شماست. شما این شناسه را به کد وب‌سایت خود اضافه می‌کنید تا تگ گوگل بارگذاری شود.

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

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

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

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

<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') تنظیم می‌کنید، یا یکی از مقادیر زیر باشد:

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

مثال‌ها

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

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

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

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