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