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

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

قبل البدء

• مفتاح Kaleidr قابل للنشر (kld_pk_live_…) من kaleidr.com/api-keys. تتضمن المفاتيح الجديدة نطاق ai اللازم للمحادثة. راجع الحصول على مفتاح API.
• إضافة مصدر صفحتك إلى المصادر المسموح بها للمفتاح إذا كان يقيّدها. للتجارب المحلية أضف مثلًا http://localhost:8080.
• رمز وصول Mapbox (pk.…) من حسابك في Mapbox. تحاسب Mapbox على الخريطة وتحاسب Kaleidr على الأسئلة؛ وهما منفصلان.
• تحميل Mapbox GL JS عبر وسم script بحيث يتوفر window.mapboxgl. إذا كنت تستورده من 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: تحميل Mapbox GL JS وإنشاء الخريطة

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

<link rel="stylesheet" href="https://api.mapbox.com/mapbox-gl-js/v3.9.4/mapbox-gl.css" />
<script src="https://api.mapbox.com/mapbox-gl-js/v3.9.4/mapbox-gl.js"></script>
<script>
  mapboxgl.accessToken = 'pk.…';
  const map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/streets-v12',
    center: [-0.12, 51.5],
    zoom: 11,
  });
</script>

النتيجة المتوقعة: خريطة Mapbox لوسط لندن قابلة للسحب والتكبير.

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

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

<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 Mapbox</title>
    <link rel="stylesheet" href="https://api.mapbox.com/mapbox-gl-js/v3.9.4/mapbox-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://api.mapbox.com/mapbox-gl-js/v3.9.4/mapbox-gl.js"></script>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
    <script>
      mapboxgl.accessToken = 'pk.…';

      const map = new mapboxgl.Map({
        container: 'map',
        style: 'mapbox://styles/mapbox/streets-v12',
        center: [-0.12, 51.5],
        zoom: 11,
      });

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

آلية العمل

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

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

• العلامات هي كائنات Marker في Mapbox مع عنصر 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.	مرّر كائن mapboxgl.Map نفسه. راجع الخرائط المدعومة.
تتحرك الكاميرا نحو مكان واحد لكن العلامات وتضمين عدة أماكن لا يعملان	لا يوجد window.mapboxgl. تحريك الكاميرا نحو مكان واحد يحتاج كائن الخريطة فقط، أما العلامات وتلاؤم عدة أماكن فيحتاجان المتغير العام.	إذا استوردت Mapbox عبر npm، عرّف window.mapboxgl قبل التثبيت. راجع واردات 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 وتظهر تحذيرًا. حرّك الكاميرا من خلال واجهة Mapbox.
• في تطبيق أحادي الصفحة، استدعِ handle.destroy() عند إزالة عرض الخريطة، وثبّته مجددًا عند العودة.

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

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

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