درگاه یکپارچه دریافت داده به صورت سرور به سرور

درگاه یکپارچه دریافت داده به این منظور طراحی شده است تا با استفاده از آن، بتوانید اطلاعات کاربران و رفتارهای آن‌ها را ارسال کنید و از داشبوردهای تحلیلی، بخش‌های دسته بندی کاربر و ارسال پوش نوتیفیکیشن استفاده کنید. به این ترتیب می‌توانید رخدادهایی که از طریق SDK ارسال نمی‌شوند را ثبت بفرمایید.

دریافت کلیدهای امنیتی

برای ارسال دیتا به صورت سرور به سرور شما نیاز به دو کلید دارید که داخل داشبورد برای شما فراهم شده است. کلید اول همان APP_ID شماست که برای پیاده‌سازی SDK از آن استفاده کرده‌اید. کلید دوم نیز API_Key مربوط به سرور شما می‌باشد که داخل تنظیمات اپلیکیشن می‌توانید مشاهده کنید. این کلیدها به ازای هر اپلیکیشن متفاوت می‌باشند

پس از دریافت این کلیدها از داشبورد، باید داخل Header درخواست خود آن‌ها را ثبت کنید. کلیدهای مرتبط با هر کدام به شرح زیر است

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

• APP_ID: همان کلید اپلیکیشن شماست که از پنل متریکس آن را دریافت می‌کنید
• API_Key: همان کلید درسترسی مختص به سرور شماست که از پنل متریکس یا تماس با پشتیبانی آن را دریافت می‌کنید

فرمت ارسال داده ها

برای ارسال داده ها باید درخواست به صورت زیر ارسال شود.

POST 'https://entry.metrix.ir/'

- Header 'X-Application-Id': 'APP_ID'
- Header 'X-API-Key': 'API_Key'
- Header 'content-type': 'application/json'

- Body
{
  "customUserId": "username | email | phone | any unique user id", // e.x: '+989...'
  "metrixUserId": "<get id from sdk>", // device id obtained from sdk for attribution purpose
  "messages": [...]
}

• customUserId: شناسه ای که برای معرفی کاربر به صورت یکتا به متریکس ارسال می شود. مانند نام کاربری. این شناسه برای کاربرد های مربوط به اتومیشن اجباری است.
• metrixUserId: شناسه ای که متریکس به دستگاه کاربر اختصاص داده است. برای دریافت این شناسه به مستندات اس دی کی ها مراجعه کنید. این شناسه برای کاربرد های مربوط به اتربیوشن اجباری است.
• messages: لیست پیام های مربوط به کاربر که در ادامه انواع آن بیشتر توضیح داده می شود. قالب کلی:

{
  "type": "message type: user | action | revenue",
  "id": "request id", // random generated uid, e.x: UUID.randomUUID().toString()
  "time": long, // current timestamp in millis, e.x: new Date().getTime()
  ...
}

• type: این فیلد نوع پیامی که برای سرور ما ارسال میکنید مشخص میکند. با توجه به این فیلد سایر مقادیر که با ... نشان داده شده است مشخص می شوند.
• id: این فیلد برای تشخیص ارسال پیام تکراری استفاده میشود. برای هر پیام به صورت جداگانه در لحظه یک آیدی تصادفی تولید کنید. فرمت آیدی باید متن باشد و محدودیت دیگری ندارد.
• time: زمان رخداد به میلی ثانیه

توجه کنید که حداقل یکی از پارامتر های customUserId و metrixUserId باید مشخص شده باشد.

در کاربرد های اتومیشن مقداردهی customUserId لازم است. در صورت استفاده همزمان از اس دی کی توجه داشته باشید مقدار یکسانی برای هر کابر ست شود.

در کاربرد های اتربیوشن مقداردهی metrixUserId لازم است و در صورت عدم مقدار دهی رخداد ها به سورس نصب متصل نمی شوند.

دریافت شناسه دستگاه‌های متریکس

برای دریافت metrixUserId به مستندات زیر مراجعه کنید.

• Android SDK
• IOS SDK
• Flutter SDK
• React Native SDK
• Unity SDK
• ...

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

با استفاده از این API شما می‌توانید خصیصه‌های کاربران خود را برای متریکس ارسال کنید و با استفاده از آن‌ها کاربران خود را دسته بندی کنید و برای هر کدام از آن‌ها پیام اختصاصی ارسال بفرمایید. خصیصه‌هایی که به صورت پیش فرض تعریف شده‌اند به شرح زیر است.

همچنین داخل پارامتر customAttributes می‌توانید ویژگی‌های دلخواه خود را به صورت Map<String, String> وارد کنید.

{
  "type"*: "user",
  "id"*: "request id", // random generated uid
  "time"*: 'Long', // current timestamp in millis
  "firstName": "User first name",
  "lastName": "User last name",
  "phoneNumber": "09121122333",
  "hashedPhoneNumber": "hashed value of phone number",
  "email": "User email address",
  "hashedEmail": "hashed value of email",
  "country": "User country",
  "city": "User city",
  "region": "User region",
  "locality": "User locality",
  "gender": "Male/Female/Other",
  "birthday": 'Long',   // timestamp of user birthday in millis
  "channels": ["SMS", "Push", "Email"],
  "customAttributes": {
    "your_user_custom_attribute_key": "custom_attribute_value"
  }
}

در نهایت فرمت درخواست شما مشابه زیر می‌شود.

POST 'https://entry.metrix.ir/'

- Header 'X-Application-Id': 'appId'
- Header 'X-API-Key': 'API Key'
- Header 'content-type': 'application/json'

- Body
{
  "customUserId"*: "r.akbari",
  "messages": [
    {
      "type"*: "user",
      "id"*: "18788701-c330-4000-853d-fe8998511280",
      "time"*: 1680000000000,
      "firstName": "Reza",
      "lastName": "Akbari",
      "phoneNumber": "09121122333",
      "email": "[email protected]",
      "country": "Iran",
      "city": "Tehran",
      "region": "Vanak",
      "locality": "User locality",
      "gender": "Male",
      "birthday": 1554321000000,
      "channels": ["SMS", "Push", "Email"],
      "customAttributes": {
        "loyalty_level": "vip",
        "job": "developer"
      }
    }
  ]
}

• پارامتر type نشان‌دهنده نوع ریکوئست می‌باشد. برای ثبت خصیصه‌های کاربر این پارامتر حتما باید user وارد شود.
• برای شناسایی باقی رخدادهای مربوط به کاربر ابتدا باید حداقل یک بار کاربر ثبت شده باشد.
• برای ثبت کاربر نیازی به پر کردن پارامتر های بدون ستاره نیست. یعنی مقدار دهی customUserId و ارسال یک پیام خالی از نوع user به ثبت کاربر منجر می شود.
• توجه داشته باشید تمامی پارامترهای ستاره‌دار اجباری هستند و هنگام درخواست باید وارد شوند.
• پارامترهای type و id و time باید در تمامی درخواست‌ها ثبت شوند.

ارسال رخداد رفتار کاربران

با استفاده از این API شما می‌توانید رخداد‌های کاربران خود را برای متریکس ارسال کنید. فرمت کلی ارسال رخداد به شکل زیر است. توجه داشته باشید در ارسال رفتار کاربران، پارامتر type را action تعریف کنید.

POST 'https://entry.metrix.ir/'

- Header 'X-Application-Id': 'appId'
- Header 'X-API-Key': 'API Key'
- Header 'content-type': 'application/json'

- Body
{
  "customUserId": "userId used before",
  "messages": [
    {
      "type"*: "action",
      "id"*: "request id",
      "time"*: 'Long'  // event occurence timestamp in millis,
      
      "name"*: "Your event slug defined in dashboard",   // e.x: 'aewqd'
      "attributes": {   // Map<String, String>
        "order_id": "12",
        "product_id": "20"
      }
    }
  ]
}

نکته: توجه داشته باشید در صورت استفاده از اتومیشین حتما باید قبل از ارسال رخداد رفتار کاربر خصیصه های کاربر را ارسال کرده باشید.

نمونه CURL و Postman

کالکشن postman برای ارسال یوزر و ایونت

می‌توانید این فایل را از اینجا دریافت کنید.

دستور curl برای ارسال یوزر و ایونت

curl --location 'https://entry.metrix.ir/' \
--header 'content-type: application/json' \
--header 'x-api-key: API_KEY' \
--header 'x-application-id: APP_ID' \
--data-raw '{
    "customUserId": "username",
    "metrixUserId": "7d5dbfbf-8ff9-44db-be79-953d2c1d7d6f",
    "messages": [
        {
            "type": "user",
            "id": "ced87826-2014-4770-a1d8-b6ed3c931cea",
            "time": 1677323951700,
            "firstName": "Ahmad",
            "lastName": "Ahmadi",
            "phone": "+98917*******",
            "email": "[email protected]",
            "country": "Iran",
            "city": "Tehran",
            "region": "Vanak",
            "gender": "Male",
            "birthday": 600873151010,
            "channels": [
                "SMS",
                "Push",
                "Email"
            ],
            "customAttributes": {
                "xxx": "yyy"
            }
        },
        {
            "type": "action",
            "id": "acc89899-2018-4881-a5d8-bad3a9c31bbb",
            "time": 1677323951700,
            "name": "slug1",
            "attributes": {
                "xxx": "yyy"
            }
        }
    ]
}'

ارسال رخدادهای درآمدی کاربران

با استفاده از این API می‌توانید رخدادهای درآمدی کاربران خود را ثبت کنید. فرمت کلی ارسال رخدادهای درآمدی به شکل زیر است. توجه داشته باشید در ارسال رخداد درآمدی کاربران، پارامتر type را revenue تعریف کنید.

POST 'https://entry.metrix.ir/'

- Header 'X-Application-Id': 'appId'
- Header 'X-API-Key': 'API Key'
- Header 'content-type': 'application/json'

- Body
{
  "customUserId": "userId used before",
  "metrixUserId": "metrix user id from sdk",
  "messages": [
    {
      "type"*: "revenue",
      "id"*: "request id",
      "time"*: 'Long'  // event occurence timestamp in millis,
      
      "name"*: "Your event slug defined in dashboard",   // e.x: 'aewqd'
      "revenue"*: 53.700   // Double,
      "currency"*: "IRR"   // IRR, USD, EUR    
    }
  ]
}

خطاهای دریافتی از سرور متریکس

سؤالات متداول در مورد یکپارچه‌سازی سرور با سرور

منظور از یکپارچه سازی سرور با سرور چیست؟

زمانی که رخداد ها از طریق سرور شما به طور مستقیم به سرور متریکس ارسال شود از یکپارچه سازی سرور با سرور یا s2s صحبت میکنیم.

این مدل در مقابل استفاده از sdk متریکس می باشد که در آن حالت رخداد ها به وسیله sdk ما از طریق دستگاه کاربر به متریکس ارسال میشود.

چرا یکپارچه سازی سرور با سرور اهمیت دارد؟

زمانی که ویرایش کد منبع اپلیکیشن برای پلتفرم اتریبیوشن امکان پذیر نباشد، این رویکرد یکپارچه سازی سودمند است. اما به طور کلی در چهار حالت زیر از این قابلیت استفاده کنید:

• رخداد مربوطه در سمت سرور شما پردازش یا تایید می شود. برای مثال پرداخت موفق یا سررسید فاکتور.
• تیم شما امکان ویرایش کد سورس اپلیکیشنتان را ندارد و آن را برای مثال به یک شخص سوم(third party) واگذار کرده است.
• SDK های شخص سوم(third party) با سیاست های شرکت شما به عنوان تبلیغ دهنده مطابقت ندارد
• می خواهید قبل از به‌روز‌رسانی اپلیکیشن، رصد کمپین های خود را شروع کنید

آیا اپلیکیشن‌های خاصی باید از این قابلیت یکپارچه سازی استفاده کنند؟

این ویژگی برای تمام اپلیکیشن های فعال در تمامی حوزه‌ها مناسب است. اما اپلیکیشن هایی که پرداخت خارج از برنامه در آنها بیشتر رخ می دهد (مانند اپ های بانکی، مالی و پرداخت الکترونیک) می‌توانند استفاده‌ی بیشتری از این سرویس ببرند. با این حال اپلیکیشن‌های دیگر مانند حمل و نقل نیز که برای پرداخت هزینه سفر، کاربر را به درگاه پرداخت هدایت می‌کنند بهتر است از این یکپارچه‌سازی بهره ببرند.