کاربران برنامه‌های خدمت‌دهنده در کنار دیوار را با نام افزونه یا مکمل می‌بینند. هر کدام از افزونه‌ها یا مکمل‌ها باید در قالب یک «اپلیکیشن» (Application, App, برنامه) در پنل کنار دیوار ثبت شده و مدیریت شوند.
هر اپلیکیشن دارای پارامترهای مختلفی‌ست که بر مبنای آن‌ها، نحوهٔ معرفی اپلیکیشن به کاربرها در دیوار، نحوهٔ تعامل سرویس‌های دیوار با اپلیکیشن، امکانات در دسترس اپلیکیشن و ... تعیین می‌شوند.
🚧 در دست احداث 🚧
در حال حاضر برای تعریف اپلیکیشن جدید یا تغییر پارامترهای اپلیکیشن خود با ما تماس بگیرید. در آینده، با تعریف فرآیند بررسی اپلیکیشن‌ها، امکان تعریف و تغییر اپلیکیشن‌ها در پنل نیز فراهم خواهد شد.
🎛️ لیست کامل پارامترهای یک اپلیکیشن را اینجا ببینید.
هر اپلیکیشن شناسهٔ یکتایی دارد که در تعاملات مختلف با سرویس‌های دیوار، مثلا در فرآیند احراز باز، استفاده می‌شود. این شناسه برای هر اپلیکیشن در زمان ساخت تعیین می‌شود و بعد از ساخت اپلیکیشن قابل تغییر نیست.
👈 برای مشاهدهٔ این شناسه، مدیریت‌اپ‌ها در پنل کنار را باز کرده و فیلد slug را بخوانید.
اپلیکیشن شما در جایگاه‌های مختلف دیوار به شیوه‌های مختلف، به کاربرها معرفی می‌شود:
- فیلد عنوان (Display) در همهٔ نقاط تعامل با کاربرهای دیوار به کار خواهد رفت. علاوه بر محل‌های معرفی اپلیکیشن‌ها، عنوان اپلیکیشن روی افزونه‌های مندرج بر آگهی‌ها یا پیام‌های ارسالی در چت نیز نمایش داده می‌شود.
- فیلد زیرعنوان (Subtitle) را بهتر است برای نمایش قیمت یا محدودهٔ قیمت خدمات استفاده کنید. پیشنهاد می‌کنیم از جداکنندهٔ هزارگان (٬) برای خوانایی بیشتر استفاده کنید. برای نوشتن این کاراکتر در صفحه‌کلید استاندارد فارسی از کلید ترکیبی
shift + 2استفاده کنید. - لوگوی اپلیکیشن (Avatar) نیز در خیلی از نقاط تعامل با کاربرها استفاده می‌شود. مطمئن شوید لوگوی شما در یک کادر مربع با فاصلهٔ ۸ پیکسلی از لبه‌ها محاط شده‌باشد و نسبت ابعاد فایل تصویر آن ۱:۱ باشد و همچنین در ابعاد کوچک به خوبی دیده و شناسایی شود.
- توضیحات (Description) نیز در بعضی از نقاط معرفی اپلیکیشن شما به کاربرها نمایش داده می‌شود. سعی کنید توضیحات را تا جای ممکن کوتاه و خلاصه نگه دارید. در صورت دریافت هزینه از کاربرها در ازای خدمات، حتما در این فیلد به شکل شفاف برای کاربرها توضیح دهید.
کاربرهای دیوار برای تعامل با برنامهٔ شما، به رابط کاربری تحت وب شما هدایت می‌شوند. مکانیزم انتقال در نقاط تعامل مختلف متفاوت است، اما به طور کلی آدرسی از اپلیکیشن شما دریافت شده، و سپس بسته به پلتفرم کاربر (وب، اندروید، آی‌اوس) کاربر به وب‌ویو یا پاپ‌آپی با آدرس دریافت شده هدایت می‌شود. در طی این فرآیند، اطلاعات اولیه‌ای مانند شناسهٔ آگهی، شناسهٔ کاربر تعامل کننده، یا ... نیز در اختیار اپلیکیشن شما قرار می‌گیرد.
پس از ثبت آگهی‌های مرتبط، اپلیکیشن شما به کاربرها معرفی می‌شوند. در صورت انتخاب کاربر، آدرس مشخص شده در پارامتر Fallback URL برنامهٔ شما برای کاربر باز می‌شود. درخواست ارسالی به Fallback URL به شکل زیر است:
https://your.app.ir
?app_slug=<app-slug>
&post_token=<post-token>
&return_url=<return-url>
&...- پارامتر
app_slugشناسهٔ برنامهٔ شماست. - پارامتر
post_tokenشناسهٔ آگهی مربوطه‌ست.- با کمک این شناسه، می‌توانید اطلاعات آگهی را از دیوار دریافت کنید.
- برای دریافت اجازه‌های مربوط به این آگهی، از این شناسه استفاده کنید.
- برای استفاده از قابلیت‌های مرتبط با این آگهی (مثل اضافه کردن افزونه به آگهی) نیز از این شناسه استفاده کنید.
- پارامتر
return_url، آدرسیست که می‌بایست کاربر را بعد از اتمام کار به آن هدایت کنید. - اطلاعات تکمیلی در مورد آگهی نیز در پارامترها درج می‌شوند.
📖 اطلاعات بیشتر در مورد افزونه‌های آگهی‌ها را اینجا بخوانید.
در مکالمات مرتبط، اپلیکیشن شما به کاربرها (به طرق مختلف) معرفی می‌شود. در صورت انتخاب کاربر، ابتدا درخواستی به شکل زیر به آدرس مشخص شده در پارامتر Session Initialization URL اپلیکیشن زده می‌شود:
POST https://your.app.ir
Content-Type: application/json
authorization: {{ Divar Identification Key }}
{
"callback_url": "<callback-url>",
"post_token": "<post-token>",
"user_id": "<user-id>",
"peer_id": "<peer-id>",
...
}- پارامتر
post_tokenشناسهٔ آگهی مورد نظر است. - پارامتر
user_idشناسهٔ کاربریست که با اپلیکیشن تعامل کرده. - پارامتر
peer_idشناسهٔ طرف دیگر چت است.- برای دریافت اجازه‌ها یا استتفاده از قابلیت‌های مربوط به چت، هر سهٔ این پارامترها را ارائه کنید.
- پارامتر
callback_urlادرسی‌ست که باید کاربر را بعد از اتمام فرآیند به آن هدایت کنید. - مقدار
authorizationمعادل پارامترDivar Identification Key، که در سطح اپلیکیشن قابل تنظیم است، قرار داده خواهد شد. با خواندن این هدر و مقایسهٔ آن، می‌توانید منبع درخواست را احراز کرده مطمئن شوید درخواست از جانب دیوار ارسال شده است.
در پاسخ به این درخواست، می‌بایست آدرسی را به شکل زیر برگردانید. کاربر به أدرسی که در قسمت url پاسخ شماست هدایت می‌شود و با برنامهٔ تحت وب شما تعامل می‌کند.
{
"status": "200",
"message": "success",
"url": "https://yourdomain.com/some/where/to/start"
}📖 اطلاعات بیشتر در مورد افزونه‌های چت را اینجا بخوانید.
علاوه بر تعامل با کاربرها، اپلیکیشن شما نیاز به تعامل با دیوار، مثلا برای دریافت اطلاعات بیشتر در مورد آگهی، افزودن محتوا به آگهی، ارسال پیام در چت، ... نیز دارد. این تعاملات از طریق فراخوانی APIهای کنار دیوار، احراز با کلیدهای API، و در صورت نیاز، دریافت اجازه از کاربرها صورت می‌گیرد.
گسترهٔ امکانات قابل استفاده در سطح اپلیکیشن تنظیم می‌شود:
- پارامتر
Permissionsدسترسی‌های کلی اپلیکیشن (حداکثر دسترسی کلیدها) را مشخص می‌کند. - پارامتر
Widgetsالمان‌های محتوایی قابل استفاده در آگهی‌ها را مشخص می‌کند.
👈 در صورتی که به استفاده از قابلیت یا المانی نیاز دارید ولی دسترسی به آن را ندارید، با ما تماس بگیرید.
در پنل توسعه‌دهندگان کنار، چند کاربر می‌توانند به یک اپلیکیشن خاص دسترسی داشته باشند و بر روی آن کار کنند. پارامتر Users تعیین کنندهٔ این دسترسی‌هاست. برای تنظیم دسترسی کاربرهای مختلف به اپلیکیشن خود با ما تماس بگیرید.
| پارامتر | توضیحات |
|---|---|
Slug |
شناسهٔ یکتای اپلیکیشن |
Display |
عنوان اپلیکیشن |
Subtitle |
متن کوتاه برای زیر عنوان اپلیکیشن |
Avatar |
تصویر اپلیکیشن |
Description |
توضیحات اپلیکیشن |
Fallback URL |
آدرس اپلیکیشن برای تعامل بعد از ثبت آگهی |
Session Initialization URL |
آدرس اپلیکیشن برای تعامل در چت |
Divar Identification Key |
کلید احراز منبع درخواست‌ها در چت |
Permissions |
دسترسی‌های اپلیکیشن |
Widgets |
المان‌های در اختیار اپلیکیشن |
Users |
کاربرهایی که به اپلیکیشن دسترسی دارند |
