إضافة Kaleidr Chat إلى خريطة MapLibre

بنهاية هذا الدليل ستكون لديك صفحة تضم خريطة MapLibre GL JS ولوحة محادثة مثبتة داخلها. يطرح الزائر سؤالًا، فتظهر الإجابة تدريجيًا داخل اللوحة، وتظهر الأماكن المذكورة كعلامات على خريطة MapLibre وتتحرك الكاميرا لعرضها. يتوفر ذلك على جميع الخطط بما فيها Free باستخدام مفتاح قابل للنشر. تستهلك الأسئلة أرصدة الذكاء الاصطناعي لمؤسستك.

تعمل اللوحة مع أي تصميم تستخدمه خريطتك حاليًا، ولا تغيّر تصميمها أو مصدر مربعات الخرائط.

قبل البدء

مفتاح Kaleidr قابل للنشر (kld_pk_live_…) من kaleidr.com/api-keys يتضمن نطاق ai اللازم للمحادثة. راجع الحصول على مفتاح API.
مصدر صفحتك ضمن المصادر المسموح بها للمفتاح إذا كانت هناك قيود. للتطوير المحلي أضف مثلًا http://localhost:8080.
عنوان URL لتصميم MapLibre. يستخدم المثال تصميم MapLibre التجريبي العام؛ استخدم تصميمك الخاص في الإنتاج.
تحميل MapLibre GL JS عبر وسم script بحيث يتوفر window.maplibregl. إذا استوردته من npm فراجع إتاحة مكتبة npm كمتغير عام.
خادم HTTP مثل npx serve أو python -m http.server 8080. لا يعمل فتح الملف مباشرة من القرص.
اسمح بالمضيفين الواردين في سياسة أمان المحتوى إذا كان موقعك يطبقها.

الخطوة 1: ترتيب الخريطة وطبقة المحادثة

ضع الخريطة وهدف تثبيت المحادثة في حاوية واحدة محددة الموضع. تقع طبقة المحادثة فوق الخريطة مع السماح بمرور أحداث المؤشر.

<div id="mapHost" style="position:relative; height:520px">
  <div id="map" style="position:absolute; inset:0; z-index:0"></div>
  <div id="chat" style="position:absolute; inset:0; z-index:1; pointer-events:none"></div>
</div>

النتيجة المتوقعة: لا شيء بعد؛ مجرد مساحة فارغة ارتفاعها 520 بكسل. توضح السمات والتخطيط وظيفة كل تصريح.

الخطوة 2: تحميل MapLibre GL JS وإنشاء الخريطة

حمّل ملف الأنماط في رأس الصفحة والبرنامج النصي قبل كودك. يجب أن يشير عنوانا URL إلى الإصدار نفسه.

<link rel="stylesheet" href="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.css" />
<script src="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.js"></script>
<script>
  const map = new maplibregl.Map({
    container: 'map',
    style: 'https://demotiles.maplibre.org/style.json', // your own style here
    center: [-0.12, 51.5],
    zoom: 11,
  });
</script>

النتيجة المتوقعة: خريطة قابلة للسحب والتكبير. يعرض التصميم التجريبي خريطة دول مبسطة قليلة التفاصيل في المدن، لكن العلامات وتحريك الكاميرا يعملان أيضًا.

الخطوة 3: تحميل `kaleidr.js`

أضف محمّل Kaleidr بعد برنامج MapLibre النصي وقبل الكود الذي يثبّت اللوحة.

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

النتيجة المتوقعة: لا تغيير مرئي. في وحدة التحكم، تعيد Kaleidr.version نص إصدار.

الخطوة 4: تثبيت لوحة المحادثة

مرّر مفتاحك وكائن الخريطة الفعلي.

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

لا تحتاج إلى انتظار حدث load الخاص بالخريطة. تعود Kaleidr.mount فورًا؛ وتظهر اللوحة عند تحميل حزمة المحادثة واستبدال مفتاحك بجلسة.

النتيجة المتوقعة: شريط إدخال يحمل «Ask Kaleidr» أعلى يسار الخريطة.

الصفحة الكاملة

احفظ المثال باسم index.html، واستبدل المفتاح، وقدّم المجلد عبر HTTP.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Kaleidr Chat on MapLibre</title>
    <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.css" />
    <style>
      body { margin: 0; font-family: system-ui, sans-serif; }
      #mapHost { position: relative; height: 100vh; }
      #map { position: absolute; inset: 0; z-index: 0; }
      #chat { position: absolute; inset: 0; z-index: 1; pointer-events: none; }
    </style>
  </head>
  <body>
    <div id="mapHost">
      <div id="map"></div>
      <div id="chat"></div>
    </div>

    <script src="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.js"></script>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
    <script>
      const map = new maplibregl.Map({
        container: 'map',
        style: 'https://demotiles.maplibre.org/style.json',
        center: [-0.12, 51.5],
        zoom: 11,
      });

      const handle = Kaleidr.mount('#chat', {
        product: 'chat',
        publishableKey: 'kld_pk_live_…',
        map,
        contained: true,
      });
    </script>
  </body>
</html>

آلية العمل

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

تفاصيل خاصة بـ MapLibre GL JS:

العلامات هي كائنات Marker في MapLibre مع عنصر HTML، منفصلة عن العلامات التي تضيفها أنت.
يُرسم المسار باستخدام مصادر وطبقات تضيفها اللوحة إلى تصميمك ثم تزيلها. لا تتغير مصادر بياناتك وطبقاتك.
تُجدَّد الجلسة تلقائيًا ما دامت اللوحة مثبتة. لا تتولى إدارة الرموز بنفسك.

التحقق من نجاح الإعداد

في الصفحة

يظهر شريط Ask Kaleidr أعلى يسار الخريطة.
اكتب Show me three museums in London واضغط Enter. تتدفق الإجابة وتظهر ثلاث علامات وتضبط الخريطة عرضها لاحتوائها.

في وحدة التحكم

لا يوجد خطأ أو تحذير يحتوي [kaleidr.

في تبويب Network

الطلب	المتوقع
`GET https://cdn.kaleidr.com/embed/v1/kaleidr.js`	200
`GET https://cdn.kaleidr.com/embed/v1/chat.js`	200
`POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions`	200 مع بيانات JSON مثل المثال أدناه
`POST https://api.kaleidr.com/inference-api/b2b/v1/chat/control/stream` (بعد السؤال)	200، `content-type: text/event-stream`

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

إذا لم يعمل

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

العَرَض	السبب	الحل
اللوحة مفقودة، وخطأ CORS في `…/sdk/sessions` ثم خطأ `[kaleidr:chat]`	المفتاح غير معروف أو أُلغي، أو المصدر غير مسموح به. لا يرسل API ترويسات CORS إلا للمصادر المقبولة.	تحقق من المفتاح وأضف المصدر الدقيق بما فيه البروتوكول والمنفذ في kaleidr.com/api-keys.
`[kaleidr:chat] kaleidr session exchange failed (403)`	المفتاح صالح لكنه لا يستطيع تشغيل Chat. قد تكون قيمة `detail` هي `insufficient_scope` (نطاق `ai` مفقود)، أو `product_not_allowed` (المنتجات الأخرى فقط)، أو `tier_capability_not_allowed`.	استخدم مفتاحًا يتضمن `ai` ويسمح بمنتج `chat`.
`[kaleidr:chat] Kaleidr: a server key (kld_sk_…) must never be used in the browser …`	مررت مفتاح خادم ولم يُرسل أي طلب.	استخدم مفتاحًا قابلًا للنشر (`kld_pk_live_…`). ألغِ مفتاح الخادم إذا سبق نشره.
`[kaleidr:chat] mount target not found: #chat`	لم يجد المحدّد عنصر الهدف.	شغّل `mount` بعد إنشاء العنصر، أو مرّر العنصر نفسه. `mount`
`[kaleidr:chat] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/chat.js`	حُظرت الحزمة عادةً بفعل سياسة أمان المحتوى أو مانع إعلانات.	اسمح بـ `https://cdn.kaleidr.com` في `script-src`.
`Kaleidr is not defined`	بدأ كودك قبل تحميل `kaleidr.js`، مثلًا بسبب `async` أو `defer`.	حمّل `kaleidr.js` أولًا بوسم عادي، أو شغّل كودك عند حدث `load` للوسم.
`[kaleidr] embed is disabled — …`	بوابة التمكين تمنع التثبيت.	تسمي الرسالة التحكم المسؤول. راجع kaleidr.js.
تظهر اللوحة أعلى يسار نافذة المتصفح بدلًا من الخريطة	`contained` مفقود أو `#chat` ليس محدد الموضع.	أضف `contained: true` وأنماط الخطوة 1.
تجيب اللوحة لكن لا تظهر علامات ولا تتحرك الخريطة	لم يُعرف الكائن الممرر في `map`.	مرّر كائن `maplibregl.Map` نفسه. راجع الخرائط المدعومة.
تتحرك الكاميرا نحو مكان واحد لكن العلامات وتضمين عدة أماكن لا يعملان	لا يوجد `window.maplibregl`. تحريك الكاميرا نحو مكان واحد يحتاج كائن الخريطة فقط، أما العلامات وتلاؤم عدة أماكن فيحتاجان المتغير العام.	إذا استوردت MapLibre عبر npm، عرّف `window.maplibregl` قبل التثبيت. راجع واردات npm.
تعرض اللوحة دائمًا «Sorry — that didn't go through. Please try again.»	الجلسة لم تعد صالحة بعد إلغاء المفتاح أو تغيير المصادر المسموح بها.	تحقق من المفتاح وأعد تحميل الصفحة.
تعرض اللوحة «You've reached your usage limit for now.»	خطأ 429: نفدت أرصدة الذكاء الاصطناعي أو تجاوز المفتاح حد المعدل. يشترك زوار الصفحة جميعًا في حد المفتاح.	راجع الحصص وحدود المعدل.
لا يمكن سحب الخريطة	تعترض طبقة المحادثة تفاعل المستخدم.	أضف `pointer-events:none` إلى `#chat`.

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

القيود

لا تتلقى صفحتك دوال رد اتصال أو أحداثًا من اللوحة، فلا يمكنك التفاعل برمجيًا مع سؤال أو إجابة أو النقر على علامة.
لا يرى المساعد طبقاتك أو علاماتك أو المنطقة المعروضة على الخريطة. يُرسل معه مستوى التكبير فقط.
لا يمكنك تمرير تعليماتك أو بياناتك الخاصة إلى المساعد عبر اللوحة.
لغة الإجابات وعنوان اللوحة ونص حقل الإدخال هي خيارات تثبيت (lang وtitle وplaceholder): راجع مرجع Chat. تبقى التسميات الأخرى بالإنجليزية.
لا تفعل handle.setCamera() شيئًا على تثبيت Chat وتظهر تحذيرًا. حرّك الكاميرا من خلال واجهة MapLibre.
في تطبيق أحادي الصفحة، استدعِ handle.destroy() عند إزالة عرض الخريطة، وثبّته مجددًا عند العودة.
لا توفر لوحة المحادثة خريطة أساسية. لعرض خريطة Kaleidr الأساسية استخدم منتج Tile داخل عنصر مستقل، ويمكن للمحادثة التحكم به عبر map-target.

توجد القائمة الكاملة في الإمكانات والقيود.

الخطوات التالية

السمات والتخطيط: طابق مظهر اللوحة مع موقعك.
مرجع Chat: جميع الخيارات وكائن التحكم والأخطاء.
قائمة فحص الإنتاج: ما يجب مراجعته قبل الإطلاق.
أطر العمل: التثبيت من React وNext.js وVue.

قبل البدء​

الخطوة 1: ترتيب الخريطة وطبقة المحادثة​

الخطوة 2: تحميل MapLibre GL JS وإنشاء الخريطة​

الخطوة 3: تحميل kaleidr.js​

الخطوة 4: تثبيت لوحة المحادثة​

الصفحة الكاملة​

آلية العمل​

التحقق من نجاح الإعداد​

إذا لم يعمل​

القيود​

الخطوات التالية​