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

درگاه یکپارچه دریافت داده به این منظور طراحی شده است تا با استفاده از آن، بتوانید اطلاعات کاربران و رفتارهای آن‌ها را ارسال کنید و از داشبوردهای تحلیلی، بخش‌های دسته بندی کاربر و ارسال پوش نوتیفیکیشن استفاده کنید. به این ترتیب می‌توانید رخدادهایی که از طریق 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...'
  "messages": [...]
}

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

{
  "type": "message type: user | action | revenue",
  "id": "request id", // random generated uid
  "time": 'Long', // current timestamp in millis
  ...
}

• در صورتی که پیام ارسالی مربوط به دستگاه (یا کاربر ناشناس) است میتوان به جای customUserId از metrixUserId استفاده کرد که مقدار آن باید از SDK دریافت شود.
• توجه داشته باشید که ارسال هر دو این پارامترها با هم صحیح نمی باشد. استفاده از customUserId پیشنهاد می شود.

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

با استفاده از این 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 و id و time باید در تمامی درخواست‌ها ثبت شوند.
• پارامتر type نشان‌دهنده نوع ریکوئست می‌باشد. برای ثبت خصیصه‌های کاربر این پارامتر حتما باید user وارد شود.
• پارامتر id مشخص کننده شناسه ریکوئست می‌باشد. این پارامتر به این منظور استفاده می‌شود تا در صورت ارسال مجدد یک داده امکان تشخیص و پردازش آن وجود داشته باشد.
• برای شناسایی باقی رخدادهای مربوط به کاربر ابتدا باید حداقل یک بار کاربر ثبت شده باشد.

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

با استفاده از این 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",
    "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",
  "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    
    }
  ]
}

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

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

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

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

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

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

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

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

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