# تعریف‌های سفارشی

هر پارامتری که همراه رویدادهایتان می‌فرستید ذخیره می‌شود، ولی تا وقتی ثبتش نکنید در هیچ فهرستی برای انتخاب ظاهر نمی‌شود. تعریف سفارشی همان کلید را به یک بعد یا سنجه قابل انتخاب تبدیل می‌کند — بدون پردازش دوباره و بدون تغییر در جمع آوری داده.

## تعریف سفارشی دقیقا چه کاری می‌کند

وقتی با `ap('track', …)` یک رویداد می‌فرستید، شیء خصیصه هایش عینا به شکل JSON کنار همان رویداد ذخیره می‌شود. هیچ چیزی از آن گم نمی‌شود، ولی هیچ چیزی هم از آن به طور خودکار در گزارش‌ها ظاهر نمی‌شود، چون ادپیکس نمی‌داند کدام کلید ارزش گروه بندی دارد و کدام یکی فقط شناسه داخلی شماست.

تعریف سفارشی همین نگاشت را می‌سازد: «کلید `plan` در props را به عنوان یک بعد قابل انتخاب بشناس». از آن لحظه، هر پرس وجویی که آن بعد را بخواهد، مقدار را در زمان خواندن مستقیم از JSON همان رویداد بیرون می‌کشد.

نتیجه عملی این معماری دو چیز است:

- **هیچ پردازش دوباره ای در کار نیست.** تعریف را همین حالا بسازید، گزارش را همین حالا بگیرید.
- **تعریف، داده نمی‌سازد.** اگر رویداد پارامتر را حمل نکرده باشد، هیچ ثبتی آن را نمی‌سازد.

> **گذشته پر نمی‌شود**
>
> ثبت تعریف، پارامتری را که رویدادهای ذخیره شده **از قبل** داشته‌اند قابل خواندن می‌کند — از این نظر برای داده‌های موجود عقب گرد دارد. ولی رویدادهایی که در زمان ارسال آن پارامتر را نداشتند تا ابد خالی می‌مانند. ترتیب درست این است: اول پارامتر را در رویدادها بفرستید، بعد تعریفش کنید.

## ساختن یک تعریف

1. در کنسول «مدیریت» را باز کنید.
2. در ستون «تنظیمات دارایی»، کارت «نمایش داده» و بعد «تعریف‌های سفارشی» را انتخاب کنید.
3. «کلید props» را دقیقا همان طور که در رویداد می‌فرستید بنویسید — مثلا `plan`.
4. «نام نمایشی» را پر کنید، «نوع» و «نوع مقدار» را انتخاب کنید و «افزودن» را بزنید.

> ابعاد و سنجه‌های سفارشی ساخته‌شده از پارامترهای رویداد. — [analytics.adpix.io/fa/admin?sel=custom-definitions](https://analytics.adpix.io/fa/admin?sel=custom-definitions)

هر ردیف جدول، یک نگاشت است: کلید props، نام نمایشی، نوع و نوع مقدار. اگر همان کلید را دوباره اضافه کنید ردیف تکراری ساخته نمی‌شود؛ نام نمایشی و نوع همان ردیف به روز می‌شود. «حذف» هم فقط نگاشت را برمی‌دارد — مقدارها همچنان روی رویدادها هستند و هر وقت خواستید می‌توانید دوباره ثبتش کنید.

ساختن و حذف تعریف از «تحلیل گر» به بالا ممکن است. خواندن فهرست با دسترسی بیننده هم کار می‌کند.

## نوع مقدار تصمیم می‌گیرد، نه ستون «نوع»

این تنها جایی است که فرم می‌تواند گمراهتان کند. آنچه رفتار واقعی را تعیین می‌کند «نوع مقدار» است:

| نوع مقدار | چه چیزی ساخته می‌شود | در کاوش چطور دیده می‌شود |
| --- | --- | --- |
| رشته | یک بعد (برای گروه بندی) | یک تراشه در فهرست «ابعاد» |
| عدد | دو سنجه: جمع و میانگین | دو تراشه در فهرست «سنجه ها» |

اگر «نوع» را روی «سنجه» بگذارید ولی «نوع مقدار» را «رشته» رها کنید، تعریف در عمل یک بعد می‌شود. برای هر چیزی که می‌خواهید جمع یا میانگینش را ببینید — مبلغ، تعداد، امتیاز — «عدد» را انتخاب کنید.

نکته دوم درباره خود کلید: فقط حرف انگلیسی، رقم، زیرخط و نقطه در نام کلید معتبر است و نام بلندتر از ۶۴ کاراکتر کوتاه می‌شود. کلیدی مثل `order-id` یا کلیدی با فاصله، هرگز به همان کلید داخل رویداد نمی‌رسد و همیشه خالی برمی گردد. مقدارها را هم تخت بفرستید (متن یا عدد)، نه شیء تودرتو.

## کجا از تعریف‌های سفارشی استفاده می‌شود

تعریف‌های سفارشی در گزارش‌های استاندارد — خانه، جذب، ترافیک، تعامل، رویدادها، تجارت الکترونیک — ظاهر **نمی‌شوند**. جای آن‌ها سطح کاوش است:

| جا | چطور استفاده می‌شود |
| --- | --- |
| گزارش‌ها و کاوش | تراشه های ابعاد و سنجه ها در پنل متغیرها؛ حداکثر ۳ بعد و ۴ سنجه هم زمان |
| مخاطبان | به عنوان فیلد یک شرط — نام فیلد را خودتان تایپ می‌کنید |
| کاوش مسیر، هم‌پوشانی بخش‌ها، ارزش طول عمر | به عنوان بعد گروه بندی یا داخل شرط بخش |

در پنل متغیرها، برچسب تراشه از خود کلید props ساخته می‌شود نه از نام نمایشی: زیرخط ها به فاصله تبدیل می‌شوند و سنجه عددی به شکل `sum · order total` و `avg · order total` دیده می‌شود.

یک استثنا را بدانید تا وقت تلف نکنید: سازنده **بخش‌ها** فیلد را از فهرست ثابتی از ابعاد داخلی می‌گیرد و بعدهای سفارشی در آن فهرست نیستند. شرط روی یک بعد سفارشی را در سازنده **مخاطبان** بسازید؛ آنجا نام فیلد یک ورودی متنی است.

> **کاوش ممکن است به پلن گره خورده باشد**
>
> دسترسی به «گزارش‌ها و کاوش» یکی از قابلیت های وابسته به پلن دارایی است. ساختن تعریف در پنل مدیریت همیشه ممکن است، ولی اگر صفحه کاوش برای آن دارایی قفل باشد، تعریف تازه ای که ساخته‌اید جایی برای خوانده شدن ندارد. جزئیات در [نقش ها و محدودیت های داده](concepts/governance/roles-and-data-restrictions) آمده است.

## کاردینالیتی: کدام کلیدها را ثبت نکنید

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

پرس وجوی کاوش، ردیف‌ها را بر اساس اولین سنجه از بزرگ به کوچک مرتب می‌کند و همان جا می‌برد؛ عددی که در «نمایش ردیف‌ها» انتخاب می‌کنید، سقف خود پرس وجوست، نه فقط سقف نمایش. **ردیف «سایر» وجود ندارد** — دم توزیع نه جمع می‌شود و نه دیده می‌شود، پس جمع ستون در جدول با کل واقعی برابر نیست.

| ثبتش کنید | ثبتش نکنید |
| --- | --- |
| `plan`، `category`، `payment_method`، `logged_in`، `ab_variant` | `order_id`، `transaction_id`، `email`، `session_key`، هر شناسه یکتا |

قاعده ساده: اگر انتظار ندارید همان مقدار روی ده ها رویداد تکرار شود، بعد خوبی نیست. برای شناسه‌های یکتا سراغ گزارش‌های تراکنشی بروید، نه گروه بندی.

## دامنه رویداد و دامنه کاربر

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

پیامدش را در عمل ببینید: اگر خصیصه ای را فقط یک بار — مثلا همراه `ap('identify', …)` — بفرستید، آن مقدار فقط روی همان یک رویداد می‌نشیند. اگر بعد بخواهید بازدید صفحه‌ها را بر اساس آن گروه بندی کنید، تقریبا همه چیز در سطل خالی می‌افتد.

دو راه درست دارید:

- پارامتر را روی همان رویدادهایی بفرستید که می‌خواهید بر اساسش تفکیک کنید — مطمئن ترین راه؛
- یا به جای گروه بندی، یک مخاطب بسازید که شرطش روی همان بعد سفارشی است. عضویت در مخاطب کاربرمحور است: کافی است **یک** رویداد آن کاربر مقدار را داشته باشد تا خود کاربر در آن مخاطب بیفتد.

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

لازم نیست هر پارامتری از سایت بیاید. قواعد رویداد می‌توانند در لحظه دریافت، پارامتری را روی رویداد بنویسند یا مقدارش را عوض کنند؛ نتیجه در همان props می‌نشیند و دقیقا مثل بقیه قابل ثبت است. این راه معمول برای عادی سازی مقدارهای بی قاعده ای است که از چند قالب مختلف سایت می‌آیند — روشش در [قواعد رویداد](analytics/collect/event-rules) توضیح داده شده است.

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

### بعد سفارشی ساختم ولی ستونش خالی است. چرا؟

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

### ثبت یک تعریف، داده‌های قدیمی را می‌سازد؟

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

### نام نمایشی که گذاشتم چرا در «گزارش‌ها و کاوش» دیده نمی‌شود؟

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

### «نوع» و «نوع مقدار» چه فرقی دارند؟

آنچه واقعا تصمیم می‌گیرد، نوع مقدار است. «عدد» تعریف را به دو سنجه جمع و میانگین تبدیل می‌کند و «رشته» آن را به یک بعد. ستون «نوع» فقط برچسبی است که در جدول نگه داشته می‌شود.

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

- [قواعد ایجاد و اصلاح رویداد](https://docs.adpix.io/fa/analytics/collect/event-rules/)
- [کاوش‌ها](https://docs.adpix.io/fa/analytics/explore/explorations/)
- [رویدادهای کلیدی](https://docs.adpix.io/fa/analytics/collect/key-events/)

---

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