فرهنگ‌نامهٔ رویدادها برای هر نوع کسب‌وکار

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

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

#چطور این فهرست را بخوانید

ستون «وضعیت» در همه جدول‌ها دو مقدار دارد و فرقشان مهم است:

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

یک تصور غلط رایج را همین‌جا ببندیم: «استاندارد» به‌معنی «در فهرست انتخاب رویداد هست» نیست. سگمنت‌ساز تا بارگذاری اسکیمای واقعی تنانت، ده نام ثابت را نشان می‌دهد (order_completed، product_viewed، product_added_to_cart، checkout_started، order_refunded، searched، app_opened، signed_up، message_opened، message_clicked) و بعد از آن فهرست را از رویدادهای واقعی خودتان می‌سازد. سناریوساز هم فقط هشت نام را برچسب می‌زند. نام استانداردی که هرگز نفرستاده‌اید، در هیچ فهرستی ظاهر نمی‌شود.

سه چیزی که باید در فهرست «استاندارد» جدا نگه دارید:

فقط سه نام واقعا رفتار دارند. order_completed مبلغ را به total_revenue پرونده اضافه می‌کند، order_count را یکی بالا می‌برد و last_order_at را جلو می‌برد. order_refunded و order_cancelled قدرمطلق مبلغ را کم می‌کنند و شمارش سفارش را یکی پایین می‌آورند، هر دو با کف صفر. بقیه نام‌های استاندارد هیچ رفتاری ندارند.

استاندارد یعنی شناخته‌شده، نه خودکار. هیچ رویدادی خودبه‌خود فرستاده نمی‌شود. نام‌های app_installed و app_opened و app_updated و app_removed و session_started و session_ended در کد به‌عنوان «رویدادهای چرخه عمر که SDKها خودکار می‌فرستند» اعلام شده‌اند، ولی هیچ SDKای آن‌ها را نمی‌فرستد. اگر می‌خواهیدشان، خودتان بفرستید.

**نام‌های message_* را خودتان نفرستید.** آن‌ها را ورکرهای خود سگمنتیک می‌نویسند و در بخش رویدادهایی که سگمنتیک می‌نویسد فهرست شده‌اند.

#نام‌هایی که پلتفرم می‌شناسد

#ویژگی‌هایی که روی هر رویداد می‌گذارید

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

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

شناسه‌ها را رشته بفرستید. "order_id": "A-100294" نه "order_id": 100294. عدد به‌شکل متن هم ذخیره می‌شود، ولی رشته از اول با سیستم خودتان join می‌شود.

عدد را عدد بفرستید و بولی را بولی. "quantity": 3 نه "quantity": "3". رشته عددشکل هرگز به نقشه عددی نمی‌رود و فیلتر «بیشتر از» روی آن هیچ‌وقت جواب نمی‌دهد.

برای مقدار ویژگی‌ها یک زبان انتخاب کنید و بمانید. مقدارها همان‌طور که فرستاده می‌شوند ذخیره می‌شوند (فقط با نرمال‌سازی فارسی). gold و طلایی دو مقدار جدا هستند و در یک سگمنت نمی‌افتند.

revenue و total و value و جفت price با quantity را فقط روی رویداد پولی بگذارید. درآمد از هر رویدادی که این کلیدها را داشته باشد استخراج می‌شود و به ارزش طول عمر آن کاربر اضافه می‌شود. برای مبلغی که پول واقعی نیست از نام دیگری استفاده کنید. در جدول‌های زیر عمدا unit_price و cart_total و amount آمده است، چون هیچ‌کدام رزرو نیستند.

#فروشگاه اینترنتی

قیف پیش‌فرضی که با همین فهرست کار می‌کند: product_viewed بعد product_added_to_cart بعد checkout_started بعد order_completed. سگمنت «سبد رهاشده» هم همان است: کسی که در هفت روز گذشته product_added_to_cart داشته و order_completed نداشته.

curl -X POST https://in.segmentic.net/v1/track \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer wk_seg_..." \
  -d '{
    "message_id": "b3d51f28-4c6a-4b1e-9d70-2f8a3c5e7d10",
    "user_id": "u_88123",
    "event": "order_completed",
    "timestamp": "2026-08-07T10:02:41.000Z",
    "properties": {
      "order_id": "A-100294",
      "revenue": 2450000,
      "currency": "IRR",
      "item_count": 3,
      "shipping_cost": 49000,
      "discount": 150000,
      "coupon_code": "NOWRUZ",
      "payment_method": "gateway"
    }
  }'

{"status":"ok","accepted":1}

#سوپراپ و درخواست خودرو

اینجا revenue روی wallet_topped_up و ride_completed عمدی است. کد صریحا این حالت را در نظر گرفته: درآمد از هر رویدادی جمع می‌شود، نه فقط سفارش، چون مشتری ممکن است اشتراک یا شارژ را رویداد خودش بداند. اما توجه کنید که فقط order_completed شمارنده order_count را بالا می‌برد، پس «تعداد سفارش» در پرونده، سفرها را نمی‌شمارد.

ویژگی service را روی هر رویداد سوپراپ بگذارید. بدون آن نمی‌توانید بپرسید «کسی که تاکسی گرفته ولی هرگز غذا سفارش نداده».

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

اینجا amount عمدا به‌جای revenue آمده. مبلغ انتقال وجه، پول شما نیست: اگر آن را revenue بنامید، total_revenue هر کاربر برابر گردش حسابش می‌شود و سگمنت «مشتری پرارزش» عملا «کسی که زیاد پول جابه‌جا می‌کند» می‌شود. روی payment_completed هر دو آمده است، چون هر دو عدد را می‌خواهید: revenue کارمزدی که مال شماست و amount مبلغی که کاربر پرداخته.

#سفر و رزرو

days_to_departure روی خود رویداد ذخیره می‌شود، نه محاسبه در زمان پرس‌وجو. تفاوتش این است که چند ماه بعد هنوز می‌توانید بپرسید «چند نفر در فاصله کمتر از سه روز مانده به پرواز رزرو کردند»، در حالی که اگر فقط depart_date را داشته باشید باید در زمان گزارش دو رشته را تفریق کنید و رشته تاریخ در نقشه ویژگی‌ها متن است.

#آموزش

course_abandoned را باید سیستم خودتان تصمیم بگیرد و از سرور بفرستد؛ پلتفرم رویدادی از روی نبود رویداد نمی‌سازد. اگر نمی‌خواهید آن را بسازید، همان کار را با یک سناریو انجام دهید که بعد از lesson_completed منتظر می‌ماند.

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

#اشتراک محتوا

نکته‌ای که در اشتراک همیشه غافلگیر می‌کند: subscription_cancelled هیچ پولی را برنمی‌گرداند. فقط order_refunded و order_cancelled از total_revenue کم می‌کنند. لغو اشتراک یعنی تمدید بعدی نمی‌آید، نه اینکه پول ماه‌های قبل پس داده شود، و پرونده هم همین را نشان می‌دهد.

#ویژگی‌های پرونده که با identify می‌فرستید

این‌ها کلیدهایی هستند که کد به آن‌ها معنی می‌دهد و به ستون واقعی پرونده تبدیل می‌شوند:

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

name و created_at هم به‌عنوان کلید رزرو اعلام شده‌اند، ولی به ستون تبدیل نمی‌شوند و ویژگی معمولی می‌مانند. اگر نام کامل را می‌خواهید، first_name و last_name را بفرستید.

هر کلید دیگری ویژگی آزاد است و در دو نقشه traits و traits_num می‌نشیند. برای فروشگاه معمولا اینها را هم می‌فرستند: loyalty_tier رشته، loyalty_points عدد، is_wholesale بولی، preferred_category رشته.

curl -X POST https://in.segmentic.net/v1/identify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer wk_seg_..." \
  -d '{
    "message_id": "c74a9e01-5f22-4a8b-8c31-7ee2d9b40a55",
    "user_id": "u_88123",
    "traits": {
      "phone": "09123456789",
      "email": "Hamid@Example.com",
      "first_name": "حمید",
      "city": "تهران",
      "birthday": "1993-04-11",
      "sms_opt_in": true,
      "loyalty_tier": "gold",
      "loyalty_points": 1840
    }
  }'

{"status":"ok","accepted":1}

نتیجه روی پرونده: phone به +989123456789 تبدیل می‌شود و phone_operator برابر mci نوشته می‌شود، email به hamid@example.com تبدیل می‌شود، loyalty_points هم در نقشه متنی و هم در نقشه عددی می‌نشیند تا فیلتر «بیشتر از» کار کند، و loyalty_tier فقط متنی می‌ماند.

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

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

message_id این رویدادها ترکیب شناسه درخواست و نام رویداد است، تا ارسال و شکست یک پیام در حذف تکراری به هم نخورند.

نام‌های message_delivered و message_bounced و unsubscribed به‌عنوان ثابت اعلام شده‌اند و هیچ جای دیگر بک‌اند از آن‌ها استفاده نمی‌کند: نه ورکری آن‌ها را می‌نویسد و نه چیزی آن‌ها را می‌خواند، پس گزارشی که روی message_delivered بسازید خالی برمی‌گردد. با این حال خود پنل رویداد تحویل می‌خواهد. قالب داشبورد «عملکرد پیام‌رسانی» و متریک‌های پایه «نرخ تحویل پیام» و «نرخ بازشدن پیام» و «نرخ کلیک پیام» هرکدام به یک رویداد تحویل نیاز دارند که از اسکیمای رویداد خودتان به آن‌ها وصل شود، و تا اسمی ندهید فعال‌سازی جلو نمی‌رود، پس اگر خودتان رویداد تحویل نفرستید، آن داشبورد و آن سه متریک هرگز ساخته نمی‌شوند.

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

ورکر انتساب دقیقا چهار نام را می‌شناسد، message_sent و message_withheld و message_opened و message_clicked، و هر رویداد دیگری را که به دستش برسد نادیده می‌گیرد. message_clicked را هم ورکر نمی‌نویسد: SDK وب آن را وقتی می‌فرستد که بازدیدکننده روی لینکی با sg_mid وارد سایت شود، یک بار، تا وقتی شناسه پیام دیگری جایش را بگیرد. مقایسه با همان یک شناسه داخل حافظه است نه با تاریخچه‌ای از شناسه‌ها، پس بازدیدکننده‌ای که روی یک پیام بیاید، بعد روی پیام دوم، و بعد دوباره روی همان پیام اول، کلیک پیام اول را دو بار گزارش می‌کند.

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