مرجع Tile

يعرض product="tile" خريطة أساس من Kaleidr تُحدَّد بمعرّف النمط. يستبدل SDK مفتاحك القابل للنشر بجلسة Tile، ثم يستبدل محتوى العنصر المستهدف بإطار iframe يحمّل https://map-embed.kaleidr.com/?style=<style>. تُرسَم الخريطة داخل ذلك الإطار.

تستخدم Kaleidr الجلسة للتحقق من المفتاح ونطاق صلاحياته وأصل صفحتك، واحتساب تحميل الخريطة، وتقديم خريطة الأساس الافتراضية لمؤسستك. لا تُمرَّر الجلسة إلى الإطار. يحتوي عنوان URL للإطار على معرّف النمط وإعدادات الكاميرا المرسلة (camera وpitch وbearing) فقط؛ ولا يحتوي على مفتاح قابل للنشر أو رمز جلسة، ولا تستخدم الخريطة داخله أياً منهما لإرسال الطلبات.


المفتاح	مفتاح قابل للنشر (`kld_pk_live_…`). مطلوب.
النطاق	`maps`، وهو موجود في المفاتيح الجديدة افتراضياً.
الخطة	جميع الخطط، بما فيها Free.
مكان العرض	إطار iframe من `https://map-embed.kaleidr.com`.
القياس	تحميل خريطة واحد لكل جلسة Tile.
سياسة أمان المحتوى	`script-src https://cdn.kaleidr.com` و`connect-src https://api.kaleidr.com` و`frame-src https://map-embed.kaleidr.com`.

للاطلاع على الخطوات، راجع استخدام خريطة أساس Kaleidr.

التثبيت

باستخدام العنصر:

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="tile"
             publishable-key="kld_pk_live_…"
             style-id="kaleidr-morning"
             center="-0.1276,51.5072" zoom="11"
             style="display:block; height:480px"></kaleidr-map>

من JavaScript:

const handle = Kaleidr.mount('#basemap', {
  product: 'tile',
  publishableKey: 'kld_pk_live_…',
  styleId: 'kaleidr-morning',
  center: [-0.1276, 51.5072],
  zoom: 11,
});

الخيارات

خيار التثبيت	السمة	النوع	الافتراضي	مطلوب	الوصف
`product`	`product`	`'tile'`	لا شيء	نعم	اختيار Tile.
`publishableKey`	`publishable-key`	سلسلة نصية	لا شيء	نعم	مفتاح `kld_pk_…` يملك النطاق `maps`. يُرفض مفتاح الخادم (`kld_sk_…`) في المتصفح قبل إرسال أي طلب.
`styleId`	`style-id`	سلسلة نصية	خريطة الأساس الافتراضية للمؤسسة إن وُجدت	موصى به	معرّف نمط من الجدول أدناه أو عنوان `https://` كامل لمستند النمط. يجب أن يطابق `^[A-Za-z0-9._:/~-]{1,200}$`.
`center`	`center`	`[longitude, latitude]`؛ وصيغة السمة `"longitude,latitude"`	العرض الافتراضي للنمط	لا	المركز الأولي.
`zoom`	`zoom`	رقم	العرض الافتراضي للنمط	لا	مستوى التكبير الأولي؛ يُتجاهل عند التثبيت إذا لم يُمرَّر `center`.
`pitch`	`pitch`	رقم، بالدرجات	العرض الافتراضي للنمط	لا	الميل الأولي.
`bearing`	`bearing`	رقم، بالدرجات	العرض الافتراضي للنمط	لا	الدوران الأولي.
`apiBase`	`api-base`	URL	`https://api.kaleidr.com/inference-api`	لا	وجهة تبادل الجلسة. يجب تضمين المسار `/inference-api`. لا يلزم ضبطه في الإنتاج.
`viewerBase`	`viewer-base`	URL	`https://map-embed.kaleidr.com`	لا	أصل تحميل iframe، ولا يُستخدم إلا الأصل. هذا مضيف صفحة الخريطة لا بياناتها.
`base`	`base`	URL	`https://cdn.kaleidr.com`	لا	الأصل الذي يحمّل SDK منه `tile.js`. تُقبل فقط الأصول المدرجة في تجاوز العنوان الأساسي.
`enabled`	`flag`	قيمة منطقية	لا شيء	لا	التحكم الخاص بكل تثبيت في بوابة التفعيل.

لا تؤثر shareId وtheme وmap وmapTarget وcontained وtileBase في تثبيت Tile.

معرّفات الأنماط

`style-id`	المظهر
`kaleidr-morning`	مشرق: أرضية بيضاء ومياه سماوية وطرق بيضاء.
`kaleidr-afternoon`	أرضية متوسطة اللون، ونباتات خضراء، وطرق رمادية.
`kaleidr-evening`	الساعة الذهبية: درجات رملية وزيتونية دافئة.
`kaleidr-night`	كحلي وفحمي داكنان، مع طرق سريعة كهرمانية.
`kaleidr-plain`	مساحة بيضاء مع الحدود وتسميات الأماكن. تظهر المباني ثلاثية الأبعاد ابتداءً من مستوى التكبير 15.
`kaleidr-editorial`	ألوان فترة ما بعد الظهر دون تسميات، للخرائط الصغيرة أو الزخرفية.

القواعد:

يجب أن تتطابق المعرّفات تماماً، مع مراعاة حالة الأحرف. لا توجد أسماء مختصرة بديلة.
عند حذف styleId، يستخدم التضمين خريطة الأساس الافتراضية للمؤسسة المرسلة مع الجلسة. إن لم توجد، يعرض iframe الرسالة "Couldn't find a map id in the URL.". مرّر styleId كي لا يعتمد العرض على إعداد الحساب.
يتقدم styleId المصرّح به دائماً على إعداد المؤسسة الافتراضي.
ينتج عن معرّف غير موجود إطار فارغ ورسالة kaleidr-embed:error برمز maplibre_error.
تمنع الأحرف غير المسموح بها التثبيت. تعرض وحدة التحكم [kaleidr:tile] Kaleidr tile: invalid style "…" — must match ^[A-Za-z0-9._:\/~-]{1,200}$.. لذا لا يمكن أن يحتوي URL النمط على سلسلة استعلام.

الكاميرا

تبدأ الكاميرا بالعرض الافتراضي للنمط، ويستبدل كل حقل ترسله قيمته المقابلة. إذا لم يحدد النمط عرضاً افتراضياً، تُعرض الكرة الأرضية كلها: المركز [0, 20]، والتكبير 2، من دون ميل أو دوران.

تأتي قيمة خط الطول أولاً في center؛ فالإحداثيان [-0.1276, 51.5072] يشيران إلى لندن.
عند التثبيت، لا يُطبَّق zoom إلا إذا أُرسل center معه.
يعمل pitch وbearing بمعزل عن center.

التحجيم

يشغل iframe كامل عرض عنصر التثبيت بنسبة 100%، دون حدود، مع زوايا مستديرة.
يشغل ارتفاع العنصر بنسبة 100% إذا كان له ارتفاع وقت التثبيت؛ وإلا فيكون ارتفاعه ثابتاً عند 500 بكسل.
يستبدل التثبيت أبناء العنصر ويضبط position:relative (إن لم يكن هناك موضع مضمن) وoverflow:hidden.
تكون قيمة <kaleidr-map> هي display:block افتراضياً، ولذلك يسري height. حدد ارتفاعاً له. تتضمن الأمثلة أيضاً display:block لدعم Safari الأقدم من 16.4، حيث يبقى العنصر مضمن العرض دون ذلك.

المقبض

يعيد Kaleidr.mount المقبض بشكل متزامن. راجع مصفوفة المقابض لجميع المنتجات.

العضو	في Tile
`handle.product`	`'tile'`
`handle.setCamera(camera)`	يحرك الخريطة.
`handle.setStyle(style)`	يبدّل خريطة الأساس في مكانها.
`handle.setTheme(theme)`	غير مدعوم؛ يصدر تحذيراً دون تنفيذ إجراء.
`handle.destroy()`	يزيل iframe ويوقف تجديدات الجلسة.

`setStyle(style)`

handle.setStyle('kaleidr-night');

يقبل معرّف نمط أو عنوان URL كاملاً، ويعالجه كما يُعالَج styleId عند التثبيت. لا يُعاد تحميل iframe، وتبقى الكاميرا في موضعها، ولا يُحتسب تحميل خريطة جديد. Tile هو المنتج الوحيد الذي يدعم setStyle.

`setCamera(camera)`

handle.setCamera({
  center: [2.3522, 48.8566], // [longitude, latitude]
  zoom: 12,
  pitch: 45,
  bearing: -20,
  duration: 1200,            // milliseconds
});

الحقل	النوع	الوصف
`center`	`[number, number]`	خط الطول، خط العرض.
`zoom`	رقم	مستوى التكبير. على خلاف التثبيت، يعمل `zoom` هنا دون `center`.
`pitch`	رقم	الميل بالدرجات.
`bearing`	رقم	الدوران بالدرجات.
`duration`	رقم	مدة الحركة بالمللي ثانية. عند حذفه أو ضبطه على `0`، ينتقل فوراً دون حركة.

كل الحقول اختيارية، وتحتفظ الحقول المحذوفة بقيمها الحالية.

توقيت الاستدعاءات

يمكنك استدعاء setCamera وsetStyle في أي وقت بعد رجوع Kaleidr.mount، حتى في السطر التالي. تُحفظ الاستدعاءات التي تحدث قبل جاهزية الخريطة داخل iframe وتُطبَّق بالترتيب عند إعلان الجاهزية. تُحفظ أحدث 256 عملية استدعاء. إذا لم تعلن الخريطة جاهزيتها خلال انتظار محدود، عادةً بعد 10 ثوانٍ من تحميل الإطار، تُرسَل الاستدعاءات رغم ذلك مع تحذير في وحدة التحكم. ليس عليك انتظار kaleidr-embed:ready. ولضبط العرض والنمط عند الفتح، تظل خيارات التثبيت هي الطريقة المباشرة كي تفتح الخريطة عليهما من البداية.

سمات العنصر بعد التثبيت

في <kaleidr-map product="tile"> مثبَّت، يؤدي تغيير center أو zoom أو pitch أو bearing إلى تحريك الخريطة دون حركة انتقالية. ولا يؤثر تغيير style-id أو publishable-key أو أي سمة أخرى.

رسائل iframe

// The basemap drew for the first time.
{ type: 'kaleidr-embed:ready', id: string, source: 'tile' }

// Something failed to draw.
{ type: 'kaleidr-embed:error', id: string, code: 'maplibre_error', message: string }

// No style: none was passed, and the organization has no default basemap.
{ type: 'kaleidr-embed:error', id: null, code: 'no_id', message: string }

تشير id إلى معرّف النمط أو عنوانه الذي أرسلته. عند no_id تكون null، ويعرض الإطار "Couldn't find a map id in the URL."، ولا يرسل ready.

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://map-embed.kaleidr.com') return;
  if (event.source !== target.querySelector('iframe')?.contentWindow) return;
  const msg = event.data;
  if (msg?.type === 'kaleidr-embed:ready') onReady(msg);
  if (msg?.type === 'kaleidr-embed:error') onError(msg);
});

تُرسل ready مرة واحدة عند رسم الخريطة، ولا تُرسل مجدداً بعد setStyle.
قد تصل maplibre_error عدة مرات قبل ready أو بعدها.
يُنشأ iframe باستخدام loading="lazy"، فلا تصل الرسائل حتى يقترب من المنطقة المرئية.
لا تُنتج الجلسة المرفوضة أي رسالة لعدم إنشاء iframe؛ راجع خطأ وحدة التحكم.
ينشر iframe رسائل أخرى يبدأ حقل type فيها بـ kaleidr-embed:. يستخدمها SDK لربط لوحة Chat بالخريطة، وليست جزءاً من العقد العام.

الجلسة وقياس الاستخدام

يرسل SDK لكل تثبيت Tile

POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions
x-api-key: kld_pk_live_…
content-type: application/json

{"product":"tile"}

ويتلقى

{
  "session_token": "kld_sess_live_…",
  "expires_in": 900,
  "product": "tile",
  "basemap_style_id": "kaleidr-morning"
}

basemap_style_id هو معرّف خريطة الأساس الافتراضية لمؤسستك، وتكون قيمته null إذا لم تُحدد.

كل تبادل ناجح باستخدام "product":"tile" يحتسب تحميل خريطة واحداً على مؤسستك. يحدث التبادل:

متى	العدد
عند التثبيت	1
قبل انتهاء الجلسة بـ 90 ثانية طوال استمرار التثبيت	1 في كل مرة
عندما تصبح علامة التبويب مرئية مجدداً والجلسة منتهية أو ستنتهي خلال 90 ثانية	1
عند التثبيت مجدداً بعد `destroy()` أو إعادة إدراج عنصر أُزيل	1

ملاحظات:

تُعاد محاولة تجديد الجلسة الفاشلة كل 30 ثانية؛ ولا تُزال الخريطة المعروضة بالفعل.
إن فشل التبادل الأول، يفشل التثبيت ولا يُعاد تلقائياً. أعد التثبيت للمحاولة.
يوقف destroy() عمليات التجديد.
لا تُحتسب حركات الكاميرا أو تبديل الأنماط أو تفاعلات الزوار.

يُرفض تبادل جلسة Tile بسبب أول حالة تنطبق من الحالات التالية:

الحالة	`detail`	السبب
403	`publishable_key_required`	المفتاح ليس قابلاً للنشر.
403	`origin_required`	لم يتضمن الطلب أصلاً.
403	`origin_not_allowed`	أصل الصفحة غير موجود في قائمة الأصول المسموحة للمفتاح.
403	`product_not_allowed`	المفتاح مقيّد بمنتجات أخرى.
403	`tier_capability_not_allowed`	لا تسمح الخطة بهذا المنتج.
403	`insufficient_scope`	يفتقر المفتاح إلى النطاق `maps`.
429	`map_load_quota_exceeded`	نُفدت حصة تحميل الخرائط للمؤسسة.

قبل هذه الفحوص، تعيد المنصة 404 sessions_disabled إذا عُطل تبادل الجلسات، أو قد تعيد 503 sessions_not_configured عند حدوث عطل. لا ينتج أي منهما عن مفتاحك. القائمة الكاملة في الأخطاء.

إقران Tile مع Chat

يمكن لتثبيت Chat التحكم في عنصر Tile. امنح عنصر Tile معرّف id، واجعل سمة Chat map-target (خيار التثبيت mapTarget) تشير إليه:

<div style="position:relative">
  <kaleidr-map id="basemap" product="tile" publishable-key="kld_pk_live_…"
               style-id="kaleidr-morning"
               style="display:block; height:560px"></kaleidr-map>

  <kaleidr-map product="chat" publishable-key="kld_pk_live_…" contained
               map-target="#basemap"
               style="display:block; position:absolute; inset:0; z-index:1; pointer-events:none"></kaleidr-map>
</div>

على خريطة Tile، يضع المساعد دبابيس مع نوافذ منبثقة، ويوجّه الكاميرا نحو الأماكن، ويرسم المسارات وحدود مناطق مثل المدن ومواقع المركبات الحية. تجد الخطوات في استخدام خريطة أساس Kaleidr، والتخطيط في المظهر والتخطيط، والخيارات في مرجع Chat.

رسائل وحدة التحكم

الرسالة	المعنى
`[kaleidr] <kaleidr-map> requires product="chat\|viewer\|editor\|tile"`	لا يحتوي العنصر على `product` صالح، لذلك لا يُثبَّت.
`[kaleidr:tile] kaleidr session exchange failed (<status>)`	رُفض التبادل. اقرأ السبب في استجابة علامة تبويب الشبكة: `detail` لرمز 403 و`map_load_quota_exceeded`، و`error` لرمز 429 `rate_limited`.
خطأ CORS في `…/sdk/sessions` يليه خطأ جلب `[kaleidr:tile]`	المفتاح غير معروف أو أُلغي، أو الأصل غير مسموح. لا تحتوي استجابة الأصل المرفوض على ترويسات CORS، فيخفيها المتصفح عن SDK.
`[kaleidr:tile] Kaleidr: a server key (kld_sk_…) must never be used in the browser — it is a standing secret. Use your publishable key (kld_pk_…) here and keep the server key server-side.`	مُرر مفتاح خادم؛ لا يُرسل أي طلب.
`[kaleidr:tile] Kaleidr tile: invalid style "…" — must match ^[A-Za-z0-9._:\/~-]{1,200}$.`	يحتوي `styleId` على محرف غير مسموح به.
`[kaleidr:tile] mount target not found: <selector>`	لم يجد `Kaleidr.mount` عنصراً يطابق المحدد.
`[kaleidr:tile] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/tile.js`	تعذر تحميل حزمة Tile.
`[kaleidr] setTheme() is not supported on product "tile" — the call is a no-op. …`	استدعيت طريقة لا يدعمها Tile.
`[kaleidr] setStyle() IS supported on product "tile", but this mount did not expose it, so the call did nothing. …`	تستخدم الصفحة نسخة قديمة مخزنة مؤقتاً من `tile.js`. أعد التحميل دون الذاكرة المؤقتة.

غير متاح

إضافة علامات أو طبقات أو نوافذ منبثقة خاصة بك إلى الخريطة.
أحداث النقر أو حركة الكاميرا أو التحديد.
قراءة موضع الكاميرا الحالي.
استخدام الخريطة دون iframe.

التثبيت​

الخيارات​

معرّفات الأنماط​

الكاميرا​

التحجيم​

المقبض​

setStyle(style)​

setCamera(camera)​

توقيت الاستدعاءات​

سمات العنصر بعد التثبيت​

رسائل iframe​

الجلسة وقياس الاستخدام​

إقران Tile مع Chat​

رسائل وحدة التحكم​

غير متاح​

صفحات ذات صلة​