REST API - شروع به کار (Getting Started)

این راهنما به شما کمک می‌کند تا اولین درخواست Server-to-Server (S2S) خود را به متریکس ارسال کنید. با استفاده از Metrix REST API، می‌توانید داده‌های مربوط به کاربران و رفتارهای آن‌ها را مستقیماً از سرور خود به متریکس بفرستید. این یکپارچه‌سازی به شما امکان می‌دهد تا از داشبوردهای تحلیلی متریکس، قابلیت‌های بخش‌بندی کاربران، و ابزارهای قدرتمند Marketing Automation بهره‌مند شوید.

۱. دریافت کلیدهای امنیتی (Security Keys)

برای احراز هویت و ارسال موفقیت‌آمیز داده‌ها به متریکس، به دو کلید امنیتی نیاز دارید:

• APP_ID (شناسه اپلیکیشن): این شناسه، اپلیکیشن شما را در متریکس شناسایی می‌کند و در پیاده‌سازی SDK نیز کاربرد دارد.
• API_Key (کلید API): این کلید مخصوص یکپارچه‌سازی‌های Server-to-Server (S2S) شماست و یک کلید محرمانه برای احراز هویت درخواست‌های ارسالی از سرور شما به متریکس است.

نحوه دسترسی به کلیدها: کلیدهای APP_ID و API_Key شما در داشبورد متریکس، در بخش تنظیمات اپلیکیشن قابل دسترسی هستند.

نکته مهم:

• کلیدها برای هر اپلیکیشن منحصربه‌فرد هستند. مطمئن شوید که کلیدهای مربوط به اپلیکیشن صحیح خود را استفاده می‌کنید.
• حفظ امنیت API_Key حیاتی است. این یک کلید نوع سرور است، و نباید در کد سمت کلاینت (مانند جاوا اسکریپت مرورگر یا کلاینت موبایل) استفاده یا افشا شود. این کلید باید فقط در سمت سرور شما نگهداری و استفاده شود.

نحوه درج کلیدها در هدر درخواست: پس از دریافت این کلیدها، باید آن‌ها را در Header هر درخواست خود به متریکس وارد کنید:

'X-Application-Id': '{YOUR APP_ID FROM METRIX DASHBOARD}'
'X-API-Key': '{YOUR API_Key FROM METRIX DASHBOARD}'

۲. فرمت ارسال داده‌ها و Endpoint

برای ارسال داده به متریکس، باید یک درخواست POST به آدرس زیر ارسال کنید:

https://entry.metrix.ir/

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

درخواست شما باید شامل هدرها و بدنه‌ای با فرمت JSON باشد:

• Header (هدرها):

  • X-Application-Id: APP_ID شما
  • X-API-Key: API_Key شما
  • Content-Type: application/json

• Body (بدنه درخواست - JSON): بدنه درخواست شامل فیلدهای اصلی برای شناسایی کاربر و لیستی از پیام‌ها است:

{
  "customUserId": "username | email | phone | any unique user id", // e.g.: '+98912XXXXXXX'
  "metrixUserId": "<get id from sdk>", // device id obtained from sdk for attribution purposes
  "messages": [
    // Different message types (user, action, revenue, businessEvent) will be explained below
  ]
}

توضیح فیلدهای اصلی بدنه درخواست:

• customUserId:

  • هدف: یک شناسه منحصر به فرد برای معرفی کاربر به متریکس. این شناسه به متریکس کمک می‌کند تا پروفایل کاربری یکتا را شناسایی و رفتار کاربر را در طول زمان و در دستگاه‌های مختلف ردیابی کند.
  • مثال‌ها: می‌تواند نام کاربری، ایمیل، شماره تلفن، یا هر شناسه داخلی یکتای دیگری از سیستم شما باشد.
  • الزام: برای کاربردهای مربوط به Automation و ایجاد سفرهای مشتری (User Journeys) اجباری است. اگر همزمان از SDK استفاده می‌کنید، اطمینان حاصل کنید که مقدار یکسانی برای هر کاربر تنظیم می‌شود.

• metrixUserId:

  • هدف: شناسه‌ای که متریکس به دستگاه کاربر اختصاص داده است (Device ID).
  • نحوه دریافت: این شناسه از طریق متریکس SDK در اپلیکیشن موبایل یا وب‌سایت کاربر قابل دریافت است. برای جزئیات بیشتر به مستندات SDK مربوطه مراجعه کنید.
  • الزام: برای کاربردهای مربوط به Attribution و اتصال رویدادها به منبع نصب، اجباری است. در صورت عدم ارسال این شناسه، رویدادها به سورس نصب متصل نخواهند شد.

• messages:

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

{
  "type": "message type: user | action | revenue | businessEvent",
  "id": "request id", // random generated unique ID, e.g., a UUID. Example: "e9f0c1d2-a3b4-5c6d-e7f8-9a0b1c2d3e4f"
  "time": "event timestamp" // Unix timestamp in **seconds** as a **String**
  // ... other fields will vary depending on 'type'
}

توضیح فیلدهای مشترک هر پیام:

• type:

  • این فیلد نوع پیامی را که برای متریکس ارسال می‌کنید، مشخص می‌کند. مقادیر مجاز شامل user (برای به‌روزرسانی پروفایل کاربر)، action (برای ردیابی رفتار کاربر)، revenue (برای ردیابی درآمد)، یا businessEvent (برای ردیابی رویدادهای سیستمی/بیزنسی) هستند. سایر فیلدهای هر پیام بسته به این type متفاوت خواهند بود.

• id:

  • این فیلد برای تشخیص و جلوگیری از ارسال پیام‌های تکراری استفاده می‌شود. برای هر پیام در لیست messages، باید یک شناسه تصادفی و یکتا در لحظه تولید کنید (مثلاً با استفاده از UUID). فرمت این شناسه باید متنی (String) باشد و محدودیت دیگری ندارد.

• time:

  • این فیلد نشان‌دهنده زمان وقوع رخداد است. فرمت آن باید Unix Timestamp در ثانیه و به صورت رشته (String) باشد.
  • مثال: "1733830178" (برای دهم دسامبر ۲۰۲۴، ساعت ۲۲:۰۹:۳۸ به وقت جهانی - UTC)

۳. ملاحظات مهم در مورد شناسه‌های کاربر

• حداقل یکی از پارامترهای customUserId یا metrixUserId باید مشخص شده باشد. بدون این شناسه‌ها، متریکس نمی‌تواند رویدادها را به درستی به کاربران نسبت دهد.
• Automation: برای استفاده از قابلیت‌های اتومیشن متریکس (مانند سفرهای مشتری و ارسال پیام‌های هدفمند)، ارائه customUserId الزامی است.
• Attribution: برای کاربردهای مربوط به اتریبیوشن (مثلاً اتصال رویدادهای درون‌برنامه به منبع نصب اپلیکیشن)، ارائه metrixUserId ضروری است. در صورت عدم ارسال metrixUserId، رویدادها به سورس نصب متصل نخواهند شد.

برای آشنایی بیشتر با انواع شناسه‌های کاربران و نقش آن‌ها در متریکس، لطفاً به بخش شناسه‌های متریکس مراجعه فرمایید.

۴. ابزارهای کمکی

• Postman Collection: برای سهولت در تست و ارسال درخواست‌ها، می‌توانید فایل Postman Collection را از اینجا دریافت کنید. این کالکشن شامل نمونه درخواست‌هایی برای ارسال رویدادهای کاربر و اکشن است.