چگونه یک نقشه حرکت را در سایت خود ادغام کنیم؟

برای ادغام یک نقشه حرکت در سایت خود بدون ساخت کامل رابط کاربری، از iframe ROOTE استفاده کنید. این embed می‌تواند جستجوی شهر و فیلترهای مناسب صفحه را دریافت کند: دوچرخه برای راهنمای دوچرخه، دستشویی برای راهنمای WC، اتوبوس و تراموا برای حمل‌ونقل.

مثال‌های این راهنما از embed.roote.ai استفاده می‌کنند که دامنه‌ی موجود در راهنماهای ROOTE است. مستندات کلی همچنین ادغام map.roote.ai را شرح می‌دهد و پارامترهای دوربین را از پارامترهای جستجوی کامل متمایز می‌کند.

افزودن یک iframe واکنش‌گرا

این بخش جستجوی دوچرخه در بوردو را با بزرگنمایی ۱۵ باز می‌کند. URL در کد ساخته شده است؛ عنوان iframe محتوای آن را برای خوانندگان صفحه نمایش توصیف می‌کند. این عنوان را به زبان صفحه خود تطبیق دهید.

<iframe
  title="Carte ROOTE — vélos à Bordeaux"
  src="https://embed.roote.ai/?q=Bordeaux&amp;modes=bicycle&amp;zoom=15"
  width="100%"
  height="480"
  loading="lazy"
  allow="geolocation"
  style="display:block; width:100%; min-height:360px; border:0; border-radius:16px;"
></iframe>

در ویژگی HTML، جداکننده‌های & به صورت & نوشته می‌شوند. عرض ۱۰۰٪ از عرض ظرف پیروی می‌کند. ارتفاعی قابل استفاده روی موبایل حفظ کنید و از قرار دادن کنترل‌های ضروری خارج از ناحیه قابل مشاهده خودداری کنید.

انتخاب حالت‌های متناسب با صفحه

این مقادیر مربوط به مسیر embed ROOTE متصل به خانواده‌های حرکت، خدمات و ترانزیت هستند. آنها جایگزین پارامترهای REST نمی‌شوند: خدمات از types و ترانزیت از modes استفاده می‌کند. نقشه متمرکز روی یک شهر تضمین نمی‌کند که هر خانواده در آن نتایجی داشته باشد.

تمایز دوربین و مبدأ جستجو

lat و lon دوربین را موقعیت‌دهی می‌کنند. این‌ها به تنهایی، در قرارداد مستند شده نقشه، برای ایجاد جستجوی نزدیکی کافی نیستند. برای بازیابی یک جستجوی شناخته شده، از search_lat، search_lon و search_label به همراه modes و zoom استفاده کنید.

https://embed.roote.ai/?search_lat=44.8416106&search_lon=-0.5810938&search_label=Bordeaux&zoom=15&modes=bus,tram

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

مستندسازی پارامترهای نقشه ROOTE

ساخت URL بدون از دست دادن کاراکترهای خاص

از URL و URLSearchParams به جای اتصال دستی استفاده کنید. این شامل رمزگذاری فاصله‌ها، حروف با اعراب و جداکننده‌ها است. این کد برای مرورگر است و آدرس iframe را از یک مکان ورودی می‌سازد.

const embedUrl = new URL('https://embed.roote.ai/');
embedUrl.searchParams.set('q', 'Place des Quinconces, Bordeaux');
embedUrl.searchParams.set('modes', 'bicycle,toilets');
embedUrl.searchParams.set('zoom', '15');
document.querySelector('iframe').src = embedUrl.toString();

حفظ زمینه تا نقشه کامل

پیوند به map.roote.ai باید وضعیت فعلی جستجو را اگر می‌دانید حفظ کند. ساختن مجدد URL بدون پارامترهای آن شهر، حالت‌ها یا بزرگنمایی را از دست می‌دهد. یک شی URL مشترک در به‌روزرسانی‌های صفحه خود نگه دارید.

const fullMapUrl = new URL('https://map.roote.ai/');
fullMapUrl.search = embedUrl.search;
const link = document.querySelector('[data-open-map]');
link.href = fullMapUrl.toString();
link.target = '_blank';
link.rel = 'noopener noreferrer';

این کد پارامترهای شناخته شده توسط صفحه والد را حفظ می‌کند. اگر کاربر جستجو را داخل iframe تغییر دهد، والد نمی‌تواند URL آن را مستقیماً روی دامنه‌ای دیگر بخواند. برای بازیابی این وضعیت، باید مکانیزمایی به طور آشکار اجرا و مستند شود، مثلاً تبادل postMessage با اعتبارسنجی مبدأ. نام رویداد سفارشی اختراع نکنید اگر توسط embed ارائه نشده است.

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

allow="geolocation" اجازه می‌دهد iframe موقعیت را درخواست کند، با رعایت رضایت و سیاست‌های مجوز سایت. رد کردن باید اجازه دهد جستجوی شهر قابل استفاده بماند. تقاضا برای موقعیت نباید بلافاصله هنگام ورود به صفحه انجام شود مگر اینکه کاربر آن را انتخاب کرده باشد.

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

بررسی نتیجه و وضعیت خطا

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

تمایز بین نبود نتیجه و خطای API

انتخاب بین embed، API و MCP

مثال راهنما برای یافتن دستشویی

سؤالات متداول

آیا باید کلید API در iframe گذاشت؟

URLهای عمومی که اینجا نشان داده شده‌اند کلید API ندارند. رمز عبور را در URL embedding یا کد کلاینت قرار ندهید.

آیا zoom=15 شعاع جستجو را افزایش می‌دهد؟

zoom نمای نقشه را تنظیم می‌کند. آن را با شعاع درخواست API برابر ندانید؛ پارامترهای جستجوی رابط کاربری استفاده شده را بررسی کنید.

آیا والد تغییرات داخل iframe را می‌داند؟

والد پارامترهایی را می‌داند که ارسال می‌کند. تغییرات داخلی نیازمند مکانیزمی برای تبادل مستند شده بین دو دامنه است.