پرش به مطلب اصلی

نقاط تماس (Touch Points)

«نقاط تماس» یا Touch Points، مکان‌های مشخصی در پلتفرم دیوار (وب‌سایت و اپلیکیشن‌ها) هستند که افزونه شما می‌تواند در آنجا به کاربران نمایش داده شود و تعامل را شروع کند.

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

نقاط تماس موجود​

افزونه شما می‌تواند در یک یا چند مورد از نقاط تماس زیر فعال شود:

۱. آگهی من (MY_POST)​

  • کجا نمایش داده می‌شود؟ این نقطه تماس، افزونه شما را در سه بخش کلیدی مرتبط با آگهی‌ها لیست می‌کند:
    • صفحه مدیریت آگهی‌های کاربر
    • صفحه پیش‌نمایش آگهی (قبل از انتشار)
    • بخش افزونه‌های پیشنهادی (بعد از ثبت موفق آگهی)
  • کاربرد: ارائه سرویس‌های مرتبط با یک آگهی خاص (مانند اعتبارسنجی، خدمات حمل‌ونقل، کارشناسی و...).

۲. دیوار من (MY_DIVAR)​

  • کجا نمایش داده می‌شود؟ در صفحه «دیوار من»، بخش «افزونه‌های دیوار».
  • کاربرد: ارائه سرویس‌های عمومی که لزوماً به یک آگهی خاص وابسته نیستند (مانند مدیریت کلی خدمات، گزارش‌گیری و...).

۳. پنل حرفه‌ای (DIVAR_PRO)​

  • کجا نمایش داده می‌شود؟ در پنل مدیریت کسب‌وکارها (دیوار حرفه‌ای)، بخش «امکانات بیشتر».
  • کاربرد: ارائه سرویس‌های تخصصی برای کاربران حرفه‌ای و کسب‌وکارها.

۴. چت (CHAT)​

  • کجا نمایش داده می‌شود؟ در صفحه چت، منوی «افزونه‌ها».
  • کاربرد: ارائه ابزارها و سرویس‌هایی که به مکالمه بین خریدار و فروشنده کمک می‌کنند (مانند هماهنگی برای بازدید، پرداخت امن و...).

فعال‌سازی و مدیریت نقاط تماس​

فرآیند فعال‌سازی نقاط تماس بسته به وضعیت اپلیکیشن شما (تستی یا منتشر شده) متفاوت است.

اپلیکیشن‌های در حال توسعه (تستی)​

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

اپلیکیشن‌های منتشر شده (Production)​

برای اپلیکیشن‌های منتشر شده، فرآیند فعال‌سازی نیازمند بررسی توسط تیم کنار است. ۱. در پنل توسعه‌دهندگان به بخش «نقاط تماس» بروید و نقاط مورد نظر خود را انتخاب کنید. ۲. با ثبت تغییرات، یک درخواست پشتیبانی به صورت خودکار برای ما ارسال می‌شود. ۳. پس از بررسی و تأیید، افزونه شما در نقاط تماس درخواستی برای کاربران نهایی فعال خواهد شد.

انواع روش‌های انتقال داده​

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

در این روش، کاربر مستقیماً به لینکی از اپلیکیشن شما (که در پنل به عنوان Fallback URL مشخص کرده‌اید) به همراه پارامترهای لازم در Query String هدایت می‌شود. این روش ساده و سریع است و برای سناریوهایی که نیاز به پردازش سمت سرور قبل از نمایش رابط کاربری ندارند، مناسب است.

نکته

در حال حاضر، این روش انتقال فقط برای نقاط تماس مرتبط با آگهی (MY_POST) در دسترس است.

کاربر به آدرسی مشابه زیر هدایت خواهد شد:

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

پارامترهای کلیدی:

  • post_token: (اختیاری) شناسه یکتای آگهی.

    • با استفاده از این توکن می‌توانید اطلاعات کامل آگهی را از API دیوار دریافت کنید.
    • برای دریافت مجوزهای لازم (مانند ویرایش آگهی) از این توکن استفاده می‌شود.
      توجه

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

  • completion_url: آدرسی که باید کاربر را پس از اتمام کار یا انصراف، به آن بازگردانید. برای جزئیات بیشتر به مستندات تکمیل فرآیند مراجعه کنید.

نکته برای توسعه

برای تست این قابلیت روی سیستم لوکال خود، می‌توانید از ابزاری مانند ngrok استفاده کنید تا localhost شما را روی یک دامنه عمومی در دسترس قرار دهد.

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

مرحله ۱: درخواست از دیوار به سرور شما

ابتدا دیوار یک درخواست POST به آدرسی که در پنل به عنوان Session Initialization URL ثبت کرده‌اید، ارسال می‌کند.

POST https://your.server.ir/initialize_session
Content-Type: application/json
Authorization: {{ Divar Identification Key }}
API-Version: 2

بدنه درخواست (Request Body):

{
  "completion_url": "<completion-url>",
  "post_token": "<post-token>",
  "conversation_id": "<conversation-id>",
  "user_side": "<user-side>",
  "source": "<source>",
  "provider_data": {
    "some_key": {
      "some_other_key": "some_value"
    }
  }
}

توضیح پارامترها و هدرها:

  • Authorization (Header): این هدر حاوی کلید شناسایی دیوار (Divar Identification Key) است که در پنل خود تعریف کرده‌اید. همیشه این هدر را اعتبارسنجی کنید تا مطمئن شوید درخواست از طرف دیوار ارسال شده است.
  • API-Version (Header): نسخه API انتقال داده را مشخص می‌کند. این هدر به شما کمک می‌کند تا در صورت به‌روزرسانی API، بتوانید مهاجرت نرم (Soft Migration) و بدون اختلالی داشته باشید.
  • completion_url: آدرس بازگشت کاربر به دیوار.
  • post_token: شناسه آگهی (در صورت وجود).
  • conversation_id: شناسه چت (در صورت شروع از نقطه تماس چت).
  • user_side: نقش کاربر در تعامل را مشخص می‌کند. مقادیر ممکن:
    • SUPPLY: کاربر، آگهی‌دهنده (فروشنده) است.
    • DEMAND: کاربر، بازدیدکننده آگهی (خریدار) است.
  • source: نقطه‌ای که تعامل از آن شروع شده است (مثلاً CHAT, POST_ADDON).
  • provider_data: یک آبجکت JSON که می‌تواند حاوی داده‌های اضافی باشد که شما هنگام تعریف یک اکشن سفارشی (مانند open_server_link) مشخص کرده‌اید.

مرحله ۲: پاسخ سرور شما به دیوار

سرور شما پس از دریافت و پردازش درخواست بالا، باید یک پاسخ JSON حاوی یک URL برای هدایت کاربر برگرداند. این URL می‌تواند شامل توکن جلسه (Session Token) یا پارامترهای مورد نیاز برای رابط کاربری شما باشد.

پاسخ مورد انتظار (Expected Response):

{
  "url": "https://your.app.ir/start-flow?session_id=xyz123"
}

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