Hogyan integráljunk mobiltérképet a weboldalba?

Mobiltérkép integrálásához weboldalán anélkül, hogy az egész felületet felépítené, használjon ROOTE iframe-et. Az embed fogadhat városkeresést és az oldalhoz illeszkedő szűrőket: kerékpárokhoz kerékpáros útmutatót, WC-khez mellékhelyiség kalauzt, buszhoz és villamoshoz tömegközlekedési információkat.

A jelen útmutató példái az embed.roote.ai használatán alapulnak, amely a ROOTE útmutatókban alkalmazott integrált domain. Az általános dokumentáció bemutatja a map.roote.ai integrációját is, és megkülönbözteti a kamera paramétereket a teljes keresési paraméterektől.

Reszponzív iframe hozzáadása

Ez a blokk Bordeaux kerékpáros keresését nyitja meg 15-ös zoommal. Az URL a kódban van összeállítva; az iframe címe leírja a tartalmat képernyőolvasók számára. Igazítsa ezt a címet oldalának nyelvéhez.

<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 attribútumban az & jel helyett & írható. A 100%-os szélesség a konténer szélességét követi. Tartson meg mobilon használható magasságot, és kerülje, hogy alapvető vezérlők a látható területen kívül legyenek.

A megfelelő módok kiválasztása az oldalhoz

Ezek az értékek a ROOTE embed útvonalaihoz kapcsolódnak, a mobilitás, szolgáltatások és közlekedés kategóriákhoz. Nem helyettesítik a REST paramétereket: a Szolgáltatások típusokat használ, míg a Közlekedés módokat. Egy városközpontú térkép nem garantálja, hogy minden kategóriában található eredmény.

Kamera és keresési kiindulópont megkülönböztetése

lat és lon a kamera helyzetét adják meg. Ezek önmagukban nem elegendőek a közeli kereséshez a dokumentált térkép szerződés szerint. Ismert keresés helyreállításához használja a search_lat, search_lon és search_label paramétereket a módokkal és zoommal együtt.

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

A fenti koordináták Bordeaux referencia pontja, nem a felhasználó helye. Ha kameraparamétereket is ad meg, megjeleníthet más területet, miközben megtartja a pontot a távolságok számításához. Ezt csak szándékos elválasztás esetén tegye.

ROOTE térkép paraméterek dokumentációja

URL építése speciális karakterek elvesztése nélkül

Használja az URL és URLSearchParams objektumokat a kézi összefűzés helyett. Ezek kódolják a szóközöket, ékezeteket és elválasztókat. Ez a kód böngészőhöz készült, a beírt hely alapján készíti az iframe címét.

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();

A teljes térkép kontextusának megőrzése

A map.roote.ai linknek vissza kell adnia a keresés aktuális állapotát, ha ismert. Egy URL újraalkotása paraméterek nélkül elveszti a várost, módokat vagy zoomot. Tartson közös URL objektumot az oldal frissítéseihez.

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';

Ez a kód megőrzi a szülő oldal által ismert paramétereket. Ha a felhasználó módosítja a keresést az iframe-ben, a szülő nem olvashatja közvetlenül az URL-t más domainen. Az állapot visszakéréséhez implementálni és dokumentálni kell egy mechanizmust, pl. postMessage alapú kommunikációval az eredet ellenőrzésével. Ne találjon ki eseménynévhez nincs támogatott embed nevet.

Helymeghatározás és mobil interakciók kezelése

allow="geolocation" engedi az iframe-nek helyzet kérését, a felhasználó beleegyezésével és az oldal jogosultsági szabályzata szerint. Elutasítás esetén a városkeresésnek továbbra is működnie kell. Ne kérje a pozíciót oldal betöltéskor, ha a felhasználó nem választotta ezt.

Cikk esetén a térkép aktívvá tétele elkerülheti, hogy görgetés vagy zoom gyűjtse a gesztusokat olvasás közben. A vezérlésnek billentyűzetes elérésűnek és egyértelműen megnevezettnek kell maradnia. Ellenőrizze az irányváltozást és a keskeny képernyőt, ne csak az asztali változatot.

Eredmény és hibaállapotok ellenőrzése

Tesztelje minden szűrőt, ismert várost, kevés adatot tartalmazó területet, érvénytelen keresést és elérhetetlen kategóriát. Egy marker nélküli térkép önmagában nem árulja el, hogy üres-e a keresés vagy hibás az API. Tartsa meg az embed üzeneteit és elérhetővé tegye a teljes térképet.

Eredmény hiány és API hiba megkülönböztetése

Embed, API vagy MCP választása

Példa útmutató WC keresésre

Gyakran ismételt kérdések

Szükséges-e API kulcs az iframe-be?

Itt bemutatott nyilvános URL-ek nem tartalmaznak API kulcsot. Ne helyezzen el titkos kulcsot embed URL-ben vagy klienskódban.

A zoom=15 növeli a keresési sugárt?

A zoom csak a nézetet állítja. Ne tévessze össze az API lekérdezés sugarával; ellenőrizze az adott felület keresési paramétereit.

Ismeri-e a szülő az iframe-ben történt változtatásokat?

Ismeri a neki átadott paramétereket. A belső módosítások dokumentált kommunikációs mechanizmust igényelnek a két domain között.