kenar-docs



مدیریت اپلیکیشن‌ها

کاربران برنامه‌های خدمت‌دهنده در کنار دیوار را با نام افزونه یا مکمل می‌بینند. هر کدام از افزونه‌ها یا مکمل‌ها باید در قالب یک «اپلیکیشن» (Application, App, برنامه) در پنل کنار دیوار ثبت شده و مدیریت شوند.
هر اپلیکیشن دارای پارامترهای مختلفی‌ست که بر مبنای آن‌ها، نحوهٔ معرفی اپلیکیشن به کاربرها در دیوار، نحوهٔ تعامل سرویس‌های دیوار با اپلیکیشن، امکانات در دسترس اپلیکیشن و … تعیین می‌شوند.


🚧 در دست احداث 🚧

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


🎛️ لیست کامل پارامترهای یک اپلیکیشن را اینجا ببینید.


شناسهٔ اپلیکیشن (Slug)

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

👈 برای مشاهدهٔ این شناسه، مدیریت‌اپ‌ها در پنل کنار را باز کرده و فیلد slug را بخوانید.


نمای اپلیکیشن

اپلیکیشن شما در جایگاه‌های مختلف دیوار به شیوه‌های مختلف، به کاربرها معرفی می‌شود:

![نمای یک اپلیکیشن در زمان معرفی به کاربر](/img/app-in-list.png)


تعامل با کاربرها

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


تعامل با کاربر پس از ثبت آگهی

پس از ثبت آگهی‌های مرتبط، اپلیکیشن شما به کاربرها معرفی می‌شوند. در صورت انتخاب کاربر، آدرس مشخص شده در پارامتر Fallback URL برنامهٔ شما برای کاربر باز می‌شود. درخواست ارسالی به Fallback URL به شکل زیر است:

https://your.app.ir
  ?post_token=<post-token>
  &return_url=<return-url>  
  &...

برای توسعه راحت‌تر اپلیکیشن خود میتوانید با استفاده از ngrok نسخه localhost اپلیکیشن خود را به روی یک domain تونل کنید


📖 اطلاعات بیشتر در مورد افزونه‌های آگهی‌ها را اینجا بخوانید.


تعامل با کاربر در چت

در مکالمات مرتبط، اپلیکیشن شما به کاربرها (به طرق مختلف) معرفی می‌شود. در صورت انتخاب کاربر، ابتدا درخواستی به شکل زیر به آدرس مشخص شده در پارامتر Session Initialization URL اپلیکیشن زده می‌شود:

POST https://your.app.ir
Content-Type: application/json
authorization: 

{
  "callback_url": "<callback-url>",
  "post_token": "<post-token>",
  "user_id": "<user-id>",
  "peer_id": "<peer-id>",
  ...
}


در پاسخ به این درخواست، می‌بایست آدرسی را به شکل زیر برگردانید. کاربر به أدرسی که در قسمت url پاسخ شماست هدایت می‌شود و با برنامهٔ تحت وب شما تعامل می‌کند.

{
  "status": "200",
  "message": "success",
  "url": "https://yourdomain.com/some/where/to/start"
}


📖 اطلاعات بیشتر در مورد افزونه‌های چت را اینجا بخوانید.


تعامل با دیوار

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

گسترهٔ امکانات قابل استفاده در سطح اپلیکیشن تنظیم می‌شود:

👈 در صورتی که به استفاده از قابلیت یا المانی نیاز دارید ولی دسترسی به آن را ندارید، با ما تماس بگیرید.


مدیریت کاربران پنل کنار

در پنل توسعه‌دهندگان کنار، چند کاربر می‌توانند به یک اپلیکیشن خاص دسترسی داشته باشند و بر روی آن کار کنند. پارامتر Users تعیین کنندهٔ این دسترسی‌هاست. برای تنظیم دسترسی کاربرهای مختلف به اپلیکیشن خود با ما تماس بگیرید.


لیست پارامترها

| پارامتر | توضیحات | | - | - | | `Slug` | [شناسهٔ یکتای اپلیکیشن][شناسه] | | `Display` | [عنوان اپلیکیشن][نما] | | `Subtitle` | [متن کوتاه برای زیر عنوان اپلیکیشن][نما] | | `Avatar` | [تصویر اپلیکیشن][نما] | | `Description` | [توضیحات اپلیکیشن][نما] | | `Fallback URL` | [آدرس اپلیکیشن برای تعامل بعد از ثبت آگهی][آگهی] | | `Session Initialization URL` | [آدرس اپلیکیشن برای تعامل در چت][چت] | | `Divar Identification Key` | [کلید احراز منبع درخواست‌ها در چت][چت] | | `Permissions` | [‌دسترسی‌های اپلیکیشن][دیوار] | | `Widgets` | [‌المان‌های در اختیار اپلیکیشن][دیوار] | | `Users` | [‌کاربرهایی که به اپلیکیشن دسترسی دارند][کاربرها] |


🚀 انتشار افزونه در دیوار

اپ تستی من آماده شده، چه‌طور می‌تونم اون‌ رو در اختیار کاربران دیوار قرار بدم؟

زمانی که از عملکرد صحیح تمام بخش‌های اپ تستی خود روی آگهی‌های تستی (از نظر فنی و همچنین سیاست‌های کنار دیوار) مطمئن شدید، در پنل کنار، تیکتی با محتوای درخواست بررسی اپ ثبت کنید. در صورتی که استفاده از سرویس شما نیاز به پرداخت وجه دارد، لطفاً چند کد تخفیف به همراه تیکت ارسال کنید و یا حساب کاربری شمارهٔ 09306603371 را در سرویس خود شارژ کنید و یا درگاه پرداخت را برای این شماره غیرفعال کنید. تیکت‌های شما حداکثر تا یک روز کاری بعد از زمان ثبت، پاسخ داده خواهند شد و نتیجه‌ی بررسی، حداکثر تا یک هفته‌ی کاری پس از زمان ثبت درخواست، برای شما در پاسخ به تیکت اعلام می‌شود.

در صورتی که اپ دارای مشکلات فنی، پیاده‌سازی و یا نقض قوانین و سیاست‌های کنار دیوار باشد، فهرست موارد در نتیجه‌ی بررسی به شما گزارش می‌شود و تمامی موارد پیش از درخواست بررسی مجدد، باید اصلاح شوند.

در صورتی که مشکلات و یا ایرادات تکراری در فرآیند بررسی مجدد وجود داشته باشد، فرآیند بررسی دفعهٔ سوم، حداقل یک ماه پس از ثبت درخواست بررسی مجدد انجام خواهد

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

ما برای شما یک برنامهٔ آمادهٔ انتشار می‌سازیم و شما می‌توانید این برنامه را در داخل پنل کاربری و قسمت «برنامه‌ها» مشاهده کنید. از آن‌جایی که شناسه‌ی یکتا (slug) در این اپ تغییر کرده است، باید برای این اپ کلید API بسازید و app-slug را در هدر OAuth آپدیت کنید بعد از آن می‌توانید از طریق تیکت به ما اطلاع دهید تا برنامهٔ شما را روی شهر و دسته‌ٔ تعیین‌شده فعال کنیم

نکته ۱: دسته‌ٔ فعالیت سرویس معمولاً بر اساس نوع خدمات سرویس شما مشخص می‌شود.

نکته ۲: شهر یا شهرهایی که سرویس شما در آن فعال می‌شود، با توجه به تحلیل دیتا از سمت کنار دیوار مشخص می‌شود.

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