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

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

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

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

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

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 دو رویداد جدا شمرده می‌شوند.

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

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

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

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

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

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

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

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

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 را خودتان انتخاب می‌کنید و باید همیشه همان سفارش را نشان دهد. ارسال دوم با همان شناسه و همان بدنه، پاسخ اول را برمی‌گرداند و رویداد جدیدی نمی‌نویسد.
• انتساب سفارش منجمد می‌شود. کانال و کمپینی که خرید را ساخته یک بار روی سفارش نوشته می‌شود و رفتار بعدی مشتری آن را بازنویسی نمی‌کند.
• مسدودکننده تبلیغات و ترک صفحه بی‌اثرند.

جزئیات کلید سرور، سرصفحه‌ها و خطاها در ردیابی سمت سرور آمده است.

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

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

این حفاظ فقط برای نام purchase کار می‌کند. اگر رویداد خریدتان نام دیگری دارد — چون قاعده رویداد آن را ساخته یا نامش را عوض کرده — روش دیگری لازم است که در قواعد ایجاد و اصلاح رویداد توضیح داده شده.

ارز#

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

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

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

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

خواندن خود گزارش در گزارش تجارت الکترونیک توضیح داده شده است.

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

مطالب مرتبط#