kaleidr.js، المحمّل

kaleidr.js هو السكربت الذي تبدأ منه جميع تضمينات Kaleidr. يعرّف الكائن العام window.Kaleidr والعنصر المخصص <kaleidr-map>. وهو صغير ولا يتضمن مكتبة خرائط أو شيفرة المنتجات. عند تركيب منتج، يحمّل حزمته من شبكة CDN نفسها ويمرر الخيارات إليه.

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

لا توجد حزمة npm. علامة script هي الطريقة الوحيدة لتحميل SDK. للاستخدام مع React وNext.js وVue وTypeScript راجع التكامل مع أطر العمل.

تحميل السكربت

السؤال	الإجابة
أين توضع العلامة؟	في أي مكان. تُركّب عناصر <kaleidr-map> سواء سبقت العلامة أم جاءت بعدها.
متى أستطيع استدعاء Kaleidr.mount؟	بعد تنفيذ السكربت. مع علامة <script src> عادية، يمكن لأي سكربت تالٍ استدعاؤها.
هل يمكن استخدام async أو defer؟	نعم للعناصر. أما Kaleidr.mount فيجب انتظار حدث load للعلامة؛ إذ لا يوجد window.Kaleidr قبله.
كم مرة؟	مرة واحدة لكل صفحة.
هل يمكن إضافة integrity؟	لا. يُحدّث الملف في مكانه، ولن تتطابق البصمة الثابتة مع الإصدار التالي. راجع إصدارات CDN.
هل يعمل على الخادم؟	لا؛ يحتاج إلى window وdocument. في التطبيقات التي تُعرض من الخادم حمّله في المتصفح فقط.

تحميل السكربت باستخدام async ثم تركيب المنتج عند وصوله:

<div id="map" style="height:480px"></div>
<script>
  const s = document.createElement('script');
  s.src = 'https://cdn.kaleidr.com/embed/v1/kaleidr.js';
  s.async = true;
  s.onload = () => {
    Kaleidr.mount('#map', { product: 'viewer', shareId: 'YOUR_MAP_ID' });
  };
  document.head.appendChild(s);
</script>

window.Kaleidr

العضو	الوصف
Kaleidr.mount(target, options)	يركّب منتجاً داخل عنصر ويُرجع مقبض تحكم.
Kaleidr.init()	يهيّئ عناصر <kaleidr-map> الموجودة بالفعل في المستند. نادراً ما يلزم استدعاؤه.
Kaleidr.enable(on)	يفعّل عمليات التركيب اللاحقة أو يعطّلها.
Kaleidr.version	سلسلة إصدار المحمّل للتشخيص.

Kaleidr.mount(target, options)

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

المعامل	النوع	الوصف
target	محدد CSS أو HTMLElement	العنصر المستهدف. يُحلّ المحدد مرة واحدة باستخدام document.querySelector.
options	كائن	مطلوب. راجع الخيارات.

يعيد مقبض تحكم.

طريقة العمل:

• يعود فوراً. يحدث تبادل الجلسة وتحميل حزمة المنتج في الخلفية. تُحفظ استدعاءات المقبض أثناء ذلك وتُنفّذ بالترتيب عندما يصبح المنتج جاهزاً. في Viewer وTile يكون ذلك عندما تُبلغ الخريطة داخل iframe بجاهزيتها؛ لذا يعمل setCamera حتى عند استدعائه مباشرة بعد mount.
• لا يرمي استثناء عند فشل التركيب. يؤدي غياب الهدف أو تعذّر تحميل الحزمة أو رفض الجلسة أو المعرّف غير الصالح إلى تسجيل خطأ يتضمن [kaleidr:<product>] في وحدة التحكم. يُعاد المقبض مع ذلك، لكن أساليبه لا تفعل شيئاً. الاستدعاء الوحيد الذي يرمي استثناء هو Kaleidr.mount('#map') من دون كائن خيارات؛ إذ ينتج TypeError.
• لا يعيد إشعاراً إلى شفرتك. لا توجد Promise تنتظرها ولا دالة رد. راجع معرفة نجاح التركيب.
• تركيب واحد لكل هدف. استدعِ handle.destroy() للمقبض السابق قبل تركيب آخر. يمكن التدمير وإعادة التركيب في العنصر نفسه بأمان حتى أثناء تحميل الأول؛ فلا يضيف التركيب المدمّر شيئاً ولا يؤثر في الثاني.

الخيارات

الخيار	النوع	الافتراضي	المنتجات	الوصف
product	'chat' | 'viewer' | 'editor' | 'tile'	لا شيء؛ مطلوب	الكل	يختار المنتج المطلوب تركيبه.
publishableKey	سلسلة	لا شيء	chat، editor، tile	مفتاحك القابل للنشر kld_pk_…. يستبدله SDK بجلسة قصيرة العمر ويمرر الجلسة وحدها إلى المنتج. لا تمرّره إلى Viewer. يُرفض مفتاح الخادم (kld_sk_…) قبل أي طلب.
shareId	سلسلة	لا شيء	viewer، chat	Viewer: معرّف الخريطة المنشورة. Chat من دون مفتاح: الخريطة المنشورة التي يوفر مالكها المحادثة.
mapId	سلسلة	لا شيء	viewer	اسم بديل لـ shareId عند عدم توفير shareId.
styleId	سلسلة	خريطة الأساس الافتراضية للمنظمة	tile، editor	معرّف نمط مثل kaleidr-morning أو عنوان URL كامل للنمط.
map	نسخة خريطة نشطة	لا شيء	chat	كائن الخريطة الذي يتحكم فيه المساعد: Mapbox GL JS أو MapLibre GL JS أو Google Maps أو Leaflet. راجع الخرائط المدعومة. احذفه عند استخدام لوحة محادثة فقط.
mapTarget	محدد CSS	لا شيء	chat	عنصر <kaleidr-map> من نوع Viewer أو Tile ليقوده المساعد بدلاً من map.
contained	منطقي	false	chat	يثبت اللوحة داخل الهدف الذي يجب ضبط موضعه وأبعاده. افتراضياً تظهر نافذة ثابتة في أعلى يسار الشاشة.
lang	سلسلة	قيمة <html lang> الصحيحة للصفحة، وإلا الإنجليزية	chat	لغة الإجابات بوسم BCP 47 مثل en أو ko أو pt-BR. راجع لغة Chat.
title	سلسلة	عنوان اللوحة الخاص بها	chat	عنوان رأس نافذة المحادثة؛ السمة في العنصر هي chat-title.
placeholder	سلسلة	النص الإرشادي الافتراضي للوحة	chat	النص الظاهر داخل حقل الإدخال قبل الكتابة.
center	[longitude, latitude]	افتراضي المنتج	viewer، tile، editor	مركز البدء.
zoom	رقم	افتراضي المنتج	viewer، tile، editor	مستوى التكبير الأولي. لا يسري في Viewer وTile إلا مع center.
pitch	رقم	افتراضي المنتج	viewer، tile، editor	الميل الأولي بالدرجات.
bearing	رقم	افتراضي المنتج	viewer، tile، editor	الدوران الأولي بالدرجات.
theme	كائن أو سلسلة JSON لكائن	لا شيء	chat، editor	Chat: خصائص CSS مخصصة مثل { '--highlight-color': '#0b5fff' }. Editor: مفاتيح السمة الـ17. تُتجاهل السلسلة غير الصالحة بصفتها JSON مع تحذير.
enabled	منطقي	لا شيء	الكل	تحكم لكل تركيب في بوابة التفعيل، يُقرأ عند التركيب فقط.
base	URL	https://cdn.kaleidr.com	الكل	أصل تحميل حزم المنتجات. يُستخدم الأصل فقط وتُطلب الحزم منه في /embed/v1/. تُقبل فقط الأصول المسموحة ضمن تجاوز عنوان الأساس، وتُتجاهل غيرها مع تحذير.
viewerBase	URL	https://map-embed.kaleidr.com	viewer، tile	أصل iframe؛ يُستخدم الأصل فقط.
apiBase	URL	https://api.kaleidr.com/inference-api	chat، editor، tile	وجهة تبادل الجلسة وطلبات المنتج. يجب تضمين /inference-api؛ فالأصل وحده يعيد 404.
tileBase	URL	https://tile.kaleidr.com	editor	المضيف الذي تُحلّ عنده معرّفات الأنماط.

ملاحظات:

• apiKey اسم بديل مهمل لـ publishableKey.
• خيارات …Base الأربعة مخصصة لاختبار عمليات نشر أخرى ولا حاجة لها في الإنتاج. يغيّر base موضع الحزم فقط؛ وتبقى صفحة الخريطة وAPI ومضيف خريطة الأساس لدى Kaleidr ما لم تغيّر كلاً منها على حدة.
• تُقرأ lang وtitle وplaceholder عند التركيب. لتغييرها، دمّر التركيب ثم أعده.
• تُتجاهل الخيارات التي لا يستخدمها المنتج من دون رسالة.

تجاوز عنوان الأساس

تحدد base (الخيار والسمة) والمتغير العام window.__KALEIDR_EMBED_BASE__ أصل حزم المنتجات. لا يُقبل التجاوز إلا إذا كان الأصل أحد الآتي:

الأصل المقبول	مثال
شبكة Kaleidr CDN	https://cdn.kaleidr.com
الأصل الذي حُمّل منه kaleidr.js نفسه	يُخدم kaleidr.js من https://static.example.com وتكون base مساوية لـ https://static.example.com.
أصل الصفحة نفسها	الصفحة على https://www.example.com/… وbase مساوية لـ https://www.example.com.

تُتجاهل أي قيمة أخرى. يستمر التركيب، وتُحمّل الحزم من CDN الافتراضية، وتظهر في وحدة التحكم رسالة تحذير لهذه القيمة:

[kaleidr] base "https://other.example.net" is IGNORED — bundles load from https://cdn.kaleidr.com. A base must be the Kaleidr CDN, the origin kaleidr.js was loaded from, or this page's own origin.

يجب أن يكون المتغير العام سلسلة نصية؛ وتُتخطى الأنواع الأخرى من دون رسالة. تعمل الاستضافة الذاتية وفق هذه القاعدة عند خدمة المحمّل والحزم من الأصل نفسه.

إعدادات الكاميرا الافتراضية حسب المنتج:

المنتج	الكاميرا الافتراضية
viewer	المشهد الذي حفظه مؤلف الخريطة.
tile	المشهد الافتراضي للنمط، وإلا العالم كله.
editor	المركز [0, 0]، والتكبير 2، والميل 0، والدوران 0.
chat	لا ينطبق؛ لا يُنشئ Chat خريطة.

تفاصيل كل منتج في: Chat، وViewer، وTile، وEditor.

مقبض التحكم

يعيد Kaleidr.mount بنية المقبض نفسها لجميع المنتجات.

interface KaleidrHandle {
  readonly product: 'chat' | 'viewer' | 'editor' | 'tile';
  setCamera(camera: {
    center?: [number, number]; // [longitude, latitude]
    zoom?: number;
    pitch?: number;
    bearing?: number;
    duration?: number;         // milliseconds
  }): void;
  setTheme(theme: string | Record<string, string>): void;
  setStyle(style: string): void;
  destroy(): void;
}

كل الأساليب موجودة على كل مقبض، لكن تأثيرها يعتمد على المنتج:

الأسلوب	chat	viewer	editor	tile
setCamera(camera)	تحذير	نعم	نعم	نعم
setTheme(theme)	نعم	تحذير	تحذير	تحذير
setStyle(style)	تحذير	تحذير	تحذير	نعم
destroy()	نعم	نعم	نعم	نعم

«تحذير» يعني أن الاستدعاء لا يفعل شيئاً وتظهر رسالة في وحدة التحكم.

[kaleidr] setCamera() is not supported on product "chat" — the call is a no-op. See the handle matrix at https://docs.kaleidr.com/sdk/kaleidr-map-element#handle-matrix.

هذا جزء من عقد /embed/v1: الأسلوب غير المدعوم لا يرمي استثناء أبداً.

ملاحظات حول الأساليب:

• setCamera: تحتفظ الحقول المحذوفة بقيمها. يحرّك duration الانتقال؛ وعند غيابه أو كونه 0 تنتقل الخريطة مباشرة. في Chat، لا يُدعم setCamera لأن المحادثة لا تمتلك الخريطة. ومع ذلك يحرّك المساعد الخريطة المتصلة أثناء الإجابات؛ لتحريكها بنفسك استخدم API مكتبة الخرائط.
• setTheme: في Chat فقط، ويقبل كائن خصائص CSS المخصصة أو سلسلة JSON له.
• setStyle: في Tile فقط، ويقبل معرّف نمط أو عنوان URL له.
• destroy: يزيل ما أضافه التركيب ويوقف تجديد الجلسات ويحذف الاستدعاءات المعلقة. تكرار الاستدعاء آمن. لا يمكن إعادة استخدام مقبض مدمّر؛ أعد التركيب.

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

[kaleidr] the map frame has not reported ready — calls held for it are sent now, and may reach no map. The frame may be showing an error (an unpublished map, a blocked request).

يبدأ الانتظار عند تحميل الإطار؛ لذلك يظل iframe الذي لم يبدأ تحميله أسفل المنطقة المرئية محتفظاً باستدعاءاته. لا يلزم انتظار kaleidr-embed:ready قبل استخدام المقبض. تبقى تلك الرسالة وkaleidr-embed:error وسيلة لمعرفة نجاح الخريطة أو فشلها. راجع رسائل Viewer.

لا يوفّر المقبض Promise باسم ready ولا أسلوب on() ولا عضواً باسم map أو iframe.

Kaleidr.init()

يهيئ جميع عناصر <kaleidr-map> الموجودة في المستند عند استدعائه. يستدعيه المحمّل تلقائياً، والعناصر المضافة لاحقاً تُركّب نفسها. لذلك نادراً ما يلزم؛ ولا ضرر من تكراره.

بوابة التفعيل

التضمينات مفعّلة افتراضياً. عند إيقاف البوابة، لا يحمّل Kaleidr.mount شيئاً ولا يرسل شيئاً ويعيد مقبضاً غير فعّال. استخدمها لانتظار موافقة الزائر أو لتعطيل التضمينات دون إزالة HTML.

وسائل التحكم الثلاث

وسيلة التحكم	النطاق	طريقة الضبط
علم الصفحة	جميع عمليات التركيب في الصفحة	window.__KALEIDR_EMBED_ENABLED__ = false قبل عمليات التركيب المراد تعليقها
Kaleidr.enable()	كل عمليات التركيب بعد الاستدعاء	Kaleidr.enable(false)
لكل تركيب	عملية واحدة	الخيار enabled: false أو السمة flag="false"

كيف يتخذ قرار التركيب

عند كل تركيب يقرأ SDK وسائل التحكم الثلاث:

1. إذا كانت أي وسيلة مضبوطة صراحة على false، يُعلّق التركيب.
2. وإلا، إذا كانت إحداها صراحة true، يتابع التركيب.
3. وإلا تُستخدم الحالة الافتراضية المفعّلة.

تترتب على ذلك ثلاث نتائج مهمة:

• لا يمكن رفع false إلا بالوسيلة التي وضعته. لا يرفع Kaleidr.enable(true) خيار enabled: false ولا علم صفحة قيمته false؛ ولا تلغي وسيلة أخرى.
• تُفحص البوابة وقت التركيب فقط. رفع التعليق لا يبدأ التراكيب المعلّقة تلقائياً، وإيقاف وسيلة لا يزيل التراكيب الجارية. بعد رفع التعليق استدعِ Kaleidr.mount من جديد أو أزل العنصر ثم أعد إدراجه.
• يُقرأ علم الصفحة في كل تركيب، لا عند تحميل السكربت فقط. تعيينه لاحقاً يؤثر في التركيب التالي.

التعليق الذي وضعته	لإلغائه افعل التالي
window.__KALEIDR_EMBED_ENABLED__ = false	عيّن true له أو احذفه.
Kaleidr.enable(false)	استدعِ Kaleidr.enable(true) أو Kaleidr.enable(null) لإعادة الافتراضي.
enabled: false أو flag="false"	أعد التركيب دون هذه القيمة. تغيير السمة flag لعنصر مُركّب لا يؤثر.

عند تعليق تركيب تظهر رسالة تحذير واحدة تسمي وسيلة التحكم المسؤولة:

[kaleidr] embed is disabled — window.__KALEIDR_EMBED_ENABLED__ is false. Reassigning it releases that lever — Kaleidr.enable() cannot.

القيم المقبولة

تتعامل وسائل التحكم بدقة مع القيم المنطقية حتى لا تفعّل سلسلة عارضة التضمينات بالخطأ.

الوسيلة	يُعدّ true	يُعدّ false	يُتجاهل مع تحذير
window.__KALEIDR_EMBED_ENABLED__	true	false	أي قيمة ليست منطقية حقيقية، بما فيها السلسلتان "true" و"false"
Kaleidr.enable(x)	بلا معامل، true، "true"، "1"، "yes"، "on"	false، 0، ""، "false"، "0"، "no"، "off"	السلاسل الأخرى، undefined، الكائنات، الدوال
خيار enabled	true، "true"، "1"، "yes"، "on"	false، 0، ""، "false"، "0"، "no"، "off"	سلاسل أخرى، كائنات، دوال
سمة flag	flag دون قيمة، "true"، "1"، "yes"، "on"	"false"، "0"، "no"، "off"	أي قيمة أخرى

تُتجاهل حالة الأحرف والمسافات المحيطة. عند استخدام قيمة من التخزين انتبه إلى نقطتين:

• يعيد Kaleidr.enable(null) ضبط الوسيلة إلى الافتراضي؛ ولا يعني «عدم إبداء رأي». تعيد localStorage.getItem(key) القيمة null عندما لا يوجد شيء مخزّن، وهذا بالضبط حال ما قبل الموافقة. لا تمرّر القيمة المخزنة مباشرة، بل قارن أولاً: Kaleidr.enable(stored === 'true').
• تترك القيمة المتجاهلة الوسيلة بحالتها السابقة، فلا تفعّل ولا تعطل.

مثال: تعليق التضمينات حتى الموافقة

تعلّق هذه الصفحة جميع التضمينات بعلم الصفحة لأنه يعمل مع العناصر التي تُركّب فور تشغيل المحمّل. عند الموافقة ترفع التعليق عن العلم نفسه ثم تعيد إدراج العناصر لتُركّب.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Consent-gated map</title>
  <script>
    // A real boolean, set before the loader. A stored string is compared, never passed through.
    window.__KALEIDR_EMBED_ENABLED__ =
      localStorage.getItem('embeds-consent') === 'true';
  </script>
  <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
</head>
<body>
  <div id="banner">
    This page shows an interactive map from Kaleidr.
    <button id="accept">Show the map</button>
  </div>

  <kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
               style="display:block; height:480px"></kaleidr-map>

  <script>
    const banner = document.getElementById('banner');
    if (window.__KALEIDR_EMBED_ENABLED__) banner.hidden = true;

    document.getElementById('accept').addEventListener('click', () => {
      localStorage.setItem('embeds-consent', 'true');
      banner.hidden = true;

      // 1. Release the lever that held the embeds.
      window.__KALEIDR_EMBED_ENABLED__ = true;

      // 2. A held element does not mount by itself. Re-insert each one.
      document.querySelectorAll('kaleidr-map').forEach((el) => {
        const parent = el.parentNode;
        const next = el.nextSibling;
        el.remove();
        parent.insertBefore(el, next);
      });
    });
  </script>
</body>
</html>

قبل الموافقة تُظهر علامة تبويب الشبكة kaleidr.js فقط من Kaleidr: لا حزمة منتج ولا طلب جلسة ولا iframe.

إذا ركّبت من JavaScript فلا تحتاج البوابة: لا تستدعِ Kaleidr.mount قبل الموافقة. تفيد البوابة عندما تُكتب التضمينات كعناصر HTML، أو حين يستدعي مدير وسوم أو فريق آخر mount وتحتاج مفتاح تحكم للصفحة بأكملها:

Kaleidr.enable(false);            // hold every later mount
// …
Kaleidr.enable(true);             // release it
const handle = Kaleidr.mount('#map', { product: 'viewer', shareId: 'YOUR_MAP_ID' });

المتغيرات العامة للصفحة

المتغير العام	النوع	وقت القراءة	الغرض
window.__KALEIDR_EMBED_ENABLED__	منطقي	عند كل تركيب	علم الصفحة في بوابة التفعيل.
window.__KALEIDR_EMBED_BASE__	سلسلة URL	عند كل تركيب	أصل حزم الاستضافة الذاتية. يُستخدم الأصل فقط ويجب أن تسمح به قواعد تجاوز الأساس. راجع إصدارات CDN.

معرفة نجاح التركيب

لا يعطي SDK شفرتك إشارة جاهزية أو فشل. المتاح للمراقبة:

المنتج	اكتمل التحميل	فشل
viewer	يرسل iframe رسالة kaleidr-embed:ready.	يرسل iframe رسالة kaleidr-embed:error أو يظهر خطأ [kaleidr:viewer] في وحدة التحكم.
tile	يرسل iframe رسالة kaleidr-embed:ready.	الجلسة المرفوضة تظهر في وحدة التحكم فقط، ومشكلة الرسم تُرسل kaleidr-embed:error.
chat	لا إشارة؛ تظهر اللوحة في الصفحة.	وحدة التحكم فقط.
editor	لا إشارة؛ يظهر المحرر في الصفحة.	وحدة التحكم فقط.

وُثّقت الرسالتان ضمن رسائل Viewer.

عند فشل التركيب

السبب	ما تراه	هل أُرسل طلب؟
لا يطابق المحدد أي هدف	[kaleidr:<product>] mount target not found: <selector>	لا
لا يملك العنصر product صالحاً	[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"	لا
مُرّر مفتاح خادم	[kaleidr:<product>] 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.	لا
مفتاح مجهول أو ملغى أو أصل غير مسموح	خطأ CORS للطلب sessions، ثم خطأ جلب [kaleidr:<product>]؛ لا يُعرض شيء.	نعم
النطاق مفقود أو المفتاح مقيّد بمنتج آخر أو الخطة لا تسمح	[kaleidr:<product>] kaleidr session exchange failed (403)؛ لا يُعرض شيء.	نعم
استنفاد تحميلات الخرائط (tile) أو كثرة طلبات الجلسة	[kaleidr:<product>] kaleidr session exchange failed (429)؛ لا يُعرض شيء.	نعم
فشل تحميل حزمة المنتج	[kaleidr:<product>] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/<product>.js	لا ينطبق
Viewer دون معرّف أو بمعرّف مشوّه	[kaleidr:viewer] Kaleidr map: invalid id "" — must match ^[A-Za-z0-9._~-]{1,100}$.	لا
Editor بلا مفتاح	[kaleidr:editor] [editor-embed] attach() requires an { apiKey }	لا
Chat بلا مفتاح ولا shareId	تظهر اللوحة لكن تفشل كل الأسئلة.	ليس وقت التركيب
بوابة التفعيل مغلقة	[kaleidr] embed is disabled — …	لا

لا يعرض SDK سبب الرفض الذي أعاده الخادم. يسجّل حالة HTTP فقط عند رفض الجلسة. السبب في نص الاستجابة: الرمز في detail عند 403/404، مثل {"detail":"insufficient_scope"}، وفي error عند 429 مع تفسير في detail. الاستثناء هو map_load_quota_exceeded الذي يرد في detail. افتح علامة الشبكة وحدد طلب sessions واقرأ الاستجابة. إذا أخفى CORS النص، أعد الطلب من الطرفية:

curl -i https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions \
  -H "x-api-key: kld_pk_live_…" \
  -H "Origin: https://www.example.com" \
  -H "content-type: application/json" \
  -d '{"product":"chat"}'

HTTP/2 403
content-type: application/json

{"detail":"origin_not_allowed"}

استخدم أصل الصفحة التي تفشل. اختبر بالمنتج "chat" أو "editor" أو "viewer"؛ فنجاح تبادل "tile" يُحسب تحميل خريطة واحداً. شرح جميع الرموز في الأخطاء.

فشل أول تبادل جلسة نهائي لذلك التركيب. لا يعيد SDK المحاولة؛ أصلح السبب وأعد التركيب.

تبادل الجلسة باختصار

في Chat وEditor وTile، لا يستخدم SDK مفتاحك القابل للنشر مباشرة لاستدعاء API وقت التشغيل، بل يستبدله بجلسة أولاً.

1. عند التركيب يرسل SDK الطلب POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions برأس x-api-key: <your publishable key> وجسم {"product":"<product>"}. يضيف المتصفح ترويسة Origin للصفحة.
2. يفحص Kaleidr بالترتيب: أن المفتاح قابل للنشر، وأن للطلب أصلاً، وأن الأصل ضمن الأصول المسموحة إن وُجدت، وأن المفتاح والخطة يسمحان بالمنتج، وأن نطاق المفتاح صحيح: ai لـChat، وdesign لـEditor، وmaps لـTile، ولا نطاق لـViewer.
3. الاستجابة هي {"session_token": "…", "expires_in": 900, "product": "…", "basemap_style_id": …}. تمثّل basemap_style_id خريطة الأساس الافتراضية للمنظمة، أو null إن لم تُضبط.
4. يستخدم المنتج رمز الجلسة في طلباته، وهو مرتبط بالأصل وبالمنتج الذي صُدر له.
5. يجدّد SDK الجلسة قبل انتهائها بـ90 ثانية، وكذلك عند عودة علامة تبويب خلفية بجلسة قاربت الانتهاء. إذا فشل التجديد، يعيد المحاولة كل 30 ثانية ما دام التركيب موجوداً.
6. يوقف handle.destroy() عمليات التجديد.

لا يحتاج Viewer إلى جلسة. أمّا Chat المركّب على خريطة منشورة باستخدام shareId بلا مفتاح فيحصل عليها من الخريطة، لا من مفتاح. راجع Chat على خريطة منشورة.

تُشرح تفاصيل الطلب والاستجابة في نقاط النهاية. ويوضح نموذج الأمان أنواع المفاتيح والجلسات وما تحميه قائمة الأصول المسموحة وما لا تحميه.

رسائل أخرى في وحدة التحكم

الرسالة	المعنى
[kaleidr] <method>() is not supported on product "<product>" — the call is a no-op. …	استدعيت أسلوباً لا يدعمه المنتج.
[kaleidr] <method>() IS supported on product "<product>", but this mount did not expose it, so the call did nothing. …	حزمة المنتج المخزّنة في المتصفح أقدم من المحمّل؛ أعد التحميل دون ذاكرة التخزين المؤقت.
[kaleidr] the map frame has not reported ready — calls held for it are sent now, and may reach no map. …	لم تُبلغ خريطة Viewer/Tile بالجاهزية خلال مهلة المقبض. أُرسلت استدعاءات setCamera وsetStyle المعلقة مع احتمال عدم وصولها؛ راقب kaleidr-embed:error.
[kaleidr] theme must be an object of CSS tokens, not an array; ignored.	كانت theme مصفوفة.
[kaleidr] theme string must be JSON …; named string themes are not supported. Ignored.	كانت theme سلسلة لا تبدأ بـ{.
[kaleidr] theme JSON parse failed (…); ignored.	احتوت theme على JSON غير صالح.
[kaleidr] <attribute>="<value>" is not a recognized boolean — the attribute is IGNORED. …	كانت قيمة flag أو contained غير معروفة. تسمي الرسالة flag="…" أو contained="…".
[kaleidr] base "<value>" is IGNORED — bundles load from <origin>. …	سمّى base أو window.__KALEIDR_EMBED_BASE__ أصلاً لا تسمح به قواعد تجاوز الأساس، فتُستخدم CDN الافتراضية.
[kaleidr] window.__KALEIDR_EMBED_ENABLED__ must be a boolean; got <type> (…). …	علم الصفحة ليس قيمة منطقية حقيقية وتُجاهل.
[kaleidr] Kaleidr.enable(): "<value>" is not a recognized boolean — the value is IGNORED. …	تلقّى Kaleidr.enable قيمة غير صالحة.
[kaleidr] enabled: "<value>" is not a recognized boolean — the value is IGNORED. …	تلقى خيار enabled قيمة غير صالحة.
[kaleidr] Kaleidr.enable(undefined) is IGNORED and leaves the gate exactly as it was. …	استُدعي Kaleidr.enable مع undefined فبقيت حالة البوابة كما هي.
[kaleidr] Kaleidr.enable(null) RESET the gate to the build default, releasing the <value> set earlier. …	أزال Kaleidr.enable(null) الضبط السابق وأعاد الافتراضي.

غير متوفر

• حزمة npm أو نسخة ES module أو تعريفات أنواع مضمنة؛ يمكن نسخ التعريف من تكامل أطر العمل.
• SDK أصلي لنظام iOS أو Android أو React Native أو Flutter.
• Promise باسم ready أو أحداث أو دوال رد على المقبض.
• عميل JavaScript لاستدعاء API دون تركيب منتج؛ استخدم API الخادم في الخلفية.

صفحات ذات صلة

• عنصر <kaleidr-map>
• تكامل أطر العمل
• إصدارات CDN
• سياسة أمان المحتوى
• استكشاف الأخطاء وإصلاحها