Gateway S2S Integration


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

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

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

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

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

'X-Application-Id': '{YOUR APP_ID FROM METRIX DASHBOARD}' 
'X-API-Key': '{YOUR API KEY FROM METRIX DASHBOARD}' 
  • appId: همان کلید اپلیکیشن شماست که از پنل متریکس آن را دریافت می‌کنید

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

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

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

{
  "customId"*: "Your userId defined throughout your system",
  "firstName": "User first name",
  "lastName": "User last name",
  "phoneNumber": "+989121122333",
  "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
{
  "metrixUserId": "metrix userId you got from SDK",
  "messages": [
    "type"*: "user",
    "id"*: "request id",
    "time"*: 'Long'  // current timestamp in millis,

    "customId"*: "Your userId defined throughout your system",
    "firstName": "Reza",
    "lastName": "Akbari",
    "phoneNumber": "+989121122333",
    "hashedPhoneNumber": "hashed value of phone number",
    "email": "[email protected]",
    "hashedEmail": "hashed value of email",
    "country": "Iran",
    "city": "Tehran",
    "region": "Vanak",
    "locality": "User locality",
    "gender": "Male",
    "birthday": 600873151000,
    "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
{
  "metrixUserId": "metrix userId you got from SDK",
  "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"
    }
  ]
}

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

با استفاده از این 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
{
"metrixUserId": "metrix userId you got 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 را در پرایسینگ پلن یا تنظیمات اپلیکیشن خود فعال نکرده باشید، این خطا را دریافت خواهید کردFORBIDDEN: 403S2S_FEATURE_NOT_AVAILABLE
اگر یکی از پارامترهای ارسالی صحیح نباشد با این خطا مواجه می‌شوید. برای مثال API-Key را با مقداری متفاوت از آنچه در اپلیکشین خود وارد کرده اید، ارسال کنیدFORBIDDEN: 403INVALID_PARAMETERS
در صورتی که slug ارسالی از سمت شما صحیح نباشد، این خطا را دریافت می‌کنیدNOT_FOUND: 404EVENT_TYPE_DOES_NOT_EXIST


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

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

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

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

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

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

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

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