kaleidr.js — المحمّل

تقوم علامة script واحدة بتثبيت window.Kaleidr وتعريف عنصر <kaleidr-map>:

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

الواجهة عبارة عن محمّل خفيف. وهي مسؤولة فقط عن: الإصدار، والإعدادات، وتحميل السكربت، وسجل المنتجات، وتمرير المفاتيح، واختيار طريقة الدمج، ودورة حياة التركيب، وتوحيد الأخطاء، وعلامة dormancy. أما السلوك الفعلي لكل منتج فيوجد في حزمته الخاصة، ويتم تحميلها بشكل كسول من URL عند أول استخدام.

Kaleidr.mount(target, options) → KaleidrHandle

const handle = Kaleidr.mount('#chat', {
  product: 'chat',
  publishableKey: 'kld_pk_live_…',
  map: myMap,
});

تعيد handle بشكل متزامن بينما يتم تحميل حزمة المنتج في الخلفية؛ ويتم وضع الاستدعاءات قبل التحميل في قائمة انتظار وتنفيذها عند الجاهزية.

الخيارات

الخيار	النوع	ملاحظات
product	'chat' | 'viewer' | 'editor' | 'tile'	مطلوب. يحدد الحزمة + طريقة الدمج الافتراضية.
publishableKey	string	مفتاح متصفح publishable (kld_pk_live_…). مطلوب لـ chat/editor/tile؛ يجب ألا يتلقى viewer مفتاحًا ويُرفض بـ product_not_allowed إذا تم تمرير مفتاح. يقوم SDK بتبادل المفتاح بجلسة قصيرة العمر مرتبطة بالأصل وقت التشغيل.
apiKey	string	اسم بديل مهمل لـ publishableKey. يقبل أيضًا مفتاح kld_live_… القديم.
shareId / mapId	string	لـ Viewer فقط. مطلوب — حذفه يؤدي إلى خطأ عند تحميل الحزمة.
styleId	string	لـ Tile/editor. Tile: معرّف نمط خريطة أساس Kaleidr (الافتراضي هو لوحة viewer الافتراضية). Editor: معرّف نمط أو URL كامل للنمط — عند حذفه يتم تطبيق الإعداد الافتراضي المخزن للمؤسسة، ثم kaleidr-morning.
map	map instance	Chat: خريطة Mapbox / MapLibre / Google الحية داخل الصفحة التي سيتم الإرفاق بها.
mapTarget	string	Chat: محدد CSS لعنصر الخريطة المضيف (المسار التعريفي).
contained	boolean	لـ Chat فقط. الافتراضي false. يثبت اللوحة داخل عنصر التركيب بدلًا من جعلها عائمة على document.body — وبدونه تخرج اللوحة من التخطيط وتبدو معطلة.
center zoom		الكاميرا الأولية (viewer، editor، tile).
pitch bearing		الكاميرا الأولية في viewer وeditor وtile.
theme	object or JSON object string	مجموعة رموز CSS (مثل { '--kd-accent': '#2da84a' }). يقبل Chat أيضًا تحديثًا مباشرًا عبر handle. السمات النصية المسماة غير مدعومة؛ وتمرير سلسلة نصية مجردة يسجل تحذيرًا ويتم تجاهلها.
doorway	'iframe' | 'attach'	خيار تجاوز — يستبدل القيمة الافتراضية للمنتج.
base	string	تجاوز أصل CDN الذي تُحمّل منه الحزم (dev / self-host).
viewerBase	string	Viewer/tile: الأصل الذي يحمّل منه iframe. مختلف عن base — لا يشير iframe أبدًا إلى CDN.
tileBase	string	Editor: CDN البلاطات المستخدم لحل قيم styleId في الكتالوج. الافتراضي https://tile.kaleidr.com.
apiBase	string	يجب أن يتضمن مسار الخدمة. الافتراضي https://api.kaleidr.com/inference-api؛ أصل مجرد مثل https://api.kaleidr.com يُرجع 404 عند تبادل الجلسة. ينطبق على chat وeditor وtile — أي منتج ينفذ تبادل جلسة.
enabled	boolean	تجاوز dormancy لكل عملية تركيب.

KaleidrHandle

شكل handle هو superset — ينفذ كل منتج فقط الأساليب التي يمكنه دعمها. راجع Handle matrix لمعرفة ما يفعله كل أسلوب مع كل منتج.

interface KaleidrHandle {
  product: 'chat' | 'viewer' | 'editor' | 'tile';
  // Always present.
  destroy(): void;
  // Viewer, editor, tile: real. Chat: NO-OP (chat does not drive the map).
  setCamera?(camera): void;
  // Chat: live update (real). Editor: mount-time only; live update is a
  // follow-up SDK release. Viewer/tile: not applicable.
  setTheme?(theme): void;
  // Tile only. Not exposed on any other product.
  setStyle?(styleId: string): void;
}

استدعاء أسلوب غير مدعوم حاليًا يسجل تحذير [kaleidr] ثم يعيد — ولا يرمي المحمّل خطأ. هذا السلوك جزء من العقد في الاسم المستعار الرئيسي v1.

Kaleidr.init()

يقوم بترقية أي <kaleidr-map> موجود بالفعل في DOM. يتم استدعاؤه تلقائيًا عند التحميل؛ واستدعه بعد إدخال العناصر ديناميكيًا.

Kaleidr.enable(on = true)

يكون SDK فعالًا افتراضيًا — لا تحتاج إلى تمكين أي شيء، ويعمل quickstart كما هو مكتوب.

توجد enable() كمفتاح إيقاف: تمرير false يمنع mount() من تحميل أي حزمة، بحيث يمكنك وضع التضمينات خلف لافتة موافقة أو تعطيلها في صفحة دون إزالة الترميز. المفتاح نفسه متاح أيضًا عبر window.__KALEIDR_EMBED_ENABLED__ = false (قبل تشغيل السكربت) أو سمة flag / خيار enabled لكل عملية تركيب.

Kaleidr.version

سلسلة إصدار المحمّل.

تجاوز قاعدة CDN

للتطوير المحلي أو الاستضافة الذاتية، وجّه المحمّل إلى أصل آخر:

<script>window.__KALEIDR_EMBED_BASE__ = 'https://cdn-dev.kaleidr.com';</script>