مرجع دستورهای تراکر

ap() تنها ورودی است#

قطعه کد نصب سه خط دارد. خط اول تابع ap را می‌سازد و برایش یک صف باز می‌کند، خط دوم فایل تراکر را به صورت async می‌گیرد، و خط سوم init را صدا می‌زند. تا وقتی فایل نرسیده، هر فراخوانی در صف می‌ماند و بعد به ترتیب اجرا می‌شود — پس هر جای صفحه می‌توانید ap(...) بنویسید بدون اینکه نگران زمان بندی باشید.

نام __sov هم به همان تابع اشاره می‌کند و برای سازگاری با نصب های قدیمی برای همیشه می‌ماند. لازم نیست از آن استفاده کنید و لازم هم نیست حذفش کنید.

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

فهرست دستورها#

init — راه اندازی#

ap('init', { id: 'AP-XXXXXXXXXX', endpoint: 'https://collect.adpix.net' });

این تنها دستوری است که حتما باید صدا زده شود، و قطعه کدی که کنسول می‌سازد خودش آن را دارد. init به تنهایی این کارها را می‌کند:

• اولین page_view را می‌فرستد؛
• قلاب History را نصب می‌کند تا سایت‌های تک صفحه‌ای هم با هر تغییر آدرس بازدید صفحه بفرستند؛
• کوکی‌ها را روی گسترده ترین دامنه قابل تنظیم می‌نویسد تا زیردامنه‌ها یک بازدیدکننده باشند؛
• پیکربندی دارایی را می‌گیرد و بر اساس آن اندازه‌گیری پیشرفته، نقشه حرارتی و بنر رضایت را روشن می‌کند؛
• شنونده شناسایی خودکار فرم ها و لینکزن میان دامنه را وصل می‌کند.

فراخوانی دوم init با همان شناسه اندازه‌گیری بی اثر است؛ حتی اگر دو نسخه از فایل تراکر روی صفحه باشد، فقط یکی راه می‌افتد.

page — بازدید صفحه#

ap('page');

آرگومانی نمی‌گیرد. آدرس، عنوان و ارجاع دهنده از خود صفحه خوانده می‌شوند.

در هر بارگذاری صفحه، برای هر آدرس یکتا فقط یک بازدید صفحه فرستاده می‌شود. «آدرس» یعنی مسیر به علاوه رشته پرسش؛ قطعه بعد از # حساب نمی‌شود. پس اگر برنامه تان برای مرتب سازی جدول یا باز کردن یک زبانه replaceState صدا می‌زند، بازدید صفحه اضافی ثبت نمی‌شود. بارگذاری کامل صفحه شمارنده را از نو شروع می‌کند، پس نوسازی صفحه همچنان یک بازدید تازه است.

در عمل تقریبا هیچ وقت لازم نیست page را دستی صدا بزنید. تنها حالت واقعی این است که autoPage را خاموش کرده باشید یا اندازه‌گیری پیشرفته را طوری تنظیم کرده باشید که بازدید صفحه‌ها خاموش باشد.

track — رویداد سفارشی#

ap('track', 'signup_completed', { plan: 'pro', trial_days: 14 });

آرگومان اول نام رویداد است و همان چیزی است که در گزارش «رویدادها» می‌بینید. آرگومان دوم اختیاری است: یک شیء ساده که هر کلیدش یک خصیصه رویداد می‌شود.

چند نکته که وقتتان را نجات می‌دهد:

• نام رویداد را ثابت و با حروف کوچک و زیرخط بنویسید. signup_completed و SignupCompleted دو رویداد جدا شمرده می‌شوند.
• مقدارها را تخت نگه دارید. شیء تودرتو ذخیره می‌شود ولی خواندنش در گزارش‌ها دشوار است.
• اگر رویداد پول دارد، کلید value را بگذارید؛ همان کلیدی است که برای درآمد رویدادهای کلیدی خوانده می‌شود.
• هیچ وقت رمز عبور، شماره کارت یا داده ای که حق نگه داشتنش را ندارید در خصیصه ها نفرستید.

ecommerce — رویداد تجاری#

ap('ecommerce', 'add_to_cart', {
  currency: 'IRR',
  value: 2450000,
  items: [{ item_id: 'SKU-42', item_name: 'کیف چرم', price: 2450000, quantity: 1 }],
});

مثل track عمل می‌کند، با این تفاوت که آرایه items را در یک بافتار جداگانه می‌فرستد تا گزارش تجارت الکترونیک بتواند سطر به سطر محصول ها را بشمارد. نام های مجاز، فیلدهای هر قلم و اینکه خرید را بهتر است از سرور بفرستید یا از مرورگر، در رویدادهای تجارت الکترونیک آمده است.

identify — شناسایی کاربر#

ap('identify', 'user_8421', { email: 'ali@example.com', phone: '09121234567', plan: 'pro' });

آرگومان اول شناسه کاربر در سیستم خودتان است. اگر شناسه ای ندارید می‌توانید رشته خالی بدهید و فقط ایمیل یا شماره بفرستید.

آرگومان دوم شیء ویژگی هاست. email و phone معنی ویژه دارند: سرور آن‌ها را نرمال و هش می‌کند و از آن‌ها به عنوان کلید قطعی برای دوختن هویت استفاده می‌کند. بقیه کلیدها — نام، شرکت، طرح و هر چیز دیگری — روی کاربر انباشته می‌شوند.

بعد از یک شناسایی موفق، رویدادهای ناشناس پیش از ورود هم به همان کاربر وصل می‌شوند.

google — ورود با گوگل#

google.accounts.id.initialize({
  client_id: '…',
  callback: (r) => { ap('google', r); },
});

پاسخ کتابخانه Google Identity Services را همان طور که هست بدهید. تراکر توکن را در مرورگر باز می‌کند، ایمیل و شناسه گوگل را بیرون می‌کشد و با آن‌ها identify را صدا می‌زند. اگر توکن ایمیل نداشته باشد، هیچ اتفاقی نمی‌افتد.

reset — پاک کردن برخوردها#

ap('reset');

کوکی‌های اولین و آخرین برخورد را حذف می‌کند و بس. شناسه بازدیدکننده، نشست و رویدادهای ثبت شده دست نخورده می‌مانند.

این دستور را برای «خروج کاربر» یا «حذف داده‌های کاربر» به کار نبرید — کارش این نیست. تنها کاربرد واقعی اش صفحه آزمایش خودتان است، وقتی می‌خواهید اتریبیوشن را از صفر شروع کنید.

رویدادهایی که خودتان نمی‌فرستید#

جدا از این هفت دستور، اگر اندازه‌گیری پیشرفته روی جریان روشن باشد تراکر خودش رویدادهایی مثل اسکرول، کلیک خروجی، دانلود فایل، جستجوی داخل سایت، شروع و ارسال فرم و پخش ویدیو را می‌فرستد. هر کدام را می‌شود جداگانه خاموش کرد؛ فهرست کامل و نحوه تنظیمشان در اندازه‌گیری پیشرفته است.

یک رویداد user_engagement هم هنگام پنهان شدن صفحه فرستاده می‌شود و مدت واقعی حضور را حمل می‌کند؛ همین عدد است که میانگین زمان نشست را می‌سازد.

قاعده‌هایی که روی همه دستورها اثر دارند#

• رضایت. page، track، ecommerce، identify و شناسایی خودکار همه به دسته «آماری» گره خورده‌اند. در حالت پذیرش، تا وقتی بازدیدکننده انتخاب نکرده هیچ کدام اجرا نمی‌شوند و رفتار پیش‌فرض بسته است، نه باز.
• انصراف. اگر کوکی __sov_x با مقدار 1 روی مرورگر باشد، هیچ رویدادی نه ساخته می‌شود و نه پذیرفته.
• ارسال دسته ای. رویدادها بلافاصله نمی‌روند؛ در یک صف جمع می‌شوند و هر ۵ ثانیه، یا با رسیدن به ۲۰ رویداد، یا هنگام پنهان شدن صفحه یک جا فرستاده می‌شوند. برای همین بلافاصله بعد از یک track انتظار نداشته باشید عدد گزارش تکان بخورد.
• از دست نرفتن. اگر ارسال شکست بخورد، دسته به صف برمی گردد و صف در حافظه محلی مرورگر آینه می‌شود، پس بستن ناگهانی مرورگر رویدادها را نمی‌سوزاند. این صف سقف دارد تا یک مقصد خراب نتواند بی نهایت بزرگش کند.

پرسش‌های پرتکرار#

مطالب مرتبط#