S2S Integration


یکپارچه سازی سرور با سرور

این API این امکان را به شما می‌دهد که رخداد‌هایی که در داخل App یا خارج از آن رخ می‌دهد اما توسط SDK ارسال نمی‌شود را، از طریق سرور‌های خود برای ما ارسال کنید. برای این منظور می‌توانید از API زیر استفاده کنید

Method: POST

URL: "https://analytics.metrix.ir/inappevent/{appId}"

appId: همان کلید اپلیکیشن شماست که از پنل متریکس آن را دریافت می‌کنید

Path Variable

{
  "appId": "APP_ID"
}

برای پیدا کردن appId برنامه‌ی مورد نظر خود می‌توانید به صفحه‌ی تنظیمات اپلیکیشن خود در داشبورد مراجعه کنید و از بخش App Info آن را ‌کپی کنید.

Request Header

{
  "Authorization":  "DEV_KEY"
}

مقدار dev-key توسط سیستم برای هر اپلیکیشن به صورت مجزا تولید می‌شود. کافیست با مراجعه به صفحه‌ی S2S Integration در بخش تنظیمات اپلیکیشن، کلید توسعه‌دهنده یا Developer Key را کپی نمایید.

همچنین برای امنیت بیشتر داده‌های دریافتی می‌توانید در قسمت S2S Integration در صفحه پیشین، لیستی از IP های مورد تائید خود را وارد کنید تا تنها رخدادهای دریافتی از آن سرورها معتبر شمرده شوند.

Request Body

{
  "metrixUserId": "METRIX_USER_ID",
  "metrixSessionId": "METRIX_SESSION_ID",

  "idfa": "IDFA",   // for ios
  "advertisingId": "GOOGLE_PLAY_SERVICES_ADVERTISING_ID",   // for Android

  // A JSON containing a rich in-app event attributes - must be String to String
  "customAttributes": {
    "content_type": "wallets",
    "content_id": "hrhfwbrfybwa"
  },

  // A JSON containing a rich in-app event metrics - must be String to Double
  "customMetrics": {
    "revenue": 130.5
  },

  "deviceIp": "USER_DEVICE_IP",
  "eventSlug": "EVENT_SLUG",              // e.g. "taqsq"
  "eventTime": "EVENT_TIMESTAMP_MILIIS"   // e.g 1570274953412 timestamp in millisecond
}

Revenue Event

برای ارسال ایونت درآمدی، باید پارامترهای زیر برای متریکس ارسال شوند.

{
  "customAttributes": {
    // IRR, USD, EUR
    "_currency": "IRR"
  },
  "customMetrics": {
    "_revenue": 53.700
  }
}

پارامترها

تمام پارامتر‌‌هایی که در Header و URL وجود دارند ضروری محسوب می‌شود و به هنگام استفاده از این API باید وارد شوند.

پارامترهای اجباری

  • metrixUserId : شناسه‌ای که متریکس به کاربران اپلیکیشن شما اختصاص می‌دهد. برای دریافت اطلاعات بیشتر درباره این شناسه و چگونگی دریافت آن در اپلیکیشن خود به مستندات فنی مراجعه کنید.

  • metrixSessionId : شناسه‌ای که متریکس به نشست‌های کاربران در اپلیکیشن شما اختصاص می‌دهد.

  • برای دریافت اطلاعات بیشتر درباره این شناسه و چگونگی دریافت آن در اپلیکیشن خود به مستندات فنی مراجعه کنید.

  • advertisingId یا idfa : همان طور که می‌دانید idfa برای دستگاه‌هایی با سیستم‌عامل ios و advertisingId برای Android است.

  • با توجه به نوع سیستم‌عاملی که رخداد مورد نظر شما در آن اتفاق می‌افتد باید دقیقا یکی از آن‌ها را انتخاب و داده‌ی متناظر با آن را وارد کنید. انتخاب هر دوی آن‌ها یا هیچ‌کدام از آن‌ها باعث مواجه شدن با خطای 400 Bad Request می شود.

  • eventSlug : همان slug مشخص شده در حین تعریف یک رخداد در داشبورد متریکس است.

  • eventTime : زمانی که رخداد در اپلیکیشن شما اتفاق می‌افتد، در صورتی که این زمان وارد نشده باشد، زمانی از سیستم که رخداد دریافت می‌شود به عنوان زمان وقوع رخداد ثبت می‌شود.

پارامترهای اختیاری

  • customAttributes : با این پارامتر می‌توانید اطلاعات دلخواه خود را ارسال کنید.

  • اطلاعات ارسالی در این بخش یک Json است که تمامی مقدارهای آن باید رشته (String) باشند.

  • customMetrics : با این پارامتر می‌توانید اطلاعات دلخواه خود را ارسال کنید.

  • اطلاعات ارسالی در این بخش یک Json است که تمامی مقدارهای آن باید عدد اعشاری (Double) باشند.

  • deviceIp : با این پارامتر آدرس ip دستگاه را می‌توانید ارسال کنید.

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

توضیحکد خطانوع خطا
همانطور که در بالا اشاره شد، پارامترهای advertisingId یا idfa نمی‌توانند خالی باشند و حتما یکی از آنها متناسب با سیستم‌عامل موردنظر باید فراهم شودBAD_REQUEST: 400IDFA_AND_ADVERTISING_ID_SHOULD_NOT_BE_NULL
همانطور که در بالا اشاره شد، پارامترهای advertisingId یا idfa نمی‌توانند همزمان ارسال شوند و حتما فقط یکی از آنها باید ارسال شودBAD_REQUEST: 400ONLY_ONE_OF_IDFA_AND_ADVERTISING_ID_SHOULD_BE_SET
در صورتی که سرویس S2S را در پرایسینگ پلن یا تنظیمات اپلیکیشن خود فعال نکرده باشید، این خطا را دریافت خواهید کرFORBIDDEN: 403S2S_FEATURE_NOT_AVAILABLE
اگر یکی از پارامترهای ارسالی صحیح نباشد با این خطا مواجه می‌شوید. برای مثال dev-key را با مقداری متفاوت از آنچه در اپلیکشین خود وارد کرده اید، ارسال کنیدFORBIDDEN: 403INVALID_PARAMETERS
اگر یکی از پارامترهای ارسالی صحیح نباشد با این خطا مواجه می‌شوید. برای مثال آدرس آی پی سروری که ریکوئست از آن ارسال می‌شود در بین آی پی‌هایی که در تنظیمات داشبورد تعریف کرده‌اید، نباشدFORBIDDEN: 403INVALID_PARAMETERS
در صورتی که slug ارسالی از سمت شما صحیح نباشد، این خطا را دریافت می‌کنیدNOT_FOUND: 404EVENT_TYPE_DOES_NOT_EXIST


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

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

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

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

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

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

چطور باید سرور خودم را با سرور متریکس یکپارچه کنم؟

برای انجام این یکپارچه سازی از بخش تنظیمات اپلیکیشن خود در داشبورد اقدام کنید. لازم است development key و آدرس‌ IP های مجاز خود را وارد کنید. برای راهنمایی بیشتر از مستندات متریکس کمک بگیرید.

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

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