Tracking Users

By using this API, you can send your User Attributes to Metrix. These attributes help you segment your users and send personalized, targeted messages to each group, which is crucial for Automation campaigns.

Metrix supports both standard attributes (like name and email) and custom attributes by default.

User Attributes Submission Structure

To send or update user attributes, you must place a message of type user in the messages array of your main request.

General structure of a user message:

{
  "type": "user", // type must be "user" for user profile updates
  "id": "request id", // random generated unique ID, e.g., a UUID
  "time": 1678886400000, // Unix timestamp in **milliseconds** (Long)
  "firstName": "User first name", // Optional: User's first name
  "lastName": "User last name", // Optional: User's last name
  "phoneNumber": "09121122333", // Optional: User's phone number
  "hashedPhoneNumber": "hashed value of phone number", // Optional: Hashed version of phone number
  "email": "User email address", // Optional: User's email address
  "hashedEmail": "hashed value of email", // Optional: Hashed version of email
  "country": "User country", // Optional: User's country
  "city": "User city", // Optional: User's city
  "region": "User region", // Optional: User's region
  "locality": "User locality", // Optional: User's locality
  "gender": "Male/Female/Other", // Optional: User's gender
  "birthday": 733908600000, // Optional: User's birthday as Unix timestamp in **milliseconds** (Long)
  "customAttributes": {
    // Optional: Custom attributes for the user
    "your_user_custom_attribute_key": "custom_attribute_value", // String value
    "integer_attribute": 123, // Integer value
    "double_attribute": 1.555, // Double/Float value
    "json_attribute": {
      // JSON object value
      "key": "value",
      "array": ["value1", "value2"]
    },
    "date_attribute": "2024-11-20T11:24:03.000Z" // Use ISO 8601 for date attributes
  }
}

Field explanations:

• Mandatory fields (type, id, time):

  • type: This field is mandatory and must be user to register user attributes.
  • id: This field is mandatory and is a random, unique ID (e.g., UUID) for each message, used to prevent duplicate message submissions.
  • time: This field is mandatory and specifies the time the event occurred (e.g., the time the user profile was updated) as a Unix Timestamp in milliseconds of type Long.

• Standard fields (firstName, lastName, phoneNumber, email, country, city, region, locality, gender, birthday):

  • These fields are optional and are used to store common, general user information.
  • The birthday field must be sent as a Unix Timestamp in milliseconds of type Long.

• Hashed fields (hashedPhoneNumber, hashedEmail):

  • These fields are optional and are used to send the hashed version of a user’s phone number or email.
  • Important Note: Using hashed fields is applicable when, due to privacy concerns or data policies, you are unable to store or send the user’s direct phone number or email. In such a case, Metrix cannot directly use these hashed values to send communications like email or SMS.

• customAttributes:

  • This field is optional and is used to send custom attributes specific to your business.
  • customAttributes is a JSON object that allows you to define arbitrary key-value pairs.
  • Metrix supports various data types for customAttributes, including String, Integer, Double/Float, Boolean, and JSON Object.
  • To ensure that a customAttribute is identified as a date, send its value in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ).

Important Notes on User Tracking

• First User Registration: For other events related to a user to be tracked correctly in Metrix, the user must be registered at least once. This registration can be done by sending an “empty” user message (containing only the mandatory type, id, and time fields, along with customUserId in the main request body).
• customUserId for Automation: For Automation purposes, providing customUserId is mandatory. This identifier enables Metrix to manage personalized communications and user journeys.
• customUserId Synchronization with SDK: If you are simultaneously using the Metrix SDK in your application or website, ensure that the customUserId value is identical for each user across both systems (API and SDK) so that user data is correctly synchronized and aggregated.

Sample Curl Command for Sending User Attributes

The following example shows how to send a user profile update using the curl command:

curl -X POST 'https://entry.metrix.ir/' \
  -H 'X-Application-Id: APP_ID' \
  -H 'X-API-Key: API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "customUserId": "r.akbari",
    "messages": [
      {
        "type": "user",
        "id": "18788701-c330-4000-853d-fe8998511280",
        "time": 1680000000000, // Example: March 28, 2023, 1:20:00 PM UTC (Unix Timestamp in Milliseconds)
        "firstName": "Reza",
        "lastName": "Akbari",
        "phoneNumber": "09121122333",
        "email": "reza@gmail.com",
        "country": "Iran",
        "city": "Tehran",
        "region": "Vanak",
        "gender": "Male",
        "birthday": 733908600000, // Example: April 3, 1993, 1:30:00 AM UTC (Unix Timestamp in Milliseconds)
        "customAttributes": {
          "loyalty_level": "vip",
          "job": "developer",
          "last_login_date": "2024-06-17T14:30:00.000Z"
        }
      }
    ]
  }'