البدء السريع

ترشدك هذه الصفحة إلى أقصر ثلاثة مسارات تكامل عاملة، بالترتيب الذي تحتاجه معظم الفرق:

1. Chat على خريطة تستخدمها بالفعل. لوحة دردشة تجيب عن أسئلة الأماكن وتضع الإجابات على خريطتك في صورة دبابيس وتحركات كاميرا ومسارات.
2. خريطة منشورة. خريطة صممتها في Kaleidr Studio وتضمّنها في صفحتك.
3. خريطة أساسية. خريطة صممها Kaleidr وجاهزة للاستخدام في صفحتك.

كل مسار عبارة عن ملف HTML واحد. وتعمل المسارات الثلاثة ضمن خطة Free.

المسار	المنتج	المفتاح المطلوب	مكان العرض
Chat على خريطتك	chat	مفتاح قابل للنشر	داخل صفحتك فوق خريطتك
خريطة منشورة	viewer	لا شيء	داخل iframe من Kaleidr
خريطة أساسية	tile	مفتاح قابل للنشر	داخل iframe من Kaleidr

إذا فضّلت فهم النموذج أولًا فاقرأ آلية عمل Kaleidr، وإذا كنت غير متأكد من المنتج المناسب فراجع اختر مسارك.

قبل البدء

• حساب Kaleidr. سجّل في kaleidr.com. خطة Free تكفي لكل ما في هذه الصفحة.

• مفتاح قابل للنشر لمساري Chat والخريطة الأساسية. أنشئه من kaleidr.com/api-keys، وتبدأ قيمته بـkld_pk_live_. يشرح الحصول على مفتاح API نموذج الإنشاء. مسار الخريطة المنشورة لا يحتاج إلى مفتاح.

• خادم ويب للصفحة. قدّم الملف عبر HTTP حتى أثناء التطوير محليًا. من مجلد الملف شغّل أحد الخيارين التاليين:

  python -m http.server 8000
  # or
  npx serve -l 8000

  ثم افتح http://localhost:8000/your-file.html. لا تفتح الملف من القرص مباشرة: فالصفحة التي تستخدم file:// لا تملك أصلًا يمكن إضافته إلى الأصول المسموح بها للمفتاح.

• أصل صفحتك ضمن قائمة المفتاح، إن وُجدت. يعمل المفتاح الذي لا يحدد أصولًا مسموحًا بها من جميع المواقع. أما الذي يحدد قائمة فلا يعمل إلا من المواقع المدرجة، لذا أضف http://localhost:8000 أثناء الاختبار.

• سياسة أمن محتوى تسمح بتحميل Kaleidr إذا كان موقعك يستخدم واحدة. لا تحتاج الصفحة التي لا ترسل ترويسة Content-Security-Policy إلى إعداد إضافي. وإلا فراجع سياسة أمن المحتوى.

تبدأ المسارات جميعها بعلامة script نفسها. هذا هو الملف الوحيد الذي تحمّله بنفسك، وهو يحمّل شيفرة كل منتج عند تركيبه.

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

Chat على خريطتك

ستحصل على خريطة MapLibre GL JS مع لوحة دردشة داخلها. عند سؤال «Where can I get ramen near Bryant Park?» تظهر الإجابة تدريجيًا، وتُوضع دبوس لكل مكان، وتتحرك الكاميرا لإظهار الأماكن.

يستخدم المثال MapLibre GL JS. ويمكن ربط Chat أيضًا بـMapbox GL JS وGoogle Maps JavaScript API وLeaflet. راجع الخرائط المدعومة.

1. أنشئ الصفحة

احفظ الملف باسم chat.html واستبدل kld_pk_live_… بمفتاحك القابل للنشر.

<!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; }
      /* The chat panel docks inside this box, so it must be positioned and sized. */
      #stage { position: relative; height: 100vh; }
      #map { position: absolute; inset: 0; }
    </style>
  </head>
  <body>
    <div id="stage">
      <div id="map"></div>
    </div>

    <!-- 1. Your map library, loaded as a page global (window.maplibregl). -->
    <script src="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.js"></script>
    <!-- 2. The Kaleidr loader. -->
    <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', // replace with your own style
        center: [-73.9857, 40.7484], // [longitude, latitude]
        zoom: 11,
      });

      const chat = Kaleidr.mount('#stage', {
        product: 'chat',
        publishableKey: 'kld_pk_live_…',
        map,             // the live map instance, not a selector
        contained: true, // dock the panel inside #stage
      });

      // When you remove the map (for example on a route change in a single-page app):
      // chat.destroy();
    </script>
  </body>
</html>

هناك ثلاث نقاط مهمة في هذا الملف:

• مكتبة الخرائط متغير عام على الصفحة. تبحث شيفرة Chat عن MapLibre في window.maplibregl. ويضبط تحميل MapLibre بعلامة script هذا المتغير تلقائيًا. إذا استوردتها من npm، فعيّنه بنفسك قبل التركيب: window.maplibregl = maplibregl.
• map هو كائن الخريطة. مرّر النسخة التي أنشأتها لا محدّد CSS.
• يتطلب contained: true عنصرًا ذا موضع محدد وارتفاع. تُعرض اللوحة داخل عنصر التركيب. من دون contained تصبح نافذة ثابتة أعلى يسار المتصفح بغض النظر عن موضع الخريطة.

نمط العرض التجريبي خريطة عالمية قليلة التفاصيل. تقع الدبابيس في الإحداثيات الصحيحة، لكن استخدم نمطك الخاص لرؤية الشوارع.

2. قدّم الصفحة واسأل سؤالًا

شغّل خادمًا محليًا في مجلد الملف وافتح http://localhost:8000/chat.html.

ما ينبغي أن تراه:

• تملأ الخريطة النافذة وتظهر في أعلى يسارها لوحة دردشة تحتوي حقل إدخال نصي.
• في علامة Network بالمتصفح، يعيد طلب إلى https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions الحالة 200. وهو تبادل المفتاح بجلسة قصيرة العمر عبر SDK.
• اكتب سؤالًا عن الأماكن مثل Where can I get ramen near Bryant Park?. تتدفق الإجابة نصيًا وتظهر دبابيس على الخريطة لكل مكان وتتحرك الكاميرا لتشملها. في Network يظهر طلب إلى …/b2b/v1/chat/control/stream يظل مفتوحًا أثناء بث الإجابة.
• لا تظهر في وحدة التحكم أسطر تحتوي [kaleidr.

3. إذا لم يعمل

ما تراه	السبب	الحل
لا توجد لوحة وتظهر أخطاء CORS لـ…/sdk/sessions يتبعها خطأ [kaleidr:chat]	المفتاح خاطئ أو ملغى أو أصل الصفحة غير مدرج في الأصول المسموح بها. لا يعيد API ترويسات CORS لهذه الحالات، فيظهر للمتصفح خطأ CORS	تحقق من المفتاح. أضف أصلك الدقيق بما فيه المنفذ في kaleidr.com/api-keys، أو امسح القائمة أثناء الاختبار.
اللوحة في أعلى يسار نافذة المتصفح لا داخل الخريطة	خيار contained: true مفقود أو موضع عنصر التركيب غير محدد	مرّر contained: true واضبط position: relative وارتفاعًا للعنصر المستهدف.
تجيب اللوحة لكن لا تظهر دبابيس	مكتبة الخرائط غير متاحة في متغير عام، فلا يستطيع Chat إنشاء الدبابيس	حمّل المكتبة بعلامة script أو اضبط window.maplibregl قبل Kaleidr.mount.

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

الخطوة التالية لهذا المسار: ربط Chat بـMapLibre للدليل الكامل، والإمكانات والقيود لمعرفة ما تفعله اللوحة وما لا تفعله.

خريطة منشورة

ستعرض خريطة صممتها في Kaleidr Studio داخل صفحتك. لا يتطلب هذا المسار مفتاح API؛ فالمعرّف العام للخريطة المنشورة هو كل ما يحتاجه التضمين.

1. انشر الخريطة وانسخ معرّفها

1. افتح خريطتك في Kaleidr Studio واختر Publish.
2. في صفحة Publish & embed اختر Go Live.
3. تحت Embed code انسخ الشيفرة. المعرّف هو آخر جزء من عنوانها: في https://map-embed.kaleidr.com/embed/abc123 يكون المعرّف abc123.

ما ينبغي أن تراه: تعرض حالة المشروع live، وتظهر معاينة حية أسفل رمز التضمين للخريطة كما سيشاهدها الزوار.

2. أنشئ الصفحة

احفظ الملف باسم map.html واستبدل YOUR_SHARE_ID بالمعرّف الذي نسخته.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>A published Kaleidr map</title>
  </head>
  <body>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

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

يحتاج العنصر إلى ارتفاع؛ من دونه يعود ارتفاع الخريطة إلى 500 بكسل. يُعرض <kaleidr-map> افتراضيًا باستخدام display:block، لذا يُطبّق الارتفاع. ويكتب المثال display:block أيضًا؛ ولا يسبب مشكلة في المتصفحات الحديثة، كما يدعم Safari قبل 16.4 حيث يبقى العنصر مضمنًا ولا ينطبق الارتفاع.

إن تعذر إضافة script إلى الصفحة، مثل منشئ المواقع أو حقل في CMS، فاستخدم iframe العادي الذي يولده تبويب iFrame في Studio. ولا يحتاج إلى المحمّل.

<iframe
  src="https://map-embed.kaleidr.com/embed/YOUR_SHARE_ID"
  width="100%"
  height="480"
  style="border:0;"
  loading="lazy"
  referrerpolicy="no-referrer-when-downgrade"
  allow="geolocation; microphone; fullscreen; clipboard-write"
  title="Kaleidr map"
></iframe>

3. قدّم الصفحة

افتح http://localhost:8000/map.html.

ما ينبغي أن تراه:

• خريطتك بارتفاع 480 بكسل وعرض الصفحة، تبدأ من العرض الذي حفظته في Studio.
• يكبّر التمرير الخريطة حين يكون المؤشر فوقها. وحين يكون المؤشر بجانب الخريطة يحرّك التمرير الصفحة.
• في لوحة Elements يظهر <iframe> داخل <kaleidr-map>، ويبدأ عنوانه بـhttps://map-embed.kaleidr.com/embed/.

إذا أظهر الإطار "This map isn't available — it may have been unpublished, paused, or the link is incorrect." فالمعرّف خاطئ أو الخريطة ليست منشورة. وإذا أظهر "This map isn't allowed to render on this site. Please contact the map owner." فالخريطة مقيدة بنطاقات أخرى.

الخطوة التالية لهذا المسار: يشرح تضمين خريطة تقييد النطاقات المسموح لها بعرضها، ويضيف Chat على خريطة منشورة لوحة دردشة يستخدمها الزوار من دون مفتاح.

خريطة أساسية

ستعرض خريطة أساسية صممها Kaleidr في صفحتك، خريطة تفاعلية مكتملة لا تحتاج إلى تثبيت مكتبة خرائط أو كتابة نمط.

1. أنشئ الصفحة

احفظ الملف باسم basemap.html واستبدل kld_pk_live_… بمفتاحك القابل للنشر.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>A Kaleidr basemap</title>
  </head>
  <body>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

    <kaleidr-map
      product="tile"
      publishable-key="kld_pk_live_…"
      style-id="kaleidr-morning"
      center="-73.9857,40.7484"
      zoom="11"
      style="display:block; height:480px"
    ></kaleidr-map>
  </body>
</html>

• يحدد style-id الخريطة الأساسية. اضبطه دائمًا. kaleidr-morning أحد الأنماط العامة؛ ويسرد Tile الأنماط الأخرى.
• center بالترتيب longitude,latitude. اضبط center عند ضبط zoom؛ إذ يُتجاهل zoom من دون center.

2. قدّم الصفحة

افتح http://localhost:8000/basemap.html.

ما ينبغي أن تراه:

• خريطة أساسية تتمركز عند وسط مانهاتن وارتفاعها 480 بكسل.
• في Network طلب إلى https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions يعيد 200، ثم إطار iframe يُحمّل من https://map-embed.kaleidr.com.
• يكبّر التمرير الخريطة حين يكون المؤشر فوقها.

إذا لم يظهر شيء وظهرت مشكلة CORS لعنوان …/sdk/sessions، فالمفتاح خاطئ أو أصل صفحتك ليس في قائمة الأصول المسموح بها، كما في مسار Chat.

تُحتسب لكل جلسة Tile حمولة خريطة واحدة من حصة مؤسستك الشهرية. راجع الحصص وحدود المعدل.

الخطوة التالية لهذا المسار: استخدام Tile يشرح تبديل الأنماط أثناء التشغيل وتحريك الكاميرا.

ما حمّلته

استخدمت المسارات الثلاثة المكوّنين نفسيهما:

• Kaleidr.mount(target, options) يركّب منتجًا من JavaScript ويعيد مقبض التحكم فورًا. تُحمّل شيفرة المنتج في الخلفية، وتُحفظ استدعاءات المقبض قبل جاهزية المنتج ثم تُطبّق بالترتيب عند جهوزيته.
• <kaleidr-map> ينفّذ الشيء نفسه من HTML. سماته هي خيارات التركيب بصيغة الواصلة (share-id وstyle-id وpublishable-key) مع استثناءين: الخيار enabled يقابله السمة flag، وخيار Chat المسمى title يقابله chat-title.

استخدم Kaleidr.mount لربط Chat بخريطتك لأنه يحتاج إلى كائن الخريطة المباشر. ويمكنك استخدام أي من الصيغتين للمنتجات الأخرى.

يملك المقبض destroy() في جميع المنتجات. أما الطرق الأخرى فتختلف: تعمل setCamera مع viewer وtile وeditor، لكنها لا تعمل مع chat؛ إذ يحرّك المساعد خريطتك عند الإجابة، وتستمر أنت في استخدام أدوات الكاميرا الخاصة بمكتبة الخرائط. راجع المصفوفة الكاملة في عنصر <kaleidr-map>.

قيود ينبغي معرفتها الآن

• يضيف Chat دبابيسه ومساراته وتحركات الكاميرا الخاصة به. لا يغيّر طبقاتك أو علاماتك ولا يرسلها إلى Kaleidr، ولا تتلقى صفحتك أحداثًا من اللوحة. راجع الإمكانات والقيود.
• يعمل Viewer وTile داخل iframe. لا يمكنك إضافة طبقات أو علامات خاصة بك إليهما. إن احتجت تلك الطبقات فاحتفظ بخريطتك واربط Chat بها.
• يُعرض نمط خريطة Kaleidr الأساسية عبر Tile. تحميل أنماط Kaleidr أو مربعاتها مباشرة في مكتبة الخرائط الخاصة بك غير مدعوم.
• SDK مخصص لصفحات الويب. لا توجد حزمة npm ولا SDK أصلي لتطبيقات الجوال. تستدعي الخوادم الخلفية واجهة الخادم.
• تستهلك عمليات التركيب التي تتطلب مفاتيح من حصتك. تستهلك إجابات Chat أرصدة الذكاء الاصطناعي، وتستهلك جلسات Tile تحميلات الخرائط. راجع آلية عمل Kaleidr.

أي مسار بعد ذلك

ما تريد فعله	اقرأ
ربط Chat بـMapbox GL JS	ربط Chat بـMapbox
ربط Chat بـMapLibre GL JS	ربط Chat بـMapLibre
ربط Chat بـGoogle Maps	ربط Chat بـGoogle Maps
ربط Chat بـLeaflet	ربط Chat بـLeaflet
تحديد موضع اللوحة ومطابقة ألوان علامتك التجارية	المظهر والتخطيط
تمكين الزوار من Chat على خريطة منشورة	Chat على خريطة منشورة
تضمين خريطة منشورة وتقييد نطاقاتها	تضمين خريطة
عرض خريطة أساسية وتبديل نمطها	استخدام Tile
وضع محرر خرائط داخل صفحتك	ربط المحرر
استخدام SDK من React أو Next.js أو Vue	أطر العمل
استدعاء Kaleidr من نظامك الخلفي	البدء السريع للخادم
استخدام بيانات مؤسستك في الإجابات	بياناتك
الإطلاق في الإنتاج	قائمة مراجعة الإنتاج