رهرو برای توسعه‌دهندگان
نقشه، مسیریابی و صفحهٔ مکان را با چند خط کد در سایت خود جاسازی کنید.
شروع سریع
اسکریپت را یک بار در صفحه بگذارید و هر جا نقشه می‌خواهید یک عنصر با data-rahro-map اضافه کنید. widget.js کمتر از ۵ کیلوبایت فشرده است، فقط iframe می‌سازد و تا وقتی عنصر به دید نیامده چیزی بار نمی‌کند.
<script src="https://map.rasadweb.ir/sdk/v1/widget.js" async></script>
<div data-rahro-map data-lat="35.6997" data-lon="51.3380" data-zoom="15"
data-label="..." data-lang="fa" style="height:360px"></div>
<div data-rahro-place="x3f8k2m1q9" data-lang="fa" style="height:320px"></div>جاسازی با iframe
سه صفحهٔ آماده: نقشه با سنجاق، مسیر بین دو نقطه و کارت مکان. زبان با ?lang= تعیین می‌شود؛ یک کد برای همهٔ صفحه‌های سایت شما کافی است.
<iframe src="https://map.rasadweb.ir/embed/map?ll=35.6997,51.338&z=15&lang=fa"
width="100%" height="360" style="border:0" loading="lazy"></iframe>
<!-- https://map.rasadweb.ir/embed/directions?from=lat,lon&to=lat,lon&to_name=...&lang=fa -->
<!-- https://map.rasadweb.ir/embed/place/{id}?lang=fa -->SDK @rahro/maps
ساخت آدرس جاسازی، سوار کردن iframe و امضای آدرس تصویر ایستا. بدون npm هم از /sdk/v1/maps.mjs قابل import است؛ Web Componentها: <rahro-map>، <rahro-directions> و <rahro-place-card>.
<div id="map" style="height:360px"></div>
<script type="module">
import { mountMap } from "https://map.rasadweb.ir/sdk/v1/maps.mjs";
mountMap(document.getElementById("map"), { base: "https://map.rasadweb.ir", lat: 35.6997, lon: 51.338, zoom: 15, lang: "fa" });
</script>
<!-- web components (after widget.js) -->
<rahro-map lat="35.6997" lon="51.338" zoom="15" lang="fa"></rahro-map>
<rahro-directions to-lat="35.7" to-lon="51.4" to-name="..." lang="fa"></rahro-directions>
<rahro-place-card place="x3f8k2m1q9" lang="fa"></rahro-place-card>کلیدهای API
برای جاسازی در مرورگر کلید publishable (pk_) و برای سرور و امضای تصویر ایستا کلید secret (sk_) بسازید. کلید کامل فقط یک بار نمایش داده می‌شود.
Origin را می‌توان جعل کرد؛ محافظ اصلی کلید publishable سهمیه و محدودیت نرخ است. کلید secret را فقط روی سرور نگه دارید.
تصویر ایستای نقشه
GET /v1/static/map با key، skid (شناسهٔ یکی از کلیدهای secret شما) و sig. امضا HMAC-SHA256 به‌صورت base64url روی رشتهٔ پرس‌وجوی مرتب‌شده بدون sig است و کلید امضا، هش SHA-256 (hex) کلید secret شماست؛ خود کلید secret هرگز در آدرس نمی‌آید. امضا را فقط روی سرور بسازید.
فعلاً پاسخ یک تصویر SVG ساده است (شبکه، سنجاق، برچسب و مختصات)، نه کاشی‌های واقعی نقشه؛ رندر واقعی با tileserver-gl بعداً اضافه می‌شود و آدرس و امضا تغییر نمی‌کند.
// Node 18+ — sign on your server, never in the browser.
import { createHash, createHmac } from "node:crypto";
const secret = createHash("sha256").update(process.env.RAHRO_SECRET_KEY).digest("hex");
const query = new URLSearchParams({
ll: "35.6997,51.338", z: "15", w: "600", h: "400",
key: "pk_...", // your publishable (or secret) key
skid: "<secret key id>", // id of the secret key, shown on the keys page
}).toString();
const canonical = query.split("&").sort().join("&");
const sig = createHmac("sha256", secret).update(canonical).digest("base64url");
const url = `https://map.rasadweb.ir/v1/static/map?${query}&sig=${sig}`;oEmbed
صفحه‌های مکان لینک کشف oEmbed دارند؛ ابزارهایی مثل وردپرس با چسباندن آدرس صفحه، کارت مکان را خودکار جاسازی می‌کنند. نقطهٔ دسترسی: GET /oembed?url=
GET https://map.rasadweb.ir/oembed?url=https%3A%2F%2Fmap.rasadweb.ir%2Fplace%2Fx3f8k2m1q9&maxwidth=600