کاربران برنامه‌های خدمت‌دهنده در کنار دیوار را با نام افزونه یا مکمل می‌بینند. هر کدام از افزونه‌ها یا مکمل‌ها باید در قالب یک «اپلیکیشن» (Application, App, برنامه) در پنل کنار دیوار ثبت شده و مدیریت شوند.
هر اپلیکیشن دارای پارامترهای مختلفی‌ست که بر مبنای آن‌ها، نحوهٔ معرفی اپلیکیشن به کاربرها در دیوار، نحوهٔ تعامل سرویس‌های دیوار با اپلیکیشن، امکانات در دسترس اپلیکیشن و ... تعیین می‌شوند.
🚧 در دست احداث 🚧
در حال حاضر برای تعریف اپلیکیشن جدید یا تغییر پارامترهای اپلیکیشن خود با ما تماس بگیرید. در آینده، با تعریف فرآیند بررسی اپلیکیشن‌ها، امکان تعریف و تغییر اپلیکیشن‌ها در پنل نیز فراهم خواهد شد.
🎛️ لیست کامل پارامترهای یک اپلیکیشن را اینجا ببینید.
هر اپلیکیشن شناسهٔ یکتایی دارد که در تعاملات مختلف با سرویس‌های دیوار، مثلا در فرآیند احراز باز، استفاده می‌شود. این شناسه برای هر اپلیکیشن در زمان ساخت تعیین می‌شود و بعد از ساخت اپلیکیشن قابل تغییر نیست.
👈 برای مشاهدهٔ این شناسه، مدیریت‌اپ‌ها در پنل کنار را باز کرده و فیلد slug را بخوانید.
اپلیکیشن شما در جایگاه‌های مختلف دیوار به شیوه‌های مختلف، به کاربرها معرفی می‌شود:
- فیلد عنوان (Display) در همهٔ نقاط تعامل با کاربرهای دیوار به کار خواهد رفت. علاوه بر محل‌های معرفی اپلیکیشن‌ها، عنوان اپلیکیشن روی افزونه‌های مندرج بر آگهی‌ها یا پیام‌های ارسالی در چت نیز نمایش داده می‌شود.
- فیلد زیرعنوان (Subtitle) را بهتر است برای نمایش قیمت یا محدودهٔ قیمت خدمات استفاده کنید. پیشنهاد می‌کنیم از جداکنندهٔ هزارگان (٬) برای خوانایی بیشتر استفاده کنید. برای نوشتن این کاراکتر در صفحه‌کلید استاندارد فارسی از کلید ترکیبی
shift + 2استفاده کنید. - لوگوی اپلیکیشن (Avatar) نیز در خیلی از نقاط تعامل با کاربرها استفاده می‌شود. مطمئن شوید لوگوی شما در یک کادر مربع با فاصلهٔ ۸ پیکسلی از لبه‌ها محاط شده‌باشد و نسبت ابعاد فایل تصویر آن ۱:۱ باشد و همچنین در ابعاد کوچک به خوبی دیده و شناسایی شود.
- توضیحات (Description) نیز در بعضی از نقاط معرفی اپلیکیشن شما به کاربرها نمایش داده می‌شود. سعی کنید توضیحات را تا جای ممکن کوتاه و خلاصه نگه دارید. در صورت دریافت هزینه از کاربرها در ازای خدمات، حتما در این فیلد به شکل شفاف برای کاربرها توضیح دهید.
کاربرهای دیوار برای تعامل با برنامهٔ شما، به رابط کاربری تحت وب شما هدایت می‌شوند. مکانیزم انتقال در نقاط تعامل مختلف متفاوت است، اما به طور کلی آدرسی از اپلیکیشن شما دریافت شده، و سپس بسته به پلتفرم کاربر (وب، اندروید، آی‌اوس) کاربر به وب‌ویو یا پاپ‌آپی با آدرس دریافت شده هدایت می‌شود. در طی این فرآیند، اطلاعات اولیه‌ای مانند شناسهٔ آگهی، شناسهٔ کاربر تعامل کننده، یا ... نیز در اختیار اپلیکیشن شما قرار می‌گیرد.
پس از ثبت آگهی‌های مرتبط، اپلیکیشن شما به کاربرها معرفی می‌شوند. در صورت انتخاب کاربر، آدرس مشخص شده در پارامتر Fallback URL برنامهٔ شما برای کاربر باز می‌شود. درخواست ارسالی به Fallback URL به شکل زیر است:
https://your.app.ir
?post_token=<post-token>
&return_url=<return-url>
&...- پارامتر
post_tokenشناسهٔ آگهی مربوطه‌ست.- با کمک این شناسه، میتوانید اطلاعات آگهی را از دیوار دریافت کنید.
- برای دریافت اجازه‌های مربوط به این آگهی، از این شناسه استفاده کنید.
- برای استفاده از قابلیت‌های مرتبط با این آگهی (مثل اضافه کردن افزونه به آگهی) نیز از این شناسه استفاده کنید.
- پارامتر
return_url، آدرسیست که می‌بایست کاربر را بعد از اتمام کار به آن هدایت کنید. - اطلاعات تکمیلی در مورد آگهی نیز در پارامترها درج می‌شوند.
برای توسعه راحت‌تر اپلیکیشن خود میتوانید با استفاده از ngrok نسخه localhost اپلیکیشن خود را به روی یک domain تونل کنید
📖 اطلاعات بیشتر در مورد افزونه‌های آگهی‌ها را اینجا بخوانید.
در مکالمات مرتبط، اپلیکیشن شما به کاربرها (به طرق مختلف) معرفی می‌شود. در صورت انتخاب کاربر، ابتدا درخواستی به شکل زیر به آدرس مشخص شده در پارامتر 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 |
کاربرهایی که به اپلیکیشن دسترسی دارند |
اپ تستی من آماده شده، چه‌طور می‌تونم اون رو در اختیار کاربران دیوار قرار بدم؟
زمانی که از عملکرد صحیح تمام بخش‌های اپ تستی خود روی آگهی‌های تستی (از نظر فنی و همچنین سیاست‌های کنار دیوار) مطمئن شدید، در پنل کنار، تیکتی با محتوای درخواست بررسی اپ ثبت کنید. در صورتی که استفاده از سرویس شما نیاز به پرداخت وجه دارد، لطفاً چند کد تخفیف به همراه تیکت ارسال کنید و یا حساب کاربری شمارهٔ 09306603371 را در سرویس خود شارژ کنید و یا درگاه پرداخت را برای این شماره غیرفعال کنید. تیکت‌های شما حداکثر تا یک روز کاری بعد از زمان ثبت، پاسخ داده خواهند شد و نتیجه‌ی بررسی، حداکثر تا یک هفته‌ی کاری پس از زمان ثبت درخواست، برای شما در پاسخ به تیکت اعلام می‌شود.
در صورتی که اپ دارای مشکلات فنی، پیاده‌سازی و یا نقض قوانین و سیاست‌های کنار دیوار باشد، فهرست موارد در نتیجه‌ی بررسی به شما گزارش می‌شود و تمامی موارد پیش از درخواست بررسی مجدد، باید اصلاح شوند.
در صورتی که مشکلات و یا ایرادات تکراری در فرآیند بررسی مجدد وجود داشته باشد، فرآیند بررسی دفعهٔ سوم، حداقل یک ماه پس از ثبت درخواست بررسی مجدد انجام خواهد
پس از این مرحله، اپ شما آماده‌ی فعال‌شدن و نمایش به کاربران دیوار است. در این مرحله باید اطلاعاتی را برای ما ارسال کنید. این اطلاعات شامل موارد زیر هستند:
- لیست ویجت‌هایی که در افزونه‌ی آگهی استفاده کرده‌اید (در صورتی که اپ شما از نوع افزونه آگهی است)
- شماره‌ی پشتیبانی سرویس‌تان به همراه داخلی آن و ساعات و روزهای فعالیت
- تصویر لوگوی سرویس با ابعاد ۱:۱
ما برای شما یک برنامهٔ آمادهٔ انتشار می‌سازیم و شما میتوانید این برنامه را در داخل پنل کاربری و قسمت «برنامه‌ها» مشاهده کنید. از آن‌جایی که شناسه‌ی یکتا (slug) در این اپ تغییر کرده است، باید برای این اپ کلید API بسازید و app-slug را در هدر OAuth آپدیت کنید بعد از آن میتوانید از طریق تیکت به ما اطلاع دهید تا برنامهٔ شما را روی شهر و دسته‌ٔ تعیین‌شده فعال کنیم
نکته ۱: دسته‌ٔ فعالیت سرویس معمولاً بر اساس نوع خدمات سرویس شما مشخص می‌شود.
نکته ۲: شهر یا شهرهایی که سرویس شما در آن فعال می‌شود، با توجه به تحلیل دیتا از سمت کنار دیوار مشخص می‌شود.
پس از گذشت یک هفته از فعالیت سرویس شما در کنار دیوار، میتوانید درخواست افزایش دسته‌ها و یا شهرهای مربوط به سرویس‌دهی اپ‌تان را از داخل پنل و از طریق تیکت برای ما ارسال کنید تا با توجه به بررسی آمار و ارقام دریافتی در یک هفته‌ی گذشته، به آن رسیدگی شود.
