# رویدادهای تجارت الکترونیک

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

## دو مسیر جمع‌آوری، یک گزارش

تجارت الکترونیک در ادپیکس از دو جا تغذیه می‌شود و هر دو در یک گزارش می‌ریزند:

| موضوع | مرورگر | سرور |
| --- | --- | --- |
| دیدن محصول، افزودن به سبد، شروع تسویه | بله | لازم نیست |
| خریدی که درگاه پرداخت تایید کرده | ناقص و شکننده | بله |
| تمدید خودکار، فاکتور دوره‌ای، بازپرداخت | خیر | بله |
| سفارشی که اپراتور دستی ثبت می‌کند | خیر | بله |

دلیل این تقسیم کار ساده است: تا پیش از پرداخت، رویداد در همان صفحه‌ای می‌افتد که کاربر باز کرده و مرورگر بهترین جای دیدنش است. لحظه پرداخت اما بیرون از صفحه اتفاق می‌افتد — کاربر به درگاه می‌رود، ممکن است هرگز برنگردد، ممکن است مسدودکننده تبلیغات بیکن را بگیرد. حقیقت خرید در سرور شماست، پس از همان‌جا بفرستیدش.

## شکل فرمان در مرورگر

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

آرگومان دوم نام رویداد است و آرگومان سوم شیء تجارت الکترونیک. فرمان دو کار جدا می‌کند:

1. یک رویداد کامل با همان نام می‌سازد و `value`، `currency` و `transaction_id` را در پارامترهای آن می‌گذارد — پس گزارش رویدادها و درآمد رویدادهای کلیدی همان لحظه آن را می‌بینند.
2. آرایه `items` را در یک بافتار جداگانه کنار رویداد می‌فرستد. گیرنده آن بافتار را باز می‌کند و **برای هر قلم یک سطر جدا** می‌نویسد. گزارش محصولات و میانگین ارزش سفارش از همان سطرها ساخته می‌شوند.

`ecommerce` هم مثل `page` و `track` به رضایت دسته «آماری» گره خورده است: تا وقتی بازدیدکننده این دسته را نپذیرفته، فرمان چیزی نمی‌فرستد و بی‌صدا برمی‌گردد.

## نام‌های رویداد

همان مجموعه‌ای که GA4 به کار می‌برد پذیرفته می‌شود. نام را دقیقا با همین املا بفرستید؛ `Purchase` و `purchase` دو رویداد جدا شمرده می‌شوند.

| نام رویداد | چه چیزی آن را می‌خواند |
| --- | --- |
| `view_item` | گام اول «قیف تجارت» |
| `add_to_cart` | گام دوم قیف |
| `begin_checkout` | گام سوم قیف |
| `purchase` | درآمد، سفارش‌ها، میانگین ارزش سفارش، واحدها، محصولات برتر، گام چهارم قیف |
| `refund` | بازپرداخت‌ها و درآمد خالص |
| `view_item_list` | فقط گزارش رویدادها و کاوش |
| `remove_from_cart` | فقط گزارش رویدادها و کاوش |
| `add_payment_info` | فقط گزارش رویدادها و کاوش |

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

## فیلدهای هر قلم

| فیلد | نوع | نکته |
| --- | --- | --- |
| `item_id` | رشته | کلید محصول در گزارش محصولات برتر. سطرها با همین گروه می‌شوند. |
| `item_name` | رشته | نام نمایشی. اگر خالی باشد، جدول `item_id` را نشان می‌دهد. |
| `price` | عدد | قیمت واحد، در ارز همان رویداد. |
| `quantity` | عدد | اگر نفرستید یا صفر باشد، ۱ در نظر گرفته می‌شود. |
| `category` | رشته | ستون «دسته» در جدول محصولات. |
| `brand` | رشته | ذخیره می‌شود. |
| `variant` | رشته | ذخیره می‌شود. |
| `discount` | عدد | از درآمد همان قلم کم می‌شود. |

درآمد هر قلم برابر است با `price × quantity − discount`، و همین عدد است که در ستون درآمد جدول محصولات جمع می‌شود. حداکثر ۲۰۰ قلم در یک رویداد پذیرفته می‌شود.

فیلدهای `coupon`، `shipping`، `tax` و `affiliation` در سطح سفارش و `coupon` و `index` در سطح قلم پذیرفته می‌شوند و رویداد را رد نمی‌کنند، ولی امروز هیچ گزارشی آن‌ها را نمی‌خواند. اگر به یکی از آن‌ها در گزارش نیاز دارید، به جای اتکا به این فیلدها آن را به عنوان یک پارامتر معمولی رویداد بفرستید و از آن یک بُعد سفارشی بسازید.

## سه چیزی که بدون آن‌ها گزارش خالی می‌ماند

> **`transaction_id` تعیین می‌کند «سفارش» چند تاست**
>
> شمارش سفارش‌ها، میانگین ارزش سفارش و اقلام به ازای سفارش همگی با گروه‌بندی روی `transaction_id` محاسبه می‌شوند. اگر این فیلد را نفرستید، همه خریدهای بازه در یک گروه با شناسه خالی می‌افتند: تعداد سفارش ۱ می‌شود و میانگین ارزش سفارش برابر کل درآمد. عدد اشتباه نیست — بی‌معناست. در مسیر سرور همین نقش را `order_id` بازی می‌کند.

- **بدون `items` هیچ سطری نوشته نمی‌شود.** رویداد خریدی که آرایه اقلام ندارد در گزارش رویدادها و در درآمد رویدادهای کلیدی دیده می‌شود، ولی برای گزارش تجارت الکترونیک اصلا وجود ندارد. اگر ریز اقلام را ندارید، دست‌کم یک قلم با `item_id` سفارش و مبلغ کل بفرستید.
- **بدون `transaction_id` سفارش شمرده نمی‌شود** — بالا توضیح داده شد.
- **بدون `currency` مبلغ‌ها زیر ارز «نامشخص» جمع می‌شوند.** کد ارز را با سه حرف بزرگ لاتین بفرستید، مثل `IRR` یا `USD`. مسیر سرور کد نامعتبر را با خطای `422` رد می‌کند.

## خرید را از سرور بفرستید

مسیر سرور به سرور همان آرایه `items` را می‌پذیرد و `order_id` را به عنوان شناسه تراکنش به کار می‌برد:

```bash
curl -X POST https://api.adpix.io/api/v1/s2s/events \
  -H 'Authorization: Bearer sk_...' \
  -H 'X-Sov-Site: <property_id>' \
  -H 'Content-Type: application/json' \
  -d '{
    "event": "purchase",
    "event_id": "order_10482",
    "order_id": "10482",
    "email": "ali@example.com",
    "value": 4900000,
    "currency": "IRR",
    "items": [
      { "item_id": "SKU-42", "item_name": "Leather bag", "price": 2450000, "quantity": 2 }
    ]
  }'
```

سه چیز را این مسیر به شما می‌دهد که مرورگر نمی‌دهد:

- **ارسال دوباره سفارش تازه نمی‌سازد.** `event_id` را خودتان انتخاب می‌کنید و باید همیشه همان سفارش را نشان دهد. ارسال دوم با همان شناسه و همان بدنه، پاسخ اول را برمی‌گرداند و رویداد جدیدی نمی‌نویسد.
- **انتساب سفارش منجمد می‌شود.** کانال و کمپینی که خرید را ساخته یک بار روی سفارش نوشته می‌شود و رفتار بعدی مشتری آن را بازنویسی نمی‌کند.
- **مسدودکننده تبلیغات و ترک صفحه بی‌اثرند.**

جزئیات کلید سرور، سرصفحه‌ها و خطاها در [ردیابی سمت سرور](analytics/collect/server-side-tracking) آمده است.

> **یک سفارش را از دو مسیر نفرستید**
>
> اگر همان خرید هم از مرورگر و هم از سرور برود، دو سطر مستقل ثبت می‌شود و درآمد دو برابر می‌شود. این دو مسیر شناسه‌های متفاوتی دارند و ادپیکس عمدا آن‌ها را روی هم نمی‌اندازد. یکی را انتخاب کنید — و اگر سرور را انتخاب کردید، مطمئن شوید قاعده «ساخت رویداد» روی صفحه پرداخت موفق هم هم‌زمان یک خرید دیگر نمی‌سازد.

## تکرار خرید در مرورگر

اگر ناچارید خرید را از مرورگر بفرستید، `transaction_id` را حتما بگذارید. رویدادی که نامش دقیقا `purchase` است و شناسه تراکنش دارد، شناسه‌ای ثابت و برگرفته از همان تراکنش می‌گیرد؛ پس بارگذاری دوباره صفحه «پرداخت موفق»، بازگشت به عقب و ارسال دوباره تراکر همگی روی هم می‌افتند و یک خرید شمرده می‌شوند.

این حفاظ فقط برای نام `purchase` کار می‌کند. اگر رویداد خریدتان نام دیگری دارد — چون قاعده رویداد آن را ساخته یا نامش را عوض کرده — روش دیگری لازم است که در [قواعد ایجاد و اصلاح رویداد](analytics/collect/event-rules) توضیح داده شده.

## ارز

مبلغ‌ها در همان ارزی که فرستاده‌اید ذخیره می‌شوند و هیچ تبدیلی انجام نمی‌شود. گزارش تجارت الکترونیک هم مبلغ‌ها را با علامت `$` نمایش می‌دهد؛ آن علامت واحد پول شما را عوض نمی‌کند و عدد کنارش همان مقدار در ارز خودتان است.

نتیجه عملی: یک دارایی که هم‌زمان با دو ارز می‌فروشد، جمع درآمدش ریال و دلار را روی هم می‌ریزد. برای هر ارز یک دارایی جدا بسازید.

## چه چیزی کجا دیده می‌شود

| جا | از کجا می‌آید |
| --- | --- |
| درآمد، سفارش‌ها، میانگین ارزش سفارش، واحدها | سطرهای قلم رویدادهای `purchase`، گروه‌شده بر `transaction_id` |
| بازپرداخت‌ها و درآمد خالص | همان، برای `refund` |
| محصولات برتر | جمع درآمد قلم به تفکیک `item_id` |
| قیف تجارت | کاربران یکتای چهار رویداد قیف در `events_local` |
| درآمد رویدادهای کلیدی | پارامتر `value` روی خود رویداد، نه سطرهای قلم |

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

خواندن خود گزارش در [گزارش تجارت الکترونیک](analytics/reports/ecommerce) توضیح داده شده است.

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

### خرید را از مرورگر بفرستم یا از سرور؟

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

### چرا گزارش تجارت الکترونیک خالی است در حالی که رویداد purchase در گزارش رویدادها دیده می‌شود؟

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

### چرا همه خریدها یک سفارش شمرده می‌شوند؟

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

### ادپیکس ارزها را به هم تبدیل می‌کند؟

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

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

- [مرجع دستورهای تراکر](https://docs.adpix.io/fa/analytics/collect/tracker-reference/)
- [ردیابی سمت سرور](https://docs.adpix.io/fa/analytics/collect/server-side-tracking/)
- [گزارش تجارت الکترونیک](https://docs.adpix.io/fa/analytics/reports/ecommerce/)
- [رویدادهای کلیدی](https://docs.adpix.io/fa/analytics/collect/key-events/)

---

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