إرفاق Kaleidr Chat بخريطة Google

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

مفتاح Google Maps ومفتاح Kaleidr منفصلان. تتولى Google فوترة الخريطة، ويتولى Kaleidr فوترة الأسئلة. ولا يتلقى Kaleidr مفتاح Google الخاص بك مطلقًا.

قبل البدء

• مفتاح Kaleidr قابل للنشر (kld_pk_live_…) من kaleidr.com/api-keys. تتضمن المفاتيح الجديدة نطاق ai اللازم للمحادثة. راجع الحصول على مفتاح API.
• أصل صفحتك ضمن الأصول المسموح بها للمفتاح إذا حُدّدت قائمة؛ وأضف للاختبار المحلي أصلًا مثل http://localhost:8080.
• مفتاح Google Maps JavaScript API من مشروعك في Google Cloud، مع تفعيل Maps JavaScript API والسماح بأصل موقعك ضمن قيود المُحيل الخاصة به.
• وسيلة لتقديم الصفحة عبر HTTP مثل npx serve أو python -m http.server 8080؛ فالفتح مباشرة من القرص لا يعمل.
• إذا كانت الصفحة تستخدم سياسة أمان المحتوى، اسمح بالمضيفين الواردين في سياسة أمان المحتوى، إضافة إلى مضيفي Google Maps الضروريين.

تعرّف واجهة Google Maps JavaScript API الكائن العام google.maps دائمًا، لذلك لا حاجة إلى خطوة إضافية لإتاحة المكتبة لحزمة المحادثة.

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

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

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

يملأ عنصر الخريطة الحاوية باستخدام height:100%. ويحافظ الجمع بين position:relative وz-index:0 على طبقات Google داخل عنصر الخريطة وأسفل طبقة المحادثة.

ما ينبغي أن يظهر: مساحة فارغة بارتفاع 520 px في هذه المرحلة.

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

حمّل ملف تشغيل Kaleidr بوسم script عادي كي يصبح Kaleidr متاحًا عند تشغيل دالة رد الاتصال الخاصة بالخريطة.

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

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

الخطوة 3: تعريف دالة رد الاتصال التي تنشئ الخريطة وتثبت اللوحة

يستدعي نص Google Maps دالة تحدد اسمها بعد اكتمال التحميل. أنشئ الخريطة وثبّت اللوحة داخل تلك الدالة، لأن google.maps لا يكون متاحًا قبل تنفيذها.

<script>
  function initMap() {
    const map = new google.maps.Map(document.getElementById('map'), {
      center: { lat: 51.5, lng: -0.12 },
      zoom: 11,
    });

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

ما ينبغي أن يظهر: لا تغيير بعد؛ فقد عُرّفت الدالة لكن لم تُستدعَ.

الخطوة 4: تحميل نص Google Maps بعد تعريف دالة رد الاتصال

ضع وسم script الخاص بـ Google أسفل النص الذي يعرّف initMap.

<script async
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_GOOGLE_KEY&callback=initMap&loading=async&v=weekly"></script>

ترتيب التحميل مهم. يحمل نص Google الخاصية async، لذا ينفذه المتصفح فور تنزيله ويستدعي initMap مباشرة. إذا جاء وسمه أولًا، فقد يكتمل قبل وصول المتصفح إلى تعريف initMap، وتظهر رسالة Google بأن initMap ليست دالة. تعريف رد الاتصال أولًا يزيل حالة التسابق.

ما ينبغي أن يظهر: خريطة Google لوسط لندن وشريط إدخال يحمل عبارة 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 Google Maps</title>
    <style>
      body { margin: 0; font-family: system-ui, sans-serif; }
      #mapHost { position: relative; height: 100vh; }
      #map { position: relative; height: 100%; 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>

    <!-- 1. The Kaleidr loader. -->
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

    <!-- 2. The callback, defined before the Google script can call it. -->
    <script>
      function initMap() {
        const map = new google.maps.Map(document.getElementById('map'), {
          center: { lat: 51.5, lng: -0.12 },
          zoom: 11,
        });

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

    <!-- 3. The Google Maps script, last. -->
    <script async
      src="https://maps.googleapis.com/maps/api/js?key=YOUR_GOOGLE_KEY&callback=initMap&loading=async&v=weekly"></script>
  </body>
</html>

آلية العمل

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

تفاصيل خاصة بـ Google Maps:

• الدبابيس عناصر HTML تُرسم بطبقة مخصصة. ولا تحتاج Map ID. إذا حمّلت الصفحة مكتبة marker من Google، تستخدم حزمة المحادثة العلامات المتقدمة بدلًا منها، وتتطلب Google حينها وجود mapId للخريطة.
• الانتقال إلى مكان هو تحريك ثم تغيير تكبير، وليس حركة طيران واحدة.
• يستخدم ضبط الإطار هامشًا موحدًا قدره 56 px على جميع الجوانب. لا يعوّض مساحة اللوحة وقد يقع مكان خلفها؛ ويمكن للزائر تحريك الخريطة أو تصغير اللوحة.
• المسار خطان متعددَا المقاطع: خط أبيض أسفل خط ملوّن.
• تُعامل الخريطة بوصفها مسطحة وموجهة للشمال، ولا يضبط المساعد الاتجاه أو الميل.
• تُجدَّد الجلسة في الخلفية ما دامت اللوحة مثبتة، دون أن تتعامل أنت مع الرموز.

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

في الصفحة

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

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

• لا توجد أخطاء أو تحذيرات تتضمن [kaleidr ولا أخطاء من Google Maps API.

في تبويب 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.

العَرَض	السبب	الحل
الخريطة غائبة وخطأ Google يقول initMap is not a function	جرى تنفيذ نص Google قبل النص المعرّف لـ initMap.	انقل وسم Google إلى ما بعد دالة رد الاتصال كما في الخطوة 4.
لا خريطة أو خريطة رمادية مع نافذة خطأ Google	مفتاح Google غير مفعّل لـ Maps JavaScript API، أو الفوترة غير معدة، أو أصل الصفحة غير مسموح.	صحح إعدادات مشروع Google Cloud؛ وهذا مستقل عن Kaleidr.
يظهر Kaleidr is not defined داخل initMap	يحمل kaleidr.js الخاصية async أو defer، أو يأتي بعد نص Google.	حمّل kaleidr.js أولًا بوسم script عادي.
تظهر الخريطة دون اللوحة، وخطأ CORS عند …/sdk/sessions ثم رسالة تتضمن [kaleidr:chat]	مفتاح Kaleidr غير معروف أو ملغى، أو أصل الصفحة غير مسموح. ترسل 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] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/chat.js	حُظرت الحزمة، عادةً بسياسة أمان المحتوى أو مانع إعلانات.	اسمح بـ https://cdn.kaleidr.com في script-src.
تظهر اللوحة أعلى يسار نافذة المتصفح بدل الخريطة	contained مفقودة أو لم يُضبط موضع #chat.	أضف contained: true وأنماط الخطوة 1.
اللوحة خلف الخريطة	لا يملك عنصر الخريطة سياق تكديس منفصلًا.	أبق z-index:0 على #map وz-index:1 على #chat.
تجيب اللوحة دون دبابيس أو حركة للخريطة	كائن map ليس نسخة google.maps.Map، بل عنصر DOM أو غلاف مثلًا.	مرّر الكائن الذي ترجعه new google.maps.Map(…). راجع الخرائط المدعومة.
تجيب اللوحة وتتحرك الخريطة دون ظهور الدبابيس	حُمّلت مكتبة marker لكن الخريطة بلا mapId.	أضف mapId لخيارات الخريطة أو لا تحمل مكتبة marker.
يظهر "تعذر إرسال ذلك، حاول ثانية." لكل سؤال	الجلسة لم تعد صالحة لإلغاء المفتاح أو تغيير الأصول المسموحة.	تحقق من المفتاح ثم أعد تحميل الصفحة.
يظهر "بلغت حد الاستخدام حاليًا."	الخطأ 429: نفد رصيد AI للمؤسسة أو بلغ المفتاح حد المعدّل؛ كل زوار الصفحة يشتركون في الحد.	راجع الحصص وحدود المعدّل.

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

القيود

• لا تستقبل صفحتك رد اتصال أو حدثًا من اللوحة؛ فلا يمكنك التفاعل برمجيًا مع الأسئلة أو الإجابات أو نقر الدبابيس.
• لا يرى المساعد طبقاتك أو علاماتك أو منطقة العرض؛ ولا يُرسل مع السؤال سوى مستوى التكبير.
• لا يمكنك تمرير تعليمات للمساعد أو بياناتك الخاصة عبر اللوحة.
• تحدَّد لغة الإجابات وعنوان اللوحة والعنصر النائب للمدخل بخيارات التثبيت (lang وtitle وplaceholder)؛ راجع مرجع المحادثة. وتظل بقية تسميات اللوحة بالإنجليزية.
• لا يراعي ضبط الإطار تجنّب لوحة المحادثة في Google Maps.
• لا ينفّذ handle.setCamera() شيئًا عند تثبيت محادثة ويسجّل تحذيرًا؛ حرّك الخريطة عبر Google API.
• في تطبيق الصفحة الواحدة استدعِ handle.destroy() عند إزالة عرض الخريطة وأعد التثبيت عند عودته.

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

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

• المظهر والتخطيط: مواءمة اللوحة مع موقعك.
• الخرائط المدعومة: قدرات المساعد على Google Maps.
• مرجع Chat: الخيارات والمقبض والأخطاء.
• قائمة التحقق قبل الإنتاج: ما ينبغي التأكد منه قبل الإطلاق.