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

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

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

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

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

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

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

| دستور | آرگومان ها | چه می‌فرستد |
| --- | --- | --- |
| `ap('init', options)` | شیء تنظیمات | اولین `page_view` + راه اندازی همه چیز |
| `ap('page')` | ندارد | یک `page_view`، اگر آدرس تازه باشد |
| `ap('track', name, props)` | نام رویداد، شیء خصیصه ها | یک رویداد سفارشی با همان نام |
| `ap('ecommerce', name, data)` | نام رویداد تجاری، شیء تجارت الکترونیک | رویداد تجاری + بافتار اقلام |
| `ap('identify', id, traits)` | شناسه کاربر، شیء ویژگی ها | یک رویداد شناسایی |
| `ap('google', response)` | پاسخ ورود با گوگل | یک رویداد شناسایی با ایمیل داخل توکن |
| `ap('reset')` | ندارد | چیزی نمی‌فرستد؛ کوکی‌های برخورد را پاک می‌کند |

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

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

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

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

| کلید | پیش‌فرض | معنی |
| --- | --- | --- |
| `id` | ندارد | شناسه اندازه‌گیری جریان، با `AP-` شروع می‌شود. اگر ندهید از پارامتر `?id=` روی آدرس خود اسکریپت خوانده می‌شود. |
| `endpoint` | ندارد | مقصد ارسال رویدادها. در حالت دروازه تگ، دامنه خودتان. |
| `autoPage` | `true` | اگر `false` بگذارید، `init` بازدید صفحه نمی‌فرستد و مسئولیتش با شماست. |
| `autoIdentify` | `true` | شناسایی خودکار از روی فرم های ورود و ثبت نام. با `false` خاموش می‌شود. |

> **کنار init یک ap('page') نگذارید**
>
> `init` خودش اولین بازدید صفحه را می‌فرستد. اگر بلافاصله بعدش `ap('page')` هم بنویسید، این فراخوانی روی همان آدرس نادیده گرفته می‌شود — ولی نصب های قدیمی که این خط را دارند ریشه شمارش چندبرابری بودند. قطعه کد را از کنسول بردارید و دست نبرید.

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

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

```js
ap('page');
```

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

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

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

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

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

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

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

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

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

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

مثل `track` عمل می‌کند، با این تفاوت که آرایه `items` را در یک بافتار جداگانه می‌فرستد تا گزارش تجارت الکترونیک بتواند سطر به سطر محصول ها را بشمارد. نام های مجاز، فیلدهای هر قلم و اینکه خرید را بهتر است از سرور بفرستید یا از مرورگر، در [رویدادهای تجارت الکترونیک](analytics/collect/ecommerce-events) آمده است.

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

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

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

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

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

> **اغلب لازم نیست خودتان صدایش بزنید**
>
> تراکر هنگام ارسال فرم، ورودی های ایمیل و تلفن را می‌خواند و خودش شناسایی می‌کند. رمز عبور و بقیه فیلدها هیچ وقت خوانده نمی‌شوند. اگر ورود شما با فرم معمولی انجام می‌شود، احتمالا همین کافی است؛ `identify` را برای وقتی نگه دارید که ورود بدون ارسال فرم انجام می‌شود یا می‌خواهید ویژگی های بیشتری بفرستید.

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

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

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

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

```js
ap('reset');
```

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

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

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

جدا از این هفت دستور، اگر اندازه‌گیری پیشرفته روی جریان روشن باشد تراکر خودش رویدادهایی مثل اسکرول، کلیک خروجی، دانلود فایل، جستجوی داخل سایت، شروع و ارسال فرم و پخش ویدیو را می‌فرستد. هر کدام را می‌شود جداگانه خاموش کرد؛ فهرست کامل و نحوه تنظیمشان در [اندازه‌گیری پیشرفته](analytics/collect/enhanced-measurement) است.

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

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

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

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

### می‌توانم ap را قبل از بارگذاری فایل تراکر صدا بزنم؟

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

### فرق ap و __sov چیست؟

هیچ. هر دو به یک تابع اشاره می‌کنند. ap نام فعلی است و __sov نام قدیمی که برای سایت‌هایی که قطعه کد قدیمی دارند برای همیشه نگه داشته می‌شود. صف هر دو هم خالی می‌شود.

### چرا رویدادی که فرستادم در گزارش نیست؟

سه دلیل رایج دارد. ممکن است بازدیدکننده دسته «آماری» را نپذیرفته باشد، یا کوکی انصراف روی مرورگر باشد، یا رویداد هنوز در دسته ای منتظر ارسال مانده باشد؛ دسته‌ها هر ۵ ثانیه، هر ۲۰ رویداد و هنگام بسته شدن صفحه فرستاده می‌شوند.

### ap('reset') همه چیز را پاک می‌کند؟

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

## مطالب مرتبط

- [رویدادهای تجارت الکترونیک](https://docs.adpix.io/fa/analytics/collect/ecommerce-events/)
- [اندازه‌گیری پیشرفته](https://docs.adpix.io/fa/analytics/collect/enhanced-measurement/)
- [نصب تگ اندازه‌گیری](https://docs.adpix.io/fa/analytics/start/install-the-tag/)

---

[مستندات](https://docs.adpix.io/fa/analytics/collect/tracker-reference/) · AdPix