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

Tracking Users (ردیابی کاربران)

با استفاده از این API، می‌توانید خصیصه‌های کاربران (User Attributes) خود را برای متریکس ارسال کنید. این خصیصه‌ها به شما کمک می‌کنند تا کاربران خود را بخش‌بندی (segment) کرده و پیام‌های شخصی‌سازی شده و هدفمند برای هر گروه ارسال کنید، که این امر برای کمپین‌های Automation بسیار حیاتی است.

متریکس به طور پیش‌فرض، هم از خصیصه‌های استاندارد (مانند نام، ایمیل) و هم از خصیصه‌های سفارشی (Custom Attributes) پشتیبانی می‌کند.

ساختار ارسال خصیصه‌های کاربران

برای ارسال یا به‌روزرسانی خصیصه‌های کاربران، باید یک پیام از نوع user را در آرایه messages درخواست اصلی خود قرار دهید.

ساختار کلی یک پیام user:

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

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

  • فیلدهای اجباری (type, id, time):

    • type: این فیلد الزامی است و برای ثبت خصیصه‌های کاربر باید حتماً user باشد.
    • id: این فیلد الزامی است و یک شناسه یکتا و تصادفی (مثلاً UUID) برای هر پیام است که برای جلوگیری از ارسال پیام‌های تکراری استفاده می‌شود.
    • time: این فیلد الزامی است و زمان رخداد (مثلاً زمان به‌روزرسانی پروفایل کاربر) را به صورت Unix Timestamp در میلی‌ثانیه و از نوع عددی (Long) مشخص می‌کند.

  • فیلدهای استاندارد (firstName, lastName, phoneNumber, email, country, city, region, locality, gender, birthday):

    • این فیلدها اختیاری هستند و برای ذخیره اطلاعات عمومی و رایج کاربران استفاده می‌شوند.
    • فیلد birthday باید به صورت Unix Timestamp در میلی‌ثانیه و از نوع عددی (Long) ارسال شود.

  • فیلدهای هش شده (hashedPhoneNumber, hashedEmail):

    • این فیلدها اختیاری هستند و برای ارسال نسخه هش شده شماره تلفن یا ایمیل کاربر استفاده می‌شوند.
    • نکته مهم: استفاده از فیلدهای هش شده زمانی کاربرد دارد که به دلایل حریم خصوصی یا سیاست‌های داده، قادر به نگهداری یا ارسال مستقیم شماره تلفن یا ایمیل کاربر نیستید. در این صورت، متریکس نمی‌تواند به طور مستقیم از طریق این مقادیر هش شده برای ارسال ارتباطاتی مانند ایمیل یا SMS استفاده کند.

  • customAttributes:

    • این فیلد اختیاری است و برای ارسال خصیصه‌های سفارشی (Custom Attributes) که مختص کسب‌وکار شما هستند، استفاده می‌شود.
    • customAttributes یک شیء JSON است که به شما امکان می‌دهد کلید-مقادیر دلخواه را تعریف کنید.
    • متریکس از انواع داده‌ای مختلف (String, Integer, Double/Float, Boolean, JSON Object) برای customAttributes پشتیبانی می‌کند.
    • برای اطمینان از اینکه یک customAttribute به عنوان تاریخ شناسایی شود، مقدار آن را با فرمت ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) ارسال کنید.

نکات مهم در ردیابی کاربران

  • اولین ثبت کاربر: برای اینکه سایر رویدادهای مربوط به یک کاربر در متریکس به درستی ردیابی شوند، لازم است حداقل یک بار کاربر ثبت شده باشد. این ثبت می‌تواند با ارسال یک پیام user “خالی” (فقط شامل فیلدهای اجباری type، id و time در کنار customUserId در بدنه اصلی درخواست) انجام شود.
  • customUserId برای Automation: در کاربردهای Automation، مقداردهی customUserId الزامی است. این شناسه، متریکس را قادر می‌سازد تا ارتباطات و سفرهای مشتری را به صورت شخصی‌سازی شده مدیریت کند.
  • همگام‌سازی customUserId با SDK: در صورت استفاده همزمان از Metrix SDK در اپلیکیشن یا وب‌سایت خود، اطمینان حاصل کنید که مقدار customUserId برای هر کاربر در هر دو سیستم (API و SDK) یکسان باشد تا داده‌های کاربر به درستی همگام‌سازی و تجمیع شوند.

نمونه دستور Curl برای ارسال خصیصه‌های کاربران

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

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"
        }
      }
    ]
  }'
Getting StartedTracking Events