استفاده از پلاگین ها

پلاگین ها اسکریپت هایی هستند که عملکرد analytics.js را برای کمک به اندازه گیری تعامل کاربر افزایش می دهند. افزونه‌ها معمولاً مختص مجموعه‌ای از ویژگی‌هایی هستند که ممکن است برای همه کاربران Google Analytics مورد نیاز نباشد، مانند تجارت الکترونیک یا اندازه‌گیری بین دامنه‌ای ، و بنابراین به‌طور پیش‌فرض در analytics.js گنجانده نشده‌اند.

این راهنما نحوه نیاز و استفاده از افزونه های analytics.js را توضیح می دهد.

نیاز به پلاگین

دستور require نام یک افزونه را می گیرد و آن را برای استفاده در صف فرمان ga() ثبت می کند. اگر افزونه گزینه‌های پیکربندی را بپذیرد، آن گزینه‌ها می‌توانند به عنوان آرگومان نهایی به دستور require ارسال شوند.

زیر امضای کامل فرمان require است:

ga('[trackerName.]require', pluginName, [pluginOptions]);

به عنوان مثال، در اینجا نحوه نیاز به افزونه تجارت الکترونیک پیشرفته برای استفاده با ردیاب پیش فرض وجود دارد:

ga('require', 'ec');

و در اینجا نحوه نیاز به افزونه Advertising Features برای یک ردیاب به نام "myTracker" و ارسال یک گزینه پیکربندی است که مقدار نام کوکی پیش‌فرض را لغو می‌کند:

ga('myTracker.require', 'displayfeatures', {
  cookieName: 'display_features_cookie'
});

در حال بارگیری کد افزونه

دستور require متدهای افزونه را برای استفاده در صف فرمان ga() مقداردهی اولیه می کند، اما خود اسکریپت افزونه را بارگذاری نمی کند. اگر از یک افزونه شخص ثالث استفاده می کنید، یا خودتان یک افزونه می نویسید ، باید کد افزونه را به صورت دستی به صفحه اضافه کنید.

روش پیشنهادی برای افزودن کد افزونه به صفحه از طریق تگ <script> با ویژگی async تنظیم شده است تا اطمینان حاصل شود که بارگذاری سایر ویژگی‌ها در سایت شما را مسدود نمی‌کند.

کد زیر هم به یک افزونه فرضی ردیابی لینک نیاز دارد و هم آن را بارگذاری می کند:

<script>
ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'linkTracker');
ga('send', 'pageview');
</script>

<!--Note: plugin scripts must be included after the tracking snippet. -->
<script async src="/path/to/link-tracker-plugin.js"></script>

توجه: پلاگین های رسمی Google Analytics برای analytics.js در صورت نیاز به طور خودکار بارگذاری می شوند. شما نیازی به اضافه کردن تگ های اسکریپت برای آنها ندارید. لیست کامل افزونه‌های رسمی analytics.js را می‌توانید در بخش پلاگین‌های رسمی در ناوبری سمت چپ پیدا کنید.

در انتظار بارگیری افزونه ها

از آنجایی که هم کتابخانه analytics.js و هم افزونه analytics.js به صورت ناهمزمان بارگیری می شوند، دانستن اینکه چه زمانی پلاگین ها به طور کامل بارگیری شده و آماده استفاده هستند می تواند چالش برانگیز باشد.

کتابخانه analytics.js این مشکل را با توقف اجرای صف فرمان زمانی که با یک دستور require برای افزونه‌ای که هنوز بارگذاری نشده است مواجه می‌شود، حل می‌کند. پس از بارگیری افزونه، اجرای صف به صورت عادی ادامه می یابد.

در نتیجه، بسیار مهم است که افزونه هایی را که استفاده می کنید آزمایش کنید تا مطمئن شوید که آنها به درستی بارگیری و اجرا می شوند. اگر پلاگین بارگیری نشود یا خطا داشته باشد، از اجرای تمام دستورات بعدی analytics.js جلوگیری می کند.

فراخوانی روش های افزونه

پس از نیاز به یک افزونه، متدهای آن برای استفاده در صف فرمان ga() در دسترس می‌شوند. در اینجا امضای فرمان برای فراخوانی متدهای افزونه آمده است:

ga('[trackerName.][pluginName:]methodName', ...args);

به عنوان مثال، متد addProduct افزونه Enhanced Ecommerce را می توان به این صورت نامید:

ga('ec:addProduct', {
  'id': 'P12345',
  'quantity': 1
});

یا در یک ردیاب با نام با افزودن نام ردیاب به رشته فرمان:

ga('myTracker.ec:addProduct', {
  'id': 'P12345',
  'quantity': 1
});

مراحل بعدی

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