From c421b4a4eae6f4a34a6c234e6e8a91578ec558c7 Mon Sep 17 00:00:00 2001 From: Saeed Alipoor Date: Sun, 1 Oct 2023 18:43:40 +0330 Subject: [PATCH] Updated text and file names --- ReadMe.md | 63 +++++++++-- access/apikeys.md | 10 -- addons/ReadMe.md | 1 + assets/{assets.md => ReadMe.md} | 62 +++++------ chat/ReadMe.md | 1 + oauth/ReadMe.md | 179 ++++++++++++++++++++++++++++++++ oauth/oauth.md | 89 ---------------- widgets/ReadMe.md | 43 ++++++++ widgets/image.md | 43 ++++---- widgets/index.md | 52 ---------- 10 files changed, 326 insertions(+), 217 deletions(-) delete mode 100644 access/apikeys.md create mode 100644 addons/ReadMe.md rename assets/{assets.md => ReadMe.md} (72%) create mode 100644 chat/ReadMe.md create mode 100644 oauth/ReadMe.md delete mode 100644 oauth/oauth.md create mode 100644 widgets/ReadMe.md delete mode 100644 widgets/index.md diff --git a/ReadMe.md b/ReadMe.md index 5eb817c..967043b 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -1,15 +1,58 @@ # کنار دیوار -**راهنمای برنامه‌نویسانه استفاده از کنار دیوار** +مجموعه‌ای از ابزارها برای اضافه کردن امکانات، خدمات یا اطلاعات بیشتر به قسمت‌هایی از مسیر کاربر در دیوار +## شروع +برای استفاده از امکانات کنار باید در [پنل کنار دیوار](https://kenar.divar.ir/admin) حساب داشته‌باشید. +در پنل کنار، اپلیکیشن مورد نظر خود را اضافه و کلید مورد نیاز را برای صدا زدن APIها دریافت و شروع کنید. +> در حال حاضر امکان ثبت نام عمومی وجود ندارد. -> ⚠️ دردست نوشتار +## اپلیکیشن +هر حساب کاربری می‌تواند اپلیکیشن‌های متفاوتی تعریف کند و از طریق آنها خدمات خود را به کاربران دهد. هر اپلیکیشن می‌تواند نام، تصویر نمایه و نوع خدمت متفاوتی ارائه دهد. -## فهرست مطالب +## کلید API +هر اپلیکیشن می‌تواند کلید‌های API با دسترسی‌های متفاوتی داشته‌باشد و از طریق آن‌ها به کنار دیوار درخواست ارسال کند. +این کلید همراه همهٔ درخواست‌ها که به کنار ارسال می‌شود باید در هدر `x-api-key` ارسال شود. -1. مدیریت دسترسی - - [داکیومنت فنی](./access/apikeys.md) -2. است ها - - [داکیومنت فنی](./assets/assets.md) -3. افزونه ها - - [داکیومنت فنی](widgets/index.md) - - [لینک فیگمای ویجت های افزونه ها](https://www.figma.com/file/ZhhSihwKTjiER1VUDX4ovh/%F0%9F%93%92-Kenar-Docs-(WIP)?type=design&node-id=2-4&mode=design&t=QGrDdUp5agET6as9-0) +برای ساخت کلید جدید یا ویرایش اجازه‌نامه‌های کلیدهای موجود، پس از ورود به پنل، به [صفحهٔ API Keys](https://kenar.divar.ir/admin/info/apikeys) بروید. + +از دکمهٔ `New` برای ساخت کلید جدید استفاده کنید. با انتخاب اپلیکیشن خود و انتخاب دسترسی‌های لازم، یک کلید جدید بسازید. +* از هدر `x-api-key` برای ارسال کلید استفاده کنید. +* کلید API را فقط در زمان ساخت می‌توانید ببینید، پس در نگهداری آن دقت کنید. +* فقط دسترسی‌های لازم را به یک کلید دهید. (مسئولیت استفادهٔ نادرست از API و دسترسی‌ها با صاحب اپلیکیشن است) +* هر اپلیکیشن فقط یک کلید با قابلیت استفاده به عنوان کلید OAuth دارد که در قسمت [احرازِ باز](#احرازِ-باز-oauth) توضیح داده‌شده است. + +## افزونه‌ها +به اجزایی که توسط سرویس‌دهنده‌های بیرونی به دیوار اضافه می‌شود افزونه یا Add-on می‌گوییم. در حال حاضر امکان توسعهٔ افزونه برای صفحهٔ آگهی و چت در دسترس است. +### افزونه‌های آگهی +در قسمت‌های مشخصی از صفحهٔ آگهی یا صفحهٔ مدیریت آگهی، می‌توان افزونه درج کرد. جزییات درخواست‌های مربوط به این افزونه‌ها را در صفحهٔ [افزونه‌های صفحهٔ آگهی](addons) ببینید. +### افزونه‌های چت +افزونه‌های چت دیوار بر اساس شرایط (دستهٔ آگهی، شهر آگهی) به کاربران ارائه می‌شود و کاربران هنگام استفاده از یک نوع خدمات (مثلاً ارسال کالا) می‌توانند به اپ یا سایت شما هدایت شوند و خدمت مورد نظر را دریافت کرده و ادامه دهند. +جزییات اتصال سرویس به چت دیوار را در [صفحهٔ افزونه‌های چت](chat) ببینید. +## ویجت‌های دیوار +ویجت‌ها اجزای تشکیل دهندهٔ صفحات در دیوار هستند، که بعضی از آنها را همانطور که در بالا اشاره شد می‌توانید به وسیلهٔ تعریف افزونه، در قسمت‌های مشخصی درج کنید. جزییات ویجت‌ها و روش استفاده از آنها را در [صفحهٔ ویجت‌های دیوار](widegts) ببینید. + +مثال از قراردادن ویجت در درخواست درج افزونه به یک آگهی +```JSON +{ + "widgets": { + "widget_list": [ + { + "widget_type": "LEGEND_TITLE_ROW", + "data": { + "@type": "type.googleapis.com/widgets.LegendTitleRowData", + "title": "ماشین‌باز", + "subtitle": "کارشناسی سریع خودرو" + } + }, + ...moreWidgets + ] + } +} +``` + +## احرازِ باز (OAuth) +برای درخواست اطلاعات یا دسترسی از کاربران دیوار استاندارد [OAuth 2.0](https://oauth.net/2/) ارائه می‌شود. کتابخانه‌های مرتبط برای استفاده از OAuth را [اینجا](https://oauth.net/code/) می‌توانید ببینید. + +برای اطلاع از APIها و روش استفاده از احراز باز، [صفحهٔ احراز باز (OAuth)](oauth) را ببینید. +## منابع و مقادیر عمومی (Assets) +برای دسترسی به مقادیر enum پرکاربرد و معمولاً ثابت دیوار مثل نام شهرها یا دسته‌ها، می‌توانید از API هایی که در [صفحهٔ Assets](assets) توضیح داده‌ایم استفاده کنید. \ No newline at end of file diff --git a/access/apikeys.md b/access/apikeys.md deleted file mode 100644 index 68aee3d..0000000 --- a/access/apikeys.md +++ /dev/null @@ -1,10 +0,0 @@ -# کلید ای پی آی - -برای احراز هویت صدا زننده ای پی آی های دیوار، از کلید ای پی آی استفاده می‌کنیم. برای بدست آوردن کلید جدید یا ویرایش اجازه‌نامه‌های کلیدهای از قبل موجود، به آدرس [پنل کنار دیوار](https://kenar.divar.ir/admin) مراجعه کنید. -در تب کلیدها، در قسمت new میتوانید کلید جدید ایجاد کنید. سپس با انتخاب اپلیکیشن خود از گزینه‌ها و انتخاب پرمیشن‌های لازم برای این کلید، دکمه save را بزنید. - - -- کلید ایجاد شده را فقط یکبار در زمان تولید میتوانید مشاهده کنید -- تنها دسترسی‌هایی که لازم دارید را به یک کلید بدهید (مسئولیت استفاده نامناسب از این دسترسی‌ها با شماست) -- برای صدا زدن ای پی آی مربوطه با کلید، آن را در هدر `x-api-key` قرار دهید -- هر اپلیکیشن فقط یک کلید با قابلیت استفاده بعنوان سیکرت OAuth دارد که در قسمت *احراز هویت باز* توضیح داده شده است diff --git a/addons/ReadMe.md b/addons/ReadMe.md new file mode 100644 index 0000000..7156ce4 --- /dev/null +++ b/addons/ReadMe.md @@ -0,0 +1 @@ +# افزونه‌های صفحهٔ آگهی \ No newline at end of file diff --git a/assets/assets.md b/assets/ReadMe.md similarity index 72% rename from assets/assets.md rename to assets/ReadMe.md index be3a868..57e5ede 100644 --- a/assets/assets.md +++ b/assets/ReadMe.md @@ -4,10 +4,10 @@ منابعی که از دیوار دریافت میکنید کاربرد دارند. برای مثال در جستجوی آگهی برای فیلتر کردن روی مقادیر برند-مدل خودرو از است برند-مدل میتوانید گزینه‌های موجود را دریافت کنید. -> اگرچه مقادیر است به ندرت تغییر میکنند، اما تضمینی برای ثابت ماندن ریسپانس نیست و هر زمان و بدون اطلاع تغییر خواهد کرد. -> اما ساختمان داده دارای تغییر شکننده نخواهد بود. +> اگرچه این مقادیر ثابت هستند و به ندرت تغییر میکنند، اما تضمینی برای ثابت ماندن پاسخ دریافتی نیست و ممکن است هر زمان و بدون اطلاع تغییر کنند. +> البته ساختمان دادهٔ پاسخ، تغییری که باعث بروز خطا شود، نخواهد داشت. -## دسته‌بندی‌ها +## دسته‌ها درخواست @@ -15,9 +15,9 @@ GET https://api.divar.ir/v1/open-platform/assets/category ``` -پاسخ +نمونهٔ پاسخ -```json5 +```JSON { "categories": [ { @@ -41,9 +41,9 @@ GET https://api.divar.ir/v1/open-platform/assets/category GET https://api.divar.ir/v1/open-platform/assets/city ``` -پاسخ +نمونهٔ پاسخ -```json5 +```JSON { "cities": [ { @@ -70,9 +70,9 @@ GET https://api.divar.ir/v1/open-platform/assets/city GET https://api.divar.ir/v1/open-platform/assets/district ``` -پاسخ +نمونهٔ پاسخ -```json5 +```JSON { "districts": [ { @@ -84,13 +84,8 @@ GET https://api.divar.ir/v1/open-platform/assets/district } ``` -برای دریافت محله‌های یک شهر خاص میتوان آنرا از طریق فانکشن زیر دریافت کرد - -```http request -GET https://api.divar.ir/v1/open-platform/assets/district/tehran -``` - -لیست شهرهای دارای محله به شرح زیر است: +### محله‌های یک شهر +می‌توانید محله‌های شهرهای زیر را از آدرسی که در ادامه می‌بینید دریافت کنید: - shiraz - isfahan - rasht @@ -100,20 +95,22 @@ GET https://api.divar.ir/v1/open-platform/assets/district/tehran - ahvaz - mashhad +```http request +GET https://api.divar.ir/v1/open-platform/assets/district/{{city}} +``` -## برندمدل‌ها -ریکوئست +## برند-مدل‌ها + +در دسته‌های `light` برای خودرو و `mobile-phones` برای کالاهای دیجیتال می‌توانید از آدرس زیر لیست برند‌مدل‌ها را دریافت کنید: ```http request GET https://api.divar.ir/v1/open-platform/assets/brand-model/{{category}} ``` -فقط دسته‌بندی‌های `light` و `mobile-phones` دارای برندمدل هستند. - -ریسپانس +نمونهٔ پاسخ -```json5 +```JSON { "brand_models": [ { @@ -131,17 +128,14 @@ GET https://api.divar.ir/v1/open-platform/assets/brand-model/{{category}} ## رنگ‌ها -درخواست +مشابه برند-مدل، برای دسته‌بندی‌های `light` و `mobile-phones` می‌توانید لیست رنگ‌های موجود در دیوار را از آدرس زیر دریافت کنید. ```http request GET https://api.divar.ir/v1/open-platform/assets/color/{{category}} ``` +نمونه پاسخ -فقط دسته‌بندی‌های `light` و `mobile-phones` دارای رنگ هستند. - -پاسخ - -```json5 +```JSON { "colors": [ { @@ -163,9 +157,9 @@ GET https://api.divar.ir/v1/open-platform/assets/color/{{category}} GET https://api.divar.ir//v1/open-platform/assets/internal-storage ``` -پاسخ +نمونهٔ پاسخ -```json5 +```JSON { "internal_storages": [ { @@ -188,9 +182,9 @@ GET https://api.divar.ir//v1/open-platform/assets/ram-memory ``` -پاسخ +نمونهٔ پاسخ -```json5 +```JSON { "ram_memories": [ { @@ -212,9 +206,9 @@ GET https://api.divar.ir//v1/open-platform/assets/ram-memory GET https://api.divar.ir//v1/open-platform/assets/body-status ``` -پاسخ +نمونهٔ پاسخ -```json5 +```JSON { "body_status": [ { diff --git a/chat/ReadMe.md b/chat/ReadMe.md new file mode 100644 index 0000000..2ef3e96 --- /dev/null +++ b/chat/ReadMe.md @@ -0,0 +1 @@ +# افزونه‌های چت دیوار \ No newline at end of file diff --git a/oauth/ReadMe.md b/oauth/ReadMe.md new file mode 100644 index 0000000..be7390c --- /dev/null +++ b/oauth/ReadMe.md @@ -0,0 +1,179 @@ +# احراز باز (OAuth) + +برای درخواست اطلاعات یا دسترسی از کاربران دیوار استاندارد [OAuth 2.0](https://oauth.net/2/) ارائه می‌شود. کتابخانه‌های مرتبط برای استفاده از OAuth را [اینجا](https://oauth.net/code/) می‌توانید ببینید. + +## مراحل فرایند OAuth + +### ارسال کاربر به صفحهٔ درخواست اجازه‌ + +در این استاندارد شروع فرایند از سایت یا اپلیکیشن خارجی(غیر دیوار) است. +ابتدا سایت شما کاربر را به سایت دیوار برای دریافت اجازه ریدایرکت میکند. URL صفحه‌ای که کاربر را به آن هدایت می‌کنید : شده باید به صورت زیر باشد: + +``` +https://open-platform-redirect.divar.ir/oauth?response_type=code&client_id=your-client-id&redirect_uri=your-redirect-url&scope=ADDON_USER_APPROVED__AZTH74V2+USER_PHONE&state=some-random-state +``` +**توضیحات پارامترها** + + + + + + + + + + + + + + + + + + + + + + + + + + + +
پارامترتوضیحات و کارکرد
response_typeنوع ارائهٔ مجوز به سایت
client_idمقدار app slug شما در پنل کنار دیوار
redirect_uriآدرس مورد نظر شما برای هدایت کاربر بعد از پاسخ به درخواست دسترسی‌ها، این URL نباید شامل هیچ پارامتری باشد
scopeمجوز هایی که از کاربر می خواهید دریافت کنید که با استفاده از + جدا شده اند. توضیحات scope
stateطبق استاندارد oauth یک رشته رندوم که هنگام بازگشت کاربر به redirect_uri به عنوان یک پارامتر پاس داده می‌شود. هدف این پارامتر اطمینان از شروع فرایند از سایت خود شماست که می توانید این موضوع را با نگه داشتن state در session نیز حل کنید.
+ + +> میتوانید از `state` برای نگهداری پارامترهای دلخواه خود که امکان نگهداری آنها را در `redirect_uri` نداشتید استفاده کنید. توجه کنید که در ساختار داده خود همچنان پارامتر رندوم را قرار دهید تا سایت شما مورد حمله قرار نگیرد. + +#### توضیحات scope + +در این قسمت می‌توانید درخواست دو نوع مجوز بدهید: + +- **مجوز روی منابع (مثل یک چت یا یک آگهی):‌** + + این نوع مجوز ها روی منابع مشخص هستند که باید `id` منبع مورد نظر را داشته باشید. + + به این شکل که `id` منبع مورد نظر (مثلاً چت یا آگهی) را با `__` در کنار نام دسترسی‌ درخواستی در مقدار scope قرار می‌دهیم. و اگر این دسترسی برای چند مورد متفاوت است با `+` می‌توانند در کنار هم قرار بگیرند. + + +``` +(PERMISSION_SCOPE)__(RESOURCE_ID) +``` + مثال: + + `ADDON_USER_APPROVED__AZTH74V2` + +> این نوع مجوز‌ها بدون `id` کار نمی‌کنند. + +- **مجوز عمومی:** + + + این نوع مجوزها نیازی به ارائهٔ `id` ندارند. مثلاً درخواست دسترسی به شمارهٔ همراه متصل به حساب کاربر. که کافیست نام دسترسی مورد نظر (`USER_PHONE`) را در مقدار scope قرار بدهید. + + +## بازگشت کاربر از صفحهٔ درخواست دسترسی + +بعد از پاسخ کاربر به درخواست دسترسی‌ها، دیوار کاربر را به URL موجود در پارامتر `redirect_uri` هدایت می‌کند و تعدادی پارامتر هم به آن آدرس اضافه می‌کند که در ادامه توضیح داده‌می‌شود. + +مثال از آدرسی که کاربر به آن هدایت می‌شود: + +``` +($redirect_uri)?state=some-random-state&code=c87sDtaqmWwgis7dYyukMqy6KAArNUFkukAPW8O90GmiEJkdmSTWH4KjSkNUP6FZ +``` + +**توضیحات پارامتر ها** + + + + + + + + + + + + + + + + + +
پارامترتوضیحات و کارکرد
codeدر صورتی که کاربر اجازهٔ دسترسی‌های مورد نظر شما را در صفحهٔ درخواست، داده‌باشد، این پارامتر به آدرس صفحهٔ بازگشت اضافه خواهد شد. بنابراین در صورت نبودن این پارامتر می‌توانید پیام خطای لازم را در صفحهٔ خود نمایش دهید.
stateمقدار این پارامتر دقیقاً همان مقداری خواهد بود که به عنوان پارامتر state در آدرس صفحهٔ درخواست قرار داده‌اید.
+ + +## دریافت access token + +در مرحلهٔ آخر با داشتن `code`، `api-key` و `app-slug` می‌توانید درخواست `access-token` بدهید و با استفاده از آن از مجوزهایی که کاربر به شما داده، استفاده کنید. + +نمونهٔ درخواست برای دریافت `access-token` + +```http request +POST https://api.divar.ir/v1/open-platform/oauth/access_token +Content-Type: application/json +x-api-key: {{apikey}} + +{ + "code": "c87sDtaqmWwgis7dYyukMqy6KAArNUFkukAPW8O90GmiEJkdmSTWH4KjSkNUP6FZ", + "client_id": "{{app_slug}}", + "client_secret": "{{oauth_key}}", + "grant_type": "authorization_code", +} +``` + +نمونه پاسخ + +```JSON +{ + access_token: "f2mjqwiYDigBwGYg2baN8toU9fHxqyKTZKFZkAsLTeNXKObOtsdL0B9vobNZ3SrTc9IhNS2rrG4Guuk9hxZLe0iqgoMbS2W7Jd3jaDUsrVM33teFWsISCrhdj88u99jb", + refresh_token: "uXvX61ZI0wA7CDqkkMfGUXQ3VDO0WVDN9nieQ3qWpXAWU6oliDgXVn5d7pep1nAebMsyZmTa7AWBklTEOvrPPmsEaEobnp0tvJKrqaLdTAPwpSEZn9k5xLF4Acdxl18Zk9XJubGIJefbXOdyjJX7i4D4imr4VTJO7W4fASyOAyKgfBceBAnDTP4cKwC9dW9646NUTJKbFdNKtKCOsRQeVFAatfvyBX1lRkDo3j1McbD1a1uQmQWC9futrvSo6T8U", + expires: "1692457372", +} +``` + +### توضیحات مقادیر ارسالی در درخواست access-token + + + + + + + + + + + + + + + + + + + + +
پارامترتوضیحات و کارکرد
codeمقدار پارامتر `code` که در آدرس صفحهٔ بازگشت قرار داده‌شد.
client_idمقدار app slug شما در پنل کنار دیوار
client_secretبرای این قسمت مقدار api-key که از پنل کنار دیوار دریافت کرده‌اید را وارد کنید.
+ +### توضیح پاسخ دریافتی + +- مقدار `access_token` کلید مورد نیاز برای دسترسی به منابع درخواستی از کاربر است که اجازه دسترسیشان را گرفتید. +- مقدار `expires` برابر با مقدار زمان به فرمت [unix](https://en.wikipedia.org/wiki/Unix_time) است و زمان انقضای کلید دریافتی است. + + +حال با استفاده از `access-token` و قراردادن آن در هدر `x-access-token` و همچنین پر کردن هدر `x-api-token` با `api-key` که از پنل کنار دیوار دریافت کرده‌اید، می‌توانید درخواست‌هایی که نیازمند اجازهٔ کاربر هستند را نیز بفرستید. + +```mermaid +sequenceDiagram + participant App as Your App + participant Divar as Divar Servers + App->>+Divar: Redirect to OAuth page + Divar->>-App: Redirect to redirect_uri + + App-->>+Divar: request /ouath/access_token + + Divar-->>-App: access_token + + App-->>Divar: x-access-token: access_token + + activate Divar; +``` \ No newline at end of file diff --git a/oauth/oauth.md b/oauth/oauth.md deleted file mode 100644 index 98f3cf8..0000000 --- a/oauth/oauth.md +++ /dev/null @@ -1,89 +0,0 @@ -# احراز باز (OAuth) - -برای دریافت اطلاعات حساس کاربران دیوار ما از استاندارد OAuth 2.0 استفاده میکنیم. برای دیدن لایبری های مختلف در زبان خود به این [لینک](https://oauth.net/code/) مراجعه کنید. - -## شروع پروسه - -در این استاندارد شروع پروسه از سایت یا اپلیکیشن خارجی(غیر دیوار) است. -در ابتدا سایت شما کاربر را به سایت دیوار برای دریافت اجازه ریدایرکت میکند. url ریدایرکت شده باید به صورت زیر باشد: -``` -https://open-platform-redirect.divar.ir/oauth?response_type=code&client_id=your-client-id&redirect_uri=your-redirect-url&scope=ADDON_USER_APPROVED__AZTH74V2+USER_PHONE&state=some-random-state -``` - -#### توضیحات پارامترها - -- پارامتر ‍`response_type`: نحوه دادن مجوز به سایت خارجی -- پارامتر `client_id`: app slug در پنل کنار -- پارامتر `redirect_uri`: آدرسی که بعد از گرفتن مجوز از کاربر، دیوار کاربر را به آن آدرس ریدایرکت میکند. طبق استاندارد این uri نباید شامل هیچ پارامتری باشد. -- پارامتر ‍`scope`: مجوز هایی که از کاربر می خواهید دریافت کنید که با استفاده از `+` جدا شده اند. -- پارامتر `state`: طبق استاندارد oauth یک رشته رندوم که هنگام برگشت کاربر به redirect_uri به عنوان یه پارامتر پاس داده میشود. هدف این پارامتر صحت سنجی برای سایت خارجی (third party) از این است که پروسه را خودش شروع کرده است. می توانید این موضوع را با نگه داشتن state در session حل کنید. - -> میتوانید از `state` برای نگهداری پارامترهای دلخواه خود که امکان نگهداری آنها را در `redirect_uri` نداشتید استفاده کنید. توجه کنید که در ساختار داده خود همچنان پارامتر رندوم را قرار دهید تا سایت شما مورد حمله قرار نگیرد. - -#### توضیحات scope - -دو نوع مجوز وجود دارد: - -- مجوز روی منابع:‌ - این نوع مجوز ها روی منابع خاص هستند شما باید یک `id` از منبع مورد نظر داشته باشید. به طور مثال برای `ADDON_USER_APPROVED` که افزونه تایید شده کاربر می باشد، شما باید توکن اگهی که برای کاربر است را به همراه آن بفرستید. - به طور مثال اگر توکن اگهی ‍‍`AZTH74V2` باشد مجوز می شود`ADDON_USER_APPROVED__AZTH74V2`(با `__` جدا کنید به شکل زیر) -``` -(PERMISSION_SCOPE)__(RESOURCE_ID) -``` - -**نکته**:‌ مجوز هایی که نیاز به منبع دارند بدون `id` کار نمیکنند! - -- مجوز بدون منابع: - این نوع مجوزها نیاز به `id` ندارند به طور مثال `USER_PHONE` که مجوز شماره همراه کاربر را میدهد. - -## بازگشت کاربر به redirect_uri -بعد از گرفتن اجازه از کاربر دیوار کاربر را به redirect_uri به همراه تعداد پارامتر برمیگرداند. به طور مثال: -``` -($redirect_uri)?state=some-random-state&code=c87sDtaqmWwgis7dYyukMqy6KAArNUFkukAPW8O90GmiEJkdmSTWH4KjSkNUP6FZ -``` - -### توضیحات پارامتر ها - -- پارامتر `code`: این پارامتر در صورتی داده می شود که کاربر مجوز ها درخواست شده را تایید کند و در صورت عدم تایید کاربر این پارامتر برگردانده نمی شود. -- پارامتر `state`: همانطور که پیش تر توضیح داده شد همان پارامتری است که هنگام شروع داده می شود تا مطمئن شوید خودتان پروسه را شروع کردید. - -## گرفتن access token -برای استفاده از مجوز هایی که کاربر به شما میدهد به یک کلید `access_token` نیاز دارید. برای دریافت این کلید باید از رکوئست زیر استفاده کنید. -```http request -POST https://api.divar.ir/v1/open-platform/oauth/access_token -Content-Type: application/json -x-api-key: {{apikey}} - -{ - "code": "c87sDtaqmWwgis7dYyukMqy6KAArNUFkukAPW8O90GmiEJkdmSTWH4KjSkNUP6FZ", - "client_id": "{{app_slug}}", - "client_secret": "{{oauth_key}}", - "grant_type": "authorization_code", -} -``` -نمونه پاسخ -```json5 -{ - "access_token":"f2mjqwiYDigBwGYg2baN8toU9fHxqyKTZKFZkAsLTeNXKObOtsdL0B9vobNZ3SrTc9IhNS2rrG4Guuk9hxZLe0iqgoMbS2W7Jd3jaDUsrVM33teFWsISCrhdj88u99jb", - "refresh_token":"uXvX61ZI0wA7CDqkkMfGUXQ3VDO0WVDN9nieQ3qWpXAWU6oliDgXVn5d7pep1nAebMsyZmTa7AWBklTEOvrPPmsEaEobnp0tvJKrqaLdTAPwpSEZn9k5xLF4Acdxl18Zk9XJubGIJefbXOdyjJX7i4D4imr4VTJO7W4fASyOAyKgfBceBAnDTP4cKwC9dW9646NUTJKbFdNKtKCOsRQeVFAatfvyBX1lRkDo3j1McbD1a1uQmQWC9futrvSo6T8U", - "expires":"1692457372" -} -``` -### توضیح رکوئست - -- مقدار `code` باید برابر با همان پارامتر `code` ای باشد که کاربر پس از بازگشت از دیوار به همراه خود دارد -- مقدار `client_id` همان `app_slug` است که در پنل کنار تعریف شده است. -- مقدار `client_secret` برابر با `api-key` است که در پنل کنار OAuth Enabled آن Yes باشد. -- مقدار `grant_type` باید `authorization_code` باشد زیرا در حال حاضر کنار فقط از این نوع OAuth پشتیبانی می کند. - -### توضیح ریسپانس - -- مقدار `access_token` کلید مورد نیاز برای دسترسی به منابع با مجوز داده شده ی کاربر میباشد. -- مقدار `expires` برابر با مقدار زمان به فرمت [unix](https://en.wikipedia.org/wiki/Unix_time) است. - -حال با استفاده از access token و قرار دادن آن در هدر `x-access-token` می توانید به api های مربوط به OAuth که مجوز آن را دارید رکوئست بزنید. - - -**نکته**: قرار دادن `x-api-token` با مجوز های مربوطه نیز اجباری است یعنی داشتن `access_token` به تنهایی کافی نیست. - -![OAuth Diagram](./oauth_diagram.jpg) diff --git a/widgets/ReadMe.md b/widgets/ReadMe.md new file mode 100644 index 0000000..a0ec656 --- /dev/null +++ b/widgets/ReadMe.md @@ -0,0 +1,43 @@ +# ساختار ویجت های دیوار (Widgets) +ویجت‌ها اجزای تشکیل دهندهٔ صفحات در دیوار هستند، که برخی از آنها را می‌توانید در افزونه‌های خود استفاده کنید.. +برای درج یک ویجت در یک افزونه باید نام ویجت و جزییات مرتبط با آن را همراه درخواست درج افزونه ارسال کنید. + +به عنوان مثال ، در ریکوئست ساخت اند آن میتواند این اطلاعات وجود داشته باشد: + +مثال از قراردادن ویجت در درخواست درج افزونه به یک آگهی +```JSON +{ + "widgets": { + "widget_list": [ + { + "widget_type": "LEGEND_TITLE_ROW", + "data": { + "@type": "type.googleapis.com/widgets.LegendTitleRowData", + "title": "ماشین‌باز", + "subtitle": "کارشناسی سریع خودرو" + } + }, + ...moreWidgets + ] + } +} +``` + +اطلاعاتی که درون `widget_list` قرار دارد ، لیستی از ویجت ها و ساختار داده‌هایی است که دیوار برای نمایش اطلاعات پشتیبانی می‌کنند. +هر ویجت ویژگی‌های خود را دارد که در قسمت `data` می‌توان تعیینشان کرد. مثلاً با `true` گذاشتن مثدار `divider` برای ویجت‌هایی که این ویژگی را دارند، می‌توان یک خط جدا کننده زیر ویجت نمایش داد. + +ویژگی‌های هر ویجت، شرایط اعتبار سنجی و توضیحات مرتبط هر کدام در صفحات زیر دسترس‌ است. +# لیست ویجت های کنار دیوار +- [DESCRIPTION_ROW](./description_row.md) +- [EVALUATION_ROW](./evaluation_row.md) +- [LEGEND_TITLE_ROW](./legend_title_row.md) +- [TITLE_ROW](./title_row.md) +- [SUBTITLE_ROW](./subtitle_row.md) +- [WIDE_BUTTON_BAR](./wide_button_bar.md) +- [SELECTOR_ROW](./selector_row.md) +- [EVENT_ROW](./event_row.md) +- [GROUP_INFO_ROW](./group_info_row.md) +- [SCORE_ROW](./score_row.md) + +### ویجت‌های دارای تصویر +برای اطلاع از درج تصویر در ویجت‌هایی که امکان نمایش تصویر در قسمتی از خود را دارند، [صفحهٔ تصاویر در ویجت‌ها](./image.md) را ببینید diff --git a/widgets/image.md b/widgets/image.md index ff7d452..c080688 100644 --- a/widgets/image.md +++ b/widgets/image.md @@ -1,23 +1,23 @@ -# عکس در ویجت ها +# درج تصویر در ویجت‌ها -تعدادی از ویجت ها از عکس پشتیبانی می‌کنند. برای قرار دادن عکس در این ویجت ها باید ابتدا آن‌ها اپلود کنید. فلوی ثبت عکس در ویجت به صورت زیر می باشد. +تعدادی از ویجت‌های دیوار امکان نمایش تصویر در قسمتی از خود را دارند. برای اضافه کردن تصویر به ویجت مورد نظر ابتدا باید تصویر را آپلود کنید و سپس شناسهٔ آت را در مشخصات ویجت قرار دهید. ```mermaid sequenceDiagram participant Third-Party participant Kenar participant Divar Image Service - Third-Party->>Divar Image Service: Upload Binary Image - Divar Image Service->>Third-Party: Creates temporary image and returns its ID - Third-Party->>Kenar: Uses the given ID in some widget + Third-Party->>+Divar Image Service: Upload Binary Image + Divar Image Service->>-Third-Party: Creates temporary image and returns its ID + Third-Party->>+Kenar: Uses the given ID in some widget Kenar->>Divar Image Service: Sends Make Permanent request with the given ID Divar Image Service->>Kenar: Makes Permanent image and returns a new ID - Kenar->>Third-Party: Creates widget with the new image ID and responds with success + Kenar->>-Third-Party: Creates widget with the new image ID and responds with success ``` -### اپلود عکس +### آپلود تصویر -در ابتدا با یک رکوئست PUT باینری عکس خود را به صورت زیر اپلود کنید. (ترجیحا فرمت عکس ها jpeg باشد) +در ابتدا با یک رکوئست PUT باینری فایل تصویر خود را به صورت زیر آپلود کنید. (ترجیحا فرمت عکس ها jpeg باشد) ```http request PUT /v2/image-service/open-platform/image.jpg HTTP/1.1 @@ -27,20 +27,22 @@ Content-Length: 22 "" ``` -دفت شود که`image.jpg` انتهای url یک نام ثابت است و ربطی به نام عکس اپلودی ندارد!(در تمام رکوئست ها `image.jpg` بگذارید) -پس از ارسال رکوئست پاسخ زیر دریافت می‌شود. +دفت شود که`image.jpg` انتهای url یک نام ثابت است و ربطی به نام عکس آپلودشده ندارد! (در تمام رکوئست ها `image.jpg` بگذارید) + +پس از ارسال درخواست، چنین پاسخی دریافت می‌شود. ```json5 { - "image_name": "57c76b48-d381-4b8a-b34f-355f6869b6ed.jpg" + image_name: "57c76b48-d381-4b8a-b34f-355f6869b6ed.jpg", } ``` -### ساخت افزونه +### درج تصویر در افزونه -حال در رکوئست ساخت افزونه از id عکس دریافت شده استفاده میکنیم. +حال در محل مورد نظرتان برای درج تصویر، `id` دریافتی از درخواست قبلی را قرار دهید. +برای مثال در نمونه درخواست زیر در ویجت `EVENT_ROW` تصویر مورد نظرمان را قرار دادیم. ```http request POST //v1/open-platform/add-ons/post/AZqfx5i2 HTTP/1.1 @@ -78,13 +80,10 @@ Content-Length: 901 } ``` -همانطور که مشاهده می کنید در ویجت `EVENT_ROW` عکسمان رو قرار داده ایم. - -در ویجت های عکس دار هم همانند `Legend Title Row` می‌توانید از `logo` برای استفاده از لوگو اپتون تو کنار استفاده کنید. - +علاوه بر درج تصویر دلخواه می‌توان به جای `{id}` مقدار `logo` را به عنوان `image_url` فرستاد تا لوگوی اپ شما که در پنل کنار دیوار قابل تنظیم است، در ویجت درج شود. ### ویجت های عکس دار -- [EVENT_ROW](./event_row.md) -- [IMAGE_CAROUSEL_ROW](./image_carousel_row.md) - -در صورتی که هنگام ساخت افزونه پیام `one or more widgets not allowed` رو دریافت می‌کنید به این منظور است که شما دسترسی ساخت یک نوع ویجت از ویجت هایی که در درخواستتان هست را ندارید برای دریافت دسترسی با پشتیبانی در ارتباط باشید. - +