مرجع Chat

يؤدي product: 'chat' إلى تثبيت لوحة Kaleidr Chat في صفحتك. تعمل اللوحة داخل مستند الصفحة وليس داخل iframe. ويمكن ربطها بكائن خريطة تمرره إليها، أو بعنصر Viewer أو Tile من Kaleidr تحدده، أو تشغيلها من دون خريطة باعتبارها لوحة محادثة فقط.

هذه الصفحة مرجع للاطلاع على التفاصيل. لإنشاء صفحتك الأولى، ابدأ بأحد الأدلة: Mapbox، أو MapLibre، أو Google Maps، أو Leaflet.

المتطلبات

البند	التفاصيل
الخطة	Free وما فوقها
بيانات الاعتماد	مفتاح قابل للنشر (`kld_pk_live_…`)، أو معرّف خريطة منشورة من Studio مع تفعيل Control Tower
النطاق	`ai`، ويُمنح لكل مفتاح جديد افتراضيًا
المصدر المسموح	مصدر الصفحة، إذا كان المفتاح يحدد مصادر مسموحة
المحمّل	`https://cdn.kaleidr.com/embed/v1/kaleidr.js`
مكتبة الخرائط	اختيارية. راجع الخرائط المدعومة.

تثبيت بالحد الأدنى

const handle = Kaleidr.mount('#chat', {
  product: 'chat',
  publishableKey: 'kld_pk_live_…',
  map,              // your live map object
  contained: true,  // dock inside #chat
});

تقبل Kaleidr.mount(target, options) محدد CSS أو عنصرًا بوصفه target. وتعيد مقبض تحكم فورًا ولا ترمي استثناء عند فشل التثبيت. يجري تحميل حزمة Chat وتبادل المفتاح في الخلفية؛ وإذا فشلت أي منهما، تُسجّل رسالة خطأ في وحدة التحكم ولا يظهر شيء. الحالة الوحيدة التي ترمي استثناء هي الاستدعاء من دون كائن خيارات: تؤدي Kaleidr.mount('#chat') إلى TypeError.

خيارات التثبيت

تُقرأ جميع الخيارات مرة واحدة فقط عند التثبيت. لتغيير أي منها، استدعِ destroy() ثم ثبّت المنتج من جديد. الاستثناء الوحيد هو السمة المرئية، إذ يمكن تحديثها بواسطة setTheme.

الخيار	النوع	القيمة الافتراضية	مطلوب	سلوكه في Chat
`product`	`'chat'`	لا شيء	نعم	يحدد منتج Chat.
`publishableKey`	سلسلة نصية	لا شيء	نعم، إلا إذا قُدّم `shareId`	مفتاحك `kld_pk_…`. يستبدله SDK برمز جلسة قبل أن ترسل اللوحة أي طلب. يُرفض مفتاح الخادم `kld_sk_…` داخل المتصفح مع ظهور خطأ في وحدة التحكم ومن دون إرسال طلب.
`shareId`	سلسلة نصية	لا شيء	نعم، إلا إذا قُدّم `publishableKey`	معرّف خريطة Studio منشورة مع تفعيل Control Tower في لوحة Kaleidr AI الخاصة بها. يُستخدم فقط عند عدم تقديم مفتاح. يتحمل مالك الخريطة تكلفة الأسئلة. يعرض العارض الخاص بالخريطة المنشورة هذه اللوحة بالفعل. راجع Kaleidr AI على خريطة منشورة.
`map`	كائن خريطة نشط	لا شيء	لا	الخريطة التي يضيف إليها المساعد العلامات ويحرك عرضها. تُعرّف المكتبة من الكائن نفسه. احذفه للوحة محادثة بلا خريطة.
`mapTarget`	محدد CSS	لا شيء	لا	عنصر Viewer أو Tile من نوع `<kaleidr-map>` على الصفحة نفسها تريد من اللوحة التحكم فيه. يُتجاهل عند تمرير `map`.
`contained`	قيمة منطقية	`false`	لا	يضع `true` اللوحة داخل هدف التثبيت الذي يجب تحديد موضعه وحجمه. ويضيفها `false` إلى `document.body` كنافذة ثابتة أعلى يسار مساحة العرض.
`lang`	سلسلة نصية	لغة `<html lang>` للصفحة إن كانت علامة صحيحة، وإلا فالإنجليزية	لا	لغة إجابات اللوحة بصيغة BCP 47 مثل `en` أو `ko` أو `pt-BR`. راجع اللغة.
`title`	سلسلة نصية	عنوان مستمد من المحادثة	لا	عنوان ترويسة نافذة Chat. راجع العنوان والنص النائب.
`placeholder`	سلسلة نصية	`Ask Kaleidr`	لا	النص النائب لحقل الإدخال.
`theme`	كائن أو سلسلة JSON تمثل كائنًا	لا شيء	لا	خصائص CSS مخصصة لتطبيقها، مثل `{ '--highlight-color': '#7c3aed' }`. تُكتب إلى `:root` وتؤثر في الصفحة كلها.
`enabled`	قيمة منطقية	لا شيء	لا	ذراع التحكم بالتفعيل الخاص بهذا التثبيت. توقفه `false`. راجع kaleidr.js.
`apiBase`	عنوان URL	`https://api.kaleidr.com/inference-api`	لا	واجهة API التي تُرسل إليها طلبات تبادل الجلسة والأسئلة. يجب أن تتضمن المسار `/inference-api`.
`base`	عنوان URL	`https://cdn.kaleidr.com`	لا	مصدر تحميل حزمة Chat. يُستخدم المصدر فقط، وتُقبل حصريًا شبكة Kaleidr (`https://cdn.kaleidr.com`)، أو المصدر الذي حُمّل منه `kaleidr.js`، أو مصدر الصفحة نفسها. راجع تجاوز المصدر الأساسي.
`apiKey`	سلسلة نصية	لا شيء	لا	اسم بديل مهجور لـ `publishableKey`.

خيارات لا يستخدمها Chat

تُقبل center وzoom وpitch وbearing وstyleId وviewerBase وtileBase ولكن تُتجاهل عند تثبيت Chat. لا تضبط اللوحة موضع كاميرا أوليًا؛ بل تحتفظ الخريطة بالعرض الذي حددته لها.

خيارات غير موجودة

لا يوجد خيار لفرض مكتبة خرائط بعينها أو لتفعيل الصوت أو لإضافة دوال رد نداء. راجع ما ليس متاحًا حاليًا.

اللغة

تحدد lang اللغة التي تجيب بها اللوحة، وتُرسل مع كل سؤال.

ما تمرره	اللغة المستخدمة
`lang: 'ko'` أو `lang="ko"` في العنصر	العلامة نفسها كما قُدمت.
من دون `lang` على صفحة فيها `<html lang="fr">`	لغة الصفحة إذا كانت العلامة صحيحة الصياغة.
من دون `lang` على صفحة بلا `<html lang>` أو بعلامة غير صحيحة	الإنجليزية.

القيم المقبولة: علامات اللغة BCP 47 مثل en وko وja وpt-BR وzh-Hant. ترفض API العلامة التي تزيد عن 35 حرفًا، وعندئذ يفشل كل سؤال برمز 422 lang_too_long.
تُستعار لغة الصفحة فقط إذا كانت العلامة صحيحة الصياغة: حرفان أو ثلاثة، يليهما اختياريًا ما يصل إلى ثلاث علامات فرعية تفصل بينها شرطات، تضم كل منها حرفًا إلى ثمانية أحرف أو أرقام. يُتجاهل أي عنصر نائب لقالب لم يُستبدل، ويُستخدم الإنجليزية، لذلك لا يؤدي وجود <html lang> معطوب إلى تعطيل Chat.
تتقدم lang المحددة صراحة دائمًا على لغة الصفحة.
لا تترجم lang العنوان أو النص النائب. قيمهما الافتراضية بالإنجليزية. اضبط title وplaceholder باللغة نفسها المحددة في lang.

العنوان والنص النائب

Kaleidr.mount('#chat', {
  product: 'chat',
  publishableKey: 'kld_pk_live_…',
  map,
  contained: true,
  lang: 'fr',
  title: 'Demandez à propos d’un lieu',
  placeholder: 'Posez une question',
});

placeholder يستبدل النص المعروض في حقل الإدخال، وهو «Ask Kaleidr» افتراضيًا.
title هو عنوان نافذة Chat. تظهر النافذة وترويستها عند بدء محادثة، ثم تعرض الترويسة عنوانك في كل محادثة. عند غياب title، تعرض الترويسة أول سؤال للزائر بصيغة مختصرة. وتعرض المحادثة المصغرة عنوان المحادثة الخاصة بها، المأخوذ من أول سؤال للزائر، سواء مررت title أم لا.
في العنصر، سمة العنوان هي chat-title وليست title. فسمة HTML المسماة title تعرض تلميح المتصفح عند تمرير المؤشر فوق محتوى العنصر.

بيانات الاعتماد المستخدمة

ما تمرره	النتيجة
`publishableKey`	يُستبدل المفتاح بجلسة. إذا قُدّم `shareId` أيضًا، يُتجاهل.
`shareId` فقط	تُستبدل الخريطة المنشورة بجلسة.
لا هذا ولا ذاك	تظهر اللوحة، لكن تفشل جميع الأسئلة. ولا يُسجّل خطأ عند التثبيت.

الخريطة المستخدمة

ما تمرره	النتيجة
`map`	كائن الخريطة هذا. يُتجاهل `mapTarget` إن قُدّم معه.
`mapTarget` فقط	عنصر Kaleidr Viewer أو Tile المطابق للمحدد. يُحل المحدد عند الحاجة إلى الخريطة، لذا يمكن تثبيت العنصر بعد اللوحة.
لا شيء، أو كائن أو محدد غير معروف	محادثة فقط: لا علامات ولا تحريك للكاميرا ولا مسارات. ولا يُسجّل شيء.

سمات العنصر

<kaleidr-map product="chat"> هي الصيغة التعريفية. ويكون العنصر نفسه هدف التثبيت.

<kaleidr-map product="chat" share-id="YOUR_MAP_ID" contained
             map-target="#store-map"
             style="display:block; position:absolute; inset:0; z-index:1; pointer-events:none"></kaleidr-map>

السمة	الخيار الذي تضبطه	ملاحظات
`product="chat"`	`product`	مطلوبة.
`publishable-key`	`publishableKey`
`share-id`	`shareId`
`map-target`	`mapTarget`	محدد CSS.
`contained`	`contained`	السمة من دون قيمة تعني `true`. و`contained="false"` تعني `false`.
`lang`	`lang`	علامة BCP 47. راجع اللغة.
`chat-title`	`title`	عنوان الترويسة، لا `title` التي تخص تلميح HTML.
`placeholder`	`placeholder`	النص النائب لحقل الإدخال.
`theme`	`theme`	سلسلة JSON. يطبَّق التغيير بعد التثبيت مباشرة.
`flag`	`enabled`	`flag="false"` يوقف التثبيت.
`api-base`	`apiBase`
`base`	`base`
`api-key`	`apiKey`	اسم بديل مهجور لـ `publishable-key`.

نقاط مهمة عن صيغة العنصر:

لا يمكنها تلقي كائن خريطة نشط. لا توجد سمة لـ map. لربط خريطتك الخاصة من Mapbox أو MapLibre أو Google أو Leaflet، استخدم Kaleidr.mount. وتتحكم صيغة العنصر في Viewer أو Tile بواسطة map-target، أو تعمل كمحادثة فقط.
تُقرأ السمات مرة واحدة عند اتصال العنصر. لا يُطبَّق أي تعديل لاحق إلا على theme. تغيير share-id أو publishable-key أو map-target أو contained أو lang أو chat-title أو placeholder أو flag بعد ذلك لا يؤثر؛ أزل العنصر وأدرج عنصرًا جديدًا.
سمات الكاميرا لا تؤثر. تُتجاهل center وzoom وpitch وbearing عند تثبيت Chat، ويُسجّل تحذير «غير مدعوم» عند تغييرها لاحقًا.
القيمة الافتراضية للعنصر هي display:block. عند استخدام contained، حدد موضعه وحجمه. تحتفظ الأمثلة بـ display:block في النمط لدعم Safari الأقدم من 16.4، إذ يبقى العنصر مضمنًا ما لم يُحدد خلاف ذلك. راجع السمات المرئية والتخطيط.
تؤدي إزالة العنصر إلى تدمير التثبيت. وتؤدي إعادة إدراجه إلى إنشاء لوحة وجلسة جديدتين.

يتوفر جدول السمات الكامل لجميع المنتجات في عنصر kaleidr-map.

مقبض التحكم

تُرجع Kaleidr.mount مقبضًا بالبنية نفسها لكل المنتجات. في Chat:

العضو	في Chat	السلوك
`product`	`'chat'`	للقراءة فقط.
`setTheme(theme)`	مدعوم	يقبل كائن خصائص CSS مخصصة أو سلسلة JSON تمثله. يضيف القيم إلى الإعدادات الموجودة. إذا خلا اسم مفتاح من `--`، تُضاف تلقائيًا. تُتجاهل السلسلة غير الصالحة أو المصفوفة مع إظهار تحذير.
`destroy()`	مدعوم	يزيل اللوحة وبطاقات الأماكن والعلامات وخط المسار، ويوقف تجديد الجلسة. يمكن استدعاؤه أكثر من مرة بأمان.
`setCamera(camera)`	غير مدعوم	يسجل تحذيرًا ولا يفعل شيئًا. استخدم API مكتبة الخرائط الخاصة بك لتحريك الخريطة.
`setStyle(style)`	غير مدعوم	يسجل تحذيرًا ولا يفعل شيئًا.

handle.setTheme({ '--highlight-color': '#0ea5e9' });
handle.destroy();

تُوضع الاستدعاءات التي تتم قبل انتهاء تحميل اللوحة في قائمة انتظار وتُنفذ عندما تصبح جاهزة. يؤدي استدعاء destroy() قبل تحميلها إلى إلغاء التثبيت.

ليس للمقبض وعد ready ولا طريقة on() ولا عضو map، ولا وسيلة لإرسال رسالة أو قراءة المحادثة. إذا كان التحكم بالتفعيل متوقفًا عند التثبيت، يصبح المقبض كائنًا خاملاً: لا تفعل أي طريقة شيئًا، ويحدد تحذير واحد في وحدة التحكم التحكمَ الذي أوقف التثبيت.

تُسجّل الطرق غير المدعومة:

[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.

جدول المنتجات الأربعة متاح في عنصر kaleidr-map.

ماذا تفعل اللوحة بعد التثبيت

تعرض شريط إدخال يحمل «Ask Kaleidr» أو placeholder الذي حددته. يوسعه السؤال الأول إلى نافذة محادثة.
يُرسل كل سؤال مع المحادثة السابقة ومعرّفها ومستوى تكبير الخريطة عند ربطها وعلامة اللغة: lang التي حددتها، ثم لغة الصفحة، ثم en. تسرد البيانات التي تغادر الصفحة كل طلب.
تتحول الأماكن المذكورة في الإجابة إلى بطاقات نتائج وعلامات على الخريطة المرتبطة. وتنتقل الكاميرا إلى مكان واحد أو تؤطر عدة أماكن.
يعرض التثبيت محادثة واحدة في كل مرة ولكل محادثة معرّفها. يؤدي إغلاق النافذة إلى مسح المحادثة وعلاماتها، ويبدأ السؤال التالي محادثة جديدة بمعرّف جديد. يحافظ تصغير Chat على المحادثة المصغرة؛ ويبدأ السؤال التالي محادثة أخرى، بينما تستأنف استعادة المحادثة المصغرة المحادثة بمعرّفها السابق. تعيد إعادة تحميل الصفحة كل شيء إلى البداية ولا يُحفظ شيء دائمًا.

تبادل الجلسة

لا يُستخدم مفتاحك القابل للنشر لإرسال الأسئلة مباشرة مطلقًا. قبل أي طلب من اللوحة، يستبدل SDK المفتاح برمز جلسة قصير العمر ثم يعطي اللوحة ذلك الرمز وحده.

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

{"product":"chat"}

{ "session_token": "kld_sess_live_…", "expires_in": 900, "product": "chat", "basemap_style_id": null }

السلوك	التفاصيل
الارتباط	الجلسة صالحة لمنتج `chat` فقط ومن المصدر الذي طلبها.
التجديد	يطلب SDK جلسة جديدة قبل انتهاء الحالية بـ 90 ثانية، وكذلك عند عودة علامة تبويب خلفية إلى الظهور وكانت الجلسة منتهية أو قاربت الانتهاء.
فشل التجديد	يُعاد المحاولة كل 30 ثانية ما دامت اللوحة مثبتة.
فشل أول تبادل	يفشل التثبيت. يُسجّل خطأ واحد، ولا يظهر شيء ولا تحدث محاولة جديدة. ثبّت من جديد لإعادة المحاولة.
بلا مفتاح ومع `shareId`	يتم التبادل بواسطة `POST …/b2b/v1/sdk/share-sessions` مع جسم `{"share_id":"…"}`. تدوم الجلسة 300 ثانية. إذا رُفض التجديد بـ 401 أو 403 أو 404، يتوقف SDK عن الطلب حتى إعادة تحميل الصفحة.

يشرح التوثيق والنطاقات المفاتيح والجلسات والنطاقات بالتفصيل.

دورة الحياة في تطبيق أحادي الصفحة

استدعِ handle.destroy() عند إزالة العرض الذي يحتوي على الخريطة. دمّر اللوحة قبل إزالة الخريطة حتى تتمكن من إزالة علاماتها.
ثبّت من جديد عند عودة العرض. يؤدي ذلك إلى تبادل جلسة جديد ومحادثة جديدة.
تُبقي destroy() ورقة أنماط اللوحة وخصائص السمة المرئية في :root داخل المستند. راجع ما تزيله destroy() وما تبقيه.
إذا استبدلت كائن الخريطة، مثل إعادة إنشائها، فدمّر اللوحة وثبّتها بالكائن الجديد. تحتفظ اللوحة بالكائن الذي استلمته عند التثبيت.

يعرض تكامل أطر العمل أنماط التثبيت والتنظيف لـ React وNext.js وVue.

الأخطاء

يبلّغ SDK عن فشل التثبيت بخطأ واحد في وحدة التحكم، من دون إعادة سبب الرفض من الخادم. عند فشل HTTP، افتح الطلب في تبويب Network واقرأ جسم JSON. يحمل الخطأ 403 أو 404 رمزه في الحقل detail. ويحمل 429 الرمز في error مع جملة توضيحية في detail.

أثناء التثبيت

وحدة التحكم	الشبكة	السبب
`[kaleidr:chat] mount target not found: <selector>`	لا طلب	لم يطابق المحدد أي عنصر.
`[kaleidr:chat] Kaleidr: a server key (kld_sk_…) must never be used in the browser …`	لا طلب	مُرر مفتاح خادم.
`[kaleidr:chat] [kaleidr] failed to load <url>`	فشل طلب `chat.js`	حُظرت الحزمة أو تعذر الوصول إلى شبكة CDN.
خطأ CORS يتبعه خطأ يحتوي على `[kaleidr:chat]`	حظر CORS طلب `POST …/sdk/sessions`	المفتاح مجهول أو ملغى أو منتهي الصلاحية، أو مصدر الصفحة غير موجود في القائمة المسموحة. تُرسل API ترويسات CORS إلى المصادر المعتمدة فقط، فيخفي المتصفح الحالة والجسم.
`[kaleidr:chat] kaleidr session exchange failed (403)`	403 `insufficient_scope`	لا يحمل المفتاح نطاق `ai`.
الشيء نفسه	403 `product_not_allowed`	المفتاح مقصور على منتجات لا تتضمن `chat`.
الشيء نفسه	403 `tier_capability_not_allowed`	خطة المؤسسة الحالية لا تتيح هذه الإمكانية.
`[kaleidr:chat] kaleidr session exchange failed (429)`	429 `rate_limited`	أكثر من 30 طلب جلسة بهذا المفتاح خلال دقيقة واحدة.
`[kaleidr:chat] kaleidr session exchange failed (404)`	404 `sessions_disabled`	تبادل الجلسات معطل في المنصة. لا يرجع السبب إلى مفتاحك.
`[kaleidr:chat] kaleidr session exchange failed (503)`	503 `sessions_not_configured`	خلل في المنصة. أعد التحميل للمحاولة.
`[kaleidr:chat] kaleidr session exchange failed (403)` أو `(404)` عند التثبيت بـ `shareId` بلا مفتاح	403 `chat_disabled` أو 403 `origin_not_allowed` أو 404 `not_found`	رفضت الخريطة المنشورة Chat. راجع Kaleidr AI على خريطة منشورة.
`[kaleidr] embed is disabled — …` (تحذير)	لا طلب	التحكم بالتفعيل متوقف. يحدد النص عنصر التحكم.
`[kaleidr] theme string must be JSON …` (تحذير)	لا ينطبق	كانت قيمة `theme` سلسلة لا تمثل JSON. تُثبّت اللوحة من دون تطبيقها.

أثناء استخدام اللوحة

تعرض اللوحة حالات الفشل للزائر كسطر ضمن المحادثة. لا يتلقى كودك إشعارًا.

ما يراه الزائر	الحالة	السبب
"Sorry — that didn't go through. Please try again."	401	لم تعد الجلسة صالحة: أُلغي المفتاح أو انتهت صلاحيته، أو أزيل المصدر من المصادر المسموحة، أو لم تقدم بيانات اعتماد عند التثبيت.
الشيء نفسه	5xx أو فشل الشبكة	خلل مؤقت.
"You've reached your usage limit for now." مع وقت إعادة الضبط إذا كان معروفًا	429 `quota_exceeded`	نفدت أرصدة الذكاء الاصطناعي للمؤسسة أو بلغ المفتاح سقفه الشهري.
الشيء نفسه	429 `rate_limited`	حد معدل طلبات المفتاح. يشترك جميع زوار الصفحة في المفتاح نفسه.
الشيء نفسه	429 `visitor_limit_reached`	Chat بلا مفتاح فقط: تجاوز هذا الزائر الحد لكل دقيقة أو لكل يوم.

يتضمن الأخطاء القائمة الكاملة، ويشرح الحصص وحدود المعدل القيود.

المتطلبات​

تثبيت بالحد الأدنى​

خيارات التثبيت​

خيارات لا يستخدمها Chat​

خيارات غير موجودة​

اللغة​

العنوان والنص النائب​

بيانات الاعتماد المستخدمة​

الخريطة المستخدمة​

سمات العنصر​

مقبض التحكم​

ماذا تفعل اللوحة بعد التثبيت​

تبادل الجلسة​

دورة الحياة في تطبيق أحادي الصفحة​

الأخطاء​

أثناء التثبيت​

أثناء استخدام اللوحة​

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