رهرو للمطورين
ضمّن الخريطة والاتجاهات وصفحات الأماكن في موقعك ببضعة أسطر من الكود.
بداية سريعة
أضف السكربت مرة واحدة في الصفحة، ثم عنصرًا بالسمة 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="ar" style="height:360px"></div>
<div data-rahro-place="x3f8k2m1q9" data-lang="ar" style="height:320px"></div>التضمين عبر iframe
ثلاث صفحات جاهزة: خريطة بدبوس، ومسار بين نقطتين، وبطاقة مكان. تُحدَّد اللغة بـ ?lang=، فيكفي رمز واحد لكل صفحات موقعك.
<iframe src="https://map.rasadweb.ir/embed/map?ll=35.6997,51.338&z=15&lang=ar"
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=ar -->
<!-- https://map.rasadweb.ir/embed/place/{id}?lang=ar -->حزمة @rahro/maps
بناء عناوين التضمين وتركيب iframe وتوقيع عناوين الصور الثابتة. يمكن استيرادها دون npm من /sdk/v1/maps.mjs؛ مكوّنات الويب: <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: "ar" });
</script>
<!-- web components (after widget.js) -->
<rahro-map lat="35.6997" lon="51.338" zoom="15" lang="ar"></rahro-map>
<rahro-directions to-lat="35.7" to-lon="51.4" to-name="..." lang="ar"></rahro-directions>
<rahro-place-card place="x3f8k2m1q9" lang="ar"></rahro-place-card>مفاتيح API
أنشئ مفتاحًا قابلًا للنشر (pk_) للتضمين في المتصفح، ومفتاحًا سريًا (sk_) للخادم ولتوقيع الصور الثابتة. يُعرض المفتاح الكامل مرة واحدة فقط.
يمكن تزوير Origin؛ الحماية الحقيقية للمفتاح العام هي الحصة وحد المعدل. احتفظ بالمفتاح السري على خادمك فقط.
صورة خريطة ثابتة
GET /v1/static/map مع key وskid (معرّف أحد مفاتيحك السرية) وsig. التوقيع HMAC-SHA256 بترميز base64url على سلسلة الاستعلام المرتبة دون sig، ومفتاح التوقيع هو تجزئة SHA-256 (hex) لمفتاحك السري؛ لا يظهر المفتاح السري نفسه في العنوان أبدًا. وقّع على الخادم فقط.
حاليًا الاستجابة صورة 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