Skip to Content
مستندات متریکس همواره در حال بهبود است! 🚀 آخرین به‌روزرسانی‌ها را از اینجا دنبال کنید.
مستندات فنیRest APITracking Events

Tracking Events (ردیابی رویدادها)

ردیابی دقیق رویدادها برای درک رفتار کاربران، سنجش عملکرد کمپین‌ها، و تحلیل عمیق داده‌ها در متریکس بسیار حیاتی است. شما می‌توانید انواع مختلفی از رویدادها را از طریق API به متریکس ارسال کنید، از جمله Action Events (رویدادهای رفتاری)، Revenue Events (رویدادهای درآمدی)، و Business Events (رویدادهای بیزنس).

ساختار کلی ارسال رویدادها

برای ارسال رویدادها، شما باید یک درخواست POST به https://entry.metrix.ir/ ارسال کنید. ساختار کلی درخواست (شامل Header و Body) همانند بخش شروع به کار است.

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

{
  "type": "message type: action | revenue | businessEvent", // Specifies the message type
  "id": "request id", // Randomly generated unique ID, e.g., a UUID
  "time": 1677323951700 // Event occurrence timestamp in **milliseconds** (Long)
  // ... other fields will vary depending on 'type'
}
  • type: نوع پیام را مشخص می‌کند (action, revenue, businessEvent).
  • id: یک شناسه یکتا و تصادفی برای هر پیام (مثلاً UUID) که برای جلوگیری از ارسال داده‌های تکراری استفاده می‌شود.
  • time: زمان وقوع رویداد به صورت Unix Timestamp در میلی‌ثانیه و از نوع عددی (Long).

۱. ارسال Action Events (رویدادهای رفتاری)

Action Events برای ردیابی تعاملات و اقدامات مشخص کاربران در اپلیکیشن یا وب‌سایت شما استفاده می‌شوند. این رویدادها به شما در درک عادات و مسیرهای کاربری کمک می‌کنند.

  • پارامتر type را action تعریف کنید.

ساختار یک پیام action:

{
  "type": "action",
  "id": "random_generated_uuid",
  "time": 1677323951700,
  "name": "aewqd", // Example: 'aewqd' (a 5-character slug)
  "customName": "product_viewed", // Example: 'product_viewed'. Either 'name' OR 'customName' must be provided.
  "attributes": {
    "key1": "value1", // String
    "key2": 123, // Integer
    "key3": true, // Boolean
    "key4": 1.555, // Double/Float
    "key5": "2024-11-20T11:24:03.000Z", // Date (ISO 8601 String)
    "key6": { "nested_key": "nested_value" }, // JSON Object
    "key7": ["item1", "item2"] // JSON Array
  }
}

توضیح فیلدهای name و customName:

در متریکس، شما می‌توانید رویدادها را به دو روش نام‌گذاری کنید:

  • name (Slug):
    • این یک شناسه کوتاه و یکتا است که معمولاً شامل ۵ کاراکتر (مثل aewqd یا u37xw) است. این slug برای رویدادهایی استفاده می‌شود که از قبل در پنل متریکس شما تعریف و ثبت شده‌اند. استفاده از name به شما اطمینان می‌دهد که داده‌های رویداد شما به تعریف دقیق و از پیش تعیین شده در پنل متصل می‌شوند. اگر قصد دارید از ویژگی‌های پیشرفته‌تر متریکس برای رویدادها استفاده کنید که نیاز به تعریف در پنل دارند (مانند تنظیم قیف‌های تبدیل دقیق)، استفاده از name ضروری است.
  • customName:
    • این یک نام توصیفی و خواناتر برای رویداد شما است (مثال: product_viewed یا login_succeeded). customName انعطاف‌پذیری بیشتری به شما می‌دهد، چرا که اگر رویدادی با این customName از قبل در متریکس تعریف نشده باشد، به صورت خودکار ایجاد می‌شود. این گزینه برای شروع سریع یا زمانی که نیاز به ردیابی طیف وسیعی از رویدادها بدون تعریف قبلی در پنل دارید، بسیار مفید است. توصیه می‌شود برای customName از الگوی object_verb (مثال: course_published, user_registered) استفاده شود تا با Taxonomy و قواعد نام‌گذاری متریکس هم‌خوانی داشته باشد و تحلیل داده‌ها را آسان‌تر کند.

نکته مهم: یکی از فیلدهای name یا customName باید در هر پیام رویداد action، revenue یا businessEvent ارائه شود. شما نمی‌توانید هر دو را همزمان ارسال کنید.

توضیح فیلد attributes:

  • attributes: (اختیاری) یک شیء JSON که شامل جزئیات و زمینه‌های اضافی مربوط به رویداد است. این attributes می‌توانند از انواع داده‌ای مختلفی باشند:
    • String: "key": "value"
    • Integer: "key": 123
    • Boolean: "key": true
    • Double/Float: "key": 1.555
    • Date: تاریخ‌ها را با فرمت ISO 8601 به صورت رشته ارسال کنید (مثال: "2024-11-20T11:24:03.000Z") تا متریکس آن را به عنوان یک تاریخ شناسایی کند.
    • JSON Object: "key": { "nested_key": "nested_value" }
    • JSON Array: "key": ["item1", "item2"]

۲. ارسال Revenue Events (رویدادهای درآمدی)

Revenue Events برای ثبت تراکنش‌های مالی و درآمدزایی حاصل از کاربران شما استفاده می‌شوند. این رویدادها به شما در تحلیل ارزش طول عمر مشتری (LTV) و عملکرد مالی کمک می‌کنند.

  • پارامتر type را revenue تعریف کنید.
  • نکته مهم: Revenue Events از فیلد attributes پشتیبانی نمی‌کنند.

ساختار یک پیام revenue:

{
  "type": "revenue",
  "id": "random_generated_uuid",
  "time": 1677323951700,
  "name": "aewqd", // Example: 'aewqd'
  "customName": "order_completed", // Example: 'order_completed'. Either 'name' OR 'customName' must be provided.
  "revenue": 53.7, // Mandatory: The amount of revenue as a Double
  "currency": "IRR" // Mandatory: The currency code (e.g., "IRR", "USD", "EUR")
}

توضیح فیلدها:

  • name: (اختیاری) یک slug برای رویداد درآمدی.
  • customName: (اختیاری) یک نام توصیفی برای رویداد درآمدی.
  • نکته مهم: یکی از فیلدهای name یا customName باید ارائه شود.
  • revenue: (الزامی) مقدار درآمد حاصل از رویداد به صورت عددی (Double).
  • currency: (الزامی) کد واحد پول بر اساس استاندارد ISO 4217 (مثال: "IRR", "USD", "EUR").

۳. ارسال Business Events (رویدادهای بیزنس)

Business Events به شما امکان می‌دهند تا اتفاقات مهمی را که در سیستم‌های بک‌اند (Backend Systems) شما رخ می‌دهند و لزوماً از تعامل مستقیم کاربر با اپلیکیشن یا وب‌سایت ناشی نمی‌شوند، ردیابی کنید. این رویدادها می‌توانند تأثیر زیادی بر روی کاربران یا فرآیندهای کسب‌وکار شما داشته باشند.

  • پارامتر type را businessEvent تعریف کنید.
  • نکته مهم: برای businessEvent، فیلدهای customUserId یا metrixUserId در بدنه اصلی درخواست الزامی نیستند، زیرا این رویدادها ممکن است مستقیماً به یک کاربر خاص مرتبط نباشند.

ساختار یک پیام businessEvent:

{
  "type": "businessEvent",
  "id": "random_generated_uuid",
  "time": 1677323951700,
  "name": "aewqd", // Example: 'aewqd'
  "customName": "course_published", // Example: 'course_published'. Either 'name' OR 'customName' must be provided.
  "attributes": {
    "course_id": "C_WEBDEV201",
    "course_title": "Full-Stack Web Development",
    "instructor_name": "Dr. Sarah Johnson",
    "publish_date": "2024-06-17T18:00:00.000Z",
    "category": "Programming"
  }
}

توضیح فیلدها:

  • type: باید businessEvent باشد.
  • name: (اختیاری) یک slug برای رویداد بیزنس.
  • customName: (اختیاری) یک نام توصیفی برای رویداد بیزنس.
  • نکته مهم: یکی از فیلدهای name یا customName باید ارائه شود.
  • attributes: (اختیاری) یک شیء JSON شامل کلید-مقدار برای ارائه جزئیات بیشتر در مورد رویداد. همانند action events، این attributes نیز می‌توانند از انواع داده‌ای مختلفی باشند.

۴. نمونه دستور Curl برای انواع رویدادها

مثال زیر نحوه ارسال همزمان یک رویداد درآمدی و یک رویداد رفتاری را با استفاده از دستور curl نشان می‌دهد:

curl --location 'https://entry.metrix.ir/' \
--header 'content-type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'x-application-id: YOUR_APP_ID' \
--data-raw '{
    "customUserId": "john.doe@example.com",
    "metrixUserId": "7d5dbfbf-8ff9-44db-be79-953d2c1d7d6f",
    "messages": [
        {
            "type": "revenue",
            "id": "f0a4207b-4460-4abf-9fe9-de6b6263024d",
            "time": 1746273261969,
            "customName": "course_purchase_completed",
            "revenue": 199.99,
            "currency": "USD"
        },
        {
            "type": "action",
            "id": "acc89899-2018-4881-a5d8-bad3a9c31bbb",
            "time": 1677323951700,
            "customName": "video_lesson_watched",
            "attributes": {
                "lesson_id": "L2345",
                "course_name": "Advanced Python",
                "duration_minutes": 15
            }
        }
    ]
}'

نمونه دستور Curl برای Business Event:

این مثال نشان می‌دهد که چگونه یک businessEvent را بدون نیاز به شناسه‌های کاربر در بدنه اصلی درخواست ارسال کنید، زیرا این رویداد مستقیماً به یک کاربر خاص مرتبط نیست:

curl --location 'https://entry.metrix.ir/' \
--header 'content-type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'x-application-id: YOUR_APP_ID' \
--data-raw '{
    "messages": [
        {
            "type": "businessEvent",
            "id": "5527cea4-2fb2-4781-b716-c259681408ec",
            "time": 1733830178000,
            "customName": "course_published",
            "attributes": {
                "course_id": "C_WEBDEV201",
                "course_title": "Full-Stack Web Development",
                "instructor_name": "Dr. Sarah Johnson",
                "publish_date": "2024-06-17T18:00:00.000Z",
                "category": "Programming"
            }
        }
    ]
}'
Tracking UsersMessaging API