Skip to Content
AI Powered Docs! 🤖 These docs are translated with AI, so keep an eye out for minor quirks. We're always improving!
TechnicalAPITracking Events

Tracking Events

Accurate event tracking is crucial for understanding user behavior, measuring campaign performance, and gaining deep insights from data in Metrix. You can send various types of events to Metrix via the API, including Action Events, Revenue Events, and Business Events.

Overall Event Submission Structure

To send events, you must send a POST request to https://entry.metrix.ir/. The overall request structure (including Header and Body) is the same as in the Getting Started  section.

Inside the messages array in the request body, you can place one or more messages of different event types. Each message must have the following common fields:

{
  "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: Specifies the message type (action, revenue, businessEvent).
  • id: A unique and random ID for each message (e.g., a UUID), used to prevent duplicate data submissions.
  • time: The time the event occurred as a Unix Timestamp in milliseconds of type Long.

1. Sending Action Events

Action Events are used to track specific user interactions and actions on your application or website. These events help you understand user habits and journeys.

  • Define the type parameter as action.

Structure of an action message:

{
  "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
  }
}

Explanation of name and customName fields:

In Metrix, you can name events in two ways:

  • name (Slug):
    • This is a short and unique identifier, typically consisting of 5 characters (e.g., aewqd or u37xw). This slug is used for events that have been predefined and registered in your Metrix dashboard. Using name ensures that your event data is connected to a precise, pre-established definition in the dashboard. If you plan to use advanced Metrix features for events that require dashboard definitions (such as setting up accurate conversion funnels), using name is essential.
  • customName:
    • This is a more descriptive and readable name for your event (e.g., product_viewed or login_succeeded). customName gives you more flexibility because if an event with this customName has not been predefined in Metrix, it will be created automatically. This option is very useful for getting started quickly or when you need to track a wide range of events without prior dashboard definition. We recommend using the object_verb pattern for customName (e.g., course_published, user_registered) to align with Metrix’s Taxonomy and make data analysis easier.

Important Note: One of the name or customName fields must be provided in every action, revenue, or businessEvent message. You cannot send both at the same time.

Explanation of the attributes field:

  • attributes: (Optional) A JSON object that includes additional details and context related to the event. These attributes can be of various data types:
    • String: "key": "value"
    • Integer: "key": 123
    • Boolean: "key": true
    • Double/Float: "key": 1.555
    • Date: Send dates as a string in ISO 8601 format (e.g., "2024-11-20T11:24:03.000Z") so that Metrix recognizes it as a date.
    • JSON Object: "key": { "nested_key": "nested_value" }
    • JSON Array: "key": ["item1", "item2"]

2. Sending Revenue Events

Revenue Events are used to record financial transactions and revenue generated from your users. These events help you analyze customer lifetime value (LTV) and financial performance.

  • Define the type parameter as revenue.
  • Important Note: Revenue Events do not support the attributes field.

Structure of a revenue message:

{
  "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")
}

Field explanations:

  • name: (Optional) A slug for the revenue event.
  • customName: (Optional) A descriptive name for the revenue event.
  • Important Note: One of the name or customName fields must be provided.
  • revenue: (Mandatory) The amount of revenue from the event as a Double.
  • currency: (Mandatory) The currency code based on the ISO 4217 standard (e.g., "IRR", "USD", "EUR").

3. Sending Business Events

Business Events allow you to track important occurrences that happen in your Backend Systems and are not necessarily caused by direct user interaction with the application or website. These events can have a significant impact on your users or business processes.

  • Define the type parameter as businessEvent.
  • Important Note: For businessEvent, the customUserId or metrixUserId fields in the main request body are not mandatory, as these events may not be directly tied to a specific user.

Structure of a businessEvent message:

{
  "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"
  }
}

Field explanations:

  • type: Must be businessEvent.
  • name: (Optional) A slug for the business event.
  • customName: (Optional) A descriptive name for the business event.
  • Important Note: One of the name or customName fields must be provided.
  • attributes: (Optional) A JSON object containing key-value pairs to provide more details about the event. Like action events, these attributes can be of various data types.

4. Sample Curl Commands for Various Events

The following example shows how to send both a revenue event and an action event in a single curl command:

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
            }
        }
    ]
}'

Sample Curl Command for a Business Event:

This example shows how to send a businessEvent without the need for user identifiers in the main request body, as this event is not directly tied to a specific user:

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"
            }
        }
    ]
}'
Last updated on
Tracking UsersMessaging API