استخدام خريطة Kaleidr أساسية

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

قبل البدء

مفتاح قابل للنشر (kld_pk_live_…) من kaleidr.com/api-keys. راجع الحصول على مفتاح API.
مصدر صفحتك التجريبية، مثل http://localhost:3000، ضمن المصادر المسموح بها في المفتاح. يعمل المفتاح الذي لا يحدد مصادر مسموحًا بها على أي موقع.
وسيلة لتقديم الصفحة عبر HTTP، مثل npx serve .. لا تتمتع الصفحة المفتوحة من القرص بمصدر صالح، لذا يرفضها المفتاح الذي يقيّد المصادر.
إذا كان موقعك يطبق سياسة أمان المحتوى، فأضف https://cdn.kaleidr.com إلى script-src، وhttps://api.kaleidr.com إلى connect-src، وhttps://map-embed.kaleidr.com إلى frame-src. راجع سياسة أمان المحتوى.

الخطوة 1: إضافة الخريطة

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="tile"
             publishable-key="kld_pk_live_…"
             style-id="kaleidr-morning"
             style="display:block; height:480px"></kaleidr-map>

النتيجة المتوقعة: يظهر مؤشر «Loading map…» ثم خريطة أساسية فاتحة. في تبويب Network، يظهر طلب POST إلى https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions بحالة 200، يليه طلب مستند إلى https://map-embed.kaleidr.com/. يحتوي عنوان إطار iframe على معرّف التصميم فقط، دون بيانات اعتماد؛ يُرسل مفتاحك عند إنشاء الجلسة وحده، ولا يوضع رمز الجلسة في عنوان الإطار.

يجب تحديد ارتفاع للعنصر؛ وإلا تستخدم الخريطة ارتفاعًا ثابتًا يبلغ 500 بكسل. يستخدم <kaleidr-map> القيمة display:block افتراضيًا، لذا يعمل الارتفاع المحدد. أبقِ هذه القيمة في CSS أيضًا لدعم Safari قبل الإصدار 16.4، حيث يظل العنصر inline ويتجاهل height. (display:block)

الخطوة 2: اختيار التصميم

اضبط style-id على أحد التصاميم العامة التالية:

`style-id`	المظهر
`kaleidr-morning`	فاتح: أرضية بيضاء ومياه سماوية وطرق بيضاء.
`kaleidr-afternoon`	أرضية بدرجة متوسطة ونباتات خضراء وطرق رمادية.
`kaleidr-evening`	ألوان الساعة الذهبية: رمل دافئ ودرجات زيتونية.
`kaleidr-night`	أزرق كحلي وفحمي داكن مع طرق رئيسية كهرمانية.
`kaleidr-plain`	مساحة بيضاء تضم الحدود وأسماء الأماكن. تظهر المباني ثلاثية الأبعاد بدءًا من مستوى تكبير 15.
`kaleidr-editorial`	ألوان ما بعد الظهر دون تسميات، للخرائط الصغيرة أو الزخرفية.

<kaleidr-map product="tile" publishable-key="kld_pk_live_…"
             style-id="kaleidr-night"
             style="display:block; height:480px"></kaleidr-map>

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

مرّر style-id دائمًا. عند حذفه يستخدم التضمين خريطة مؤسستك الأساسية الافتراضية إن وُجدت؛ وإلا يعرض الإطار «Couldn't find a map id in the URL.».

يجب كتابة معرّفات التصاميم بدقة. لا توجد أسماء مختصرة: night ليس بديلًا عن kaleidr-night.

الخطوة 3: ضبط الكاميرا

من دون إعدادات كاميرا، تُفتح الخريطة على العرض الافتراضي للتصميم، وهو غالبًا العالم بأكمله. مرّر center (خط الطول أولًا ثم خط العرض) وzoom لعرض المنطقة المطلوبة. تعمل pitch على إمالة العرض وbearing على تدويره.

<kaleidr-map product="tile" publishable-key="kld_pk_live_…"
             style-id="kaleidr-morning"
             center="-0.1276,51.5072" zoom="12" pitch="45" bearing="-20"
             style="display:block; height:480px"></kaleidr-map>

النتيجة المتوقعة: وسط لندن مع إمالة وتدوير.

يُتجاهل zoom ما لم تمرّر center أيضًا. يمكن استخدام pitch وbearing منفصلين.

الخطوة 4: تحريك الكاميرا وتغيير التصميم برمجيًا

العنصر هو الصيغة التصريحية. للتحكم من JavaScript، ثبّت الخريطة باستخدام Kaleidr.mount واحتفظ بكائن التحكم الذي تُرجعه الدالة.

<div id="basemap" style="height:480px"></div>
<p>
  <button id="paris">Fly to Paris</button>
  <button id="night">Night</button>
  <button id="day">Morning</button>
</p>

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<script>
  const handle = Kaleidr.mount('#basemap', {
    product: 'tile',
    publishableKey: 'kld_pk_live_…',
    styleId: 'kaleidr-morning',
    center: [-0.1276, 51.5072],
    zoom: 11,
  });

  document.getElementById('paris').addEventListener('click', () => {
    // duration is in milliseconds. Leave it out to jump with no animation.
    handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 1200 });
  });
  document.getElementById('night').addEventListener('click', () => {
    handle.setStyle('kaleidr-night');
  });
  document.getElementById('day').addEventListener('click', () => {
    handle.setStyle('kaleidr-morning');
  });
</script>

النتيجة المتوقعة: يغيّر كل زر الخريطة في مكانها. لا يُعاد تحميل iframe ولا يظهر طلب جلسة جديد في Network.

نقاط مهمة:

الدالتان setCamera وsetStyle موجودتان في كائن التحكم، لا على العنصر نفسه.
تتوفر setStyle في Tile فقط، وتعرض تحذيرًا من دون تنفيذ أي إجراء على المنتجات الأخرى.
يمكنك استدعاء دوال التحكم بعد عودة Kaleidr.mount في أي وقت. تُحفظ الاستدعاءات التي تسبق جاهزية الخريطة داخل iframe، ثم تُطبّق بالترتيب عند جاهزيتها؛ فلا حاجة إلى انتظار رسالة kaleidr-embed:ready في الخطوة 6. استخدم خيارات التثبيت لاختيار التصميم والكاميرا عند بدء العرض.
بعد تثبيت العنصر، يؤدي تغيير center أوzoom أوpitch أوbearing إلى تحريك الخريطة، بينما لا يغيّر تعديل style-id شيئًا.

الخطوة 5: ربط لوحة محادثة بالخريطة (اختياري)

يمكن للوحة Kaleidr Chat التحكم بخريطة Tile: إذ تعرض الأماكن الواردة في الإجابات كعلامات وتضبط الكاميرا لإظهارها. ضع عنصر Tile داخل حاوية محددة الموضع، ثم ضع عنصر المحادثة فوقه واجعل map-target يشير إلى عنصر Tile.

<div style="position:relative">
  <kaleidr-map id="basemap" product="tile"
               publishable-key="kld_pk_live_…"
               style-id="kaleidr-morning"
               center="-0.1276,51.5072" zoom="11"
               style="display:block; height:560px"></kaleidr-map>

  <kaleidr-map product="chat" publishable-key="kld_pk_live_…" contained
               map-target="#basemap"
               style="display:block; position:absolute; inset:0; z-index:1; pointer-events:none"></kaleidr-map>
</div>

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

النتيجة المتوقعة: تظهر لوحة المحادثة أعلى يسار الخريطة. اسأل «coffee near Covent Garden» وستظهر علامات على خريطة Tile.

وظائف سمات عنصر المحادثة وأنماطه:

الجزء	الوظيفة
`map-target="#basemap"`	محدّد CSS لعنصر Tile الذي تتحكم به المحادثة.
`contained`	يثبّت اللوحة داخل عنصر المحادثة، وإلا تظهر ثابتة أعلى يسار نافذة المتصفح.
`position:absolute; inset:0`	يمد عنصر المحادثة فوق الخريطة لتثبيت اللوحة في زاويتها.
`z-index:1`	يبقي طبقة المحادثة فوق الخريطة.
`pointer-events:none`	يتيح سحب الخريطة وتكبيرها خارج اللوحة، مع بقاء اللوحة قابلة للنقر.

ملاحظات:

يصلح المفتاح نفسه لكلا العنصرين لأن المفتاح الافتراضي يتضمن النطاقين maps وai. يطلب عنصر المحادثة جلسة مستقلة، وتستهلك كل رسالة أرصدة الذكاء الاصطناعي.
ترتيب العنصرين غير مهم؛ تبحث لوحة المحادثة عن الخريطة حين تحتاج إليها.

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

الخطوة 6: معرفة اكتمال تحميل الخريطة (اختياري)

لا يقدم SDK وعد ready ولا يرسل العنصر أحداثًا. يرسل iframe إلى الصفحة رسالة عند رسم الخريطة لأول مرة ورسالة أخرى إذا تعذر رسم جزء منها:

const target = document.getElementById('basemap');

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://map-embed.kaleidr.com') return;
  const frame = target.querySelector('iframe');
  if (!frame || event.source !== frame.contentWindow) return;

  const msg = event.data;
  if (!msg || typeof msg.type !== 'string') return;

  if (msg.type === 'kaleidr-embed:ready') {
    // { type, id: 'kaleidr-morning', source: 'tile' }
    console.log('basemap loaded', msg.id);
  } else if (msg.type === 'kaleidr-embed:error') {
    // { type, id, code: 'maplibre_error', message }, or
    // { type, id: null, code: 'no_id', message } when there is no style
    console.warn('basemap problem', msg.code, msg.message);
  }
});

لا تصل أي رسالة عند فشل إنشاء الجلسة، لأن iframe لا يُنشأ أصلًا. يظهر الخطأ في وحدة التحكم. راجع إذا لم يعمل.

صفحة كاملة

احفظ المثال باسم 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 basemap</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 2rem; }
    #basemap { height: 480px; }
  </style>
</head>
<body>
  <h1>Kaleidr basemap</h1>
  <p id="status">Loading the map…</p>

  <div id="basemap"></div>
  <p>
    <button id="paris">Fly to Paris</button>
    <button id="night">Night</button>
    <button id="day">Morning</button>
  </p>

  <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
  <script>
    const target = document.getElementById('basemap');
    const status = document.getElementById('status');

    const handle = Kaleidr.mount(target, {
      product: 'tile',
      publishableKey: 'kld_pk_live_…',
      styleId: 'kaleidr-morning',
      center: [-0.1276, 51.5072],
      zoom: 11,
    });

    window.addEventListener('message', (event) => {
      if (event.origin !== 'https://map-embed.kaleidr.com') return;
      const frame = target.querySelector('iframe');
      if (!frame || event.source !== frame.contentWindow) return;
      const msg = event.data;
      if (msg && msg.type === 'kaleidr-embed:ready') {
        status.textContent = 'Map loaded.';
      }
    });

    document.getElementById('paris').addEventListener('click', () => {
      handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 1200 });
    });
    document.getElementById('night').addEventListener('click', () => {
      handle.setStyle('kaleidr-night');
    });
    document.getElementById('day').addEventListener('click', () => {
      handle.setStyle('kaleidr-morning');
    });

    // In a single-page app, call handle.destroy() when the map leaves the screen.
  </script>
</body>
</html>

آلية العمل

الموضوع	السلوك
الجلسة	يستبدل SDK مفتاحك بجلسة Tile قصيرة العمر قبل إنشاء iframe، ثم يجددها ما دام العنصر مثبتًا. تتحقق العملية من المفتاح وتحتسب تحميلًا واحدًا للخريطة. لا تُمرّر الجلسة إلى iframe الذي يتضمن عنوانه التصميم والكاميرا فقط.
العرض عند الفتح	إعدادات الكاميرا التي تمرّرها، وإلا عرض التصميم الافتراضي.
التمرير	يكبّر التمرير الخريطة حين يكون المؤشر فوقها. وحين يكون المؤشر خارج الخريطة يحرّك التمرير صفحتك. على الشاشات اللمسية، يحرّك السحب الخريطة ويكبّرها ضم الأصابع.
الارتفاع	يعتمد ارتفاع عنصر التثبيت عند إنشائه، وإلا يكون 500 بكسل ثابتًا.
التحميل	يُحمّل iframe عند الاقتراب من المنطقة المرئية.
الإزالة	تزيل `handle.destroy()` الإطار وتوقف تجديد الجلسة. وينطبق ذلك أيضًا على حذف عنصر `<kaleidr-map>`.
إعادة الإدراج	تؤدي إعادة إدراج عنصر محذوف أو نقله إلى أصل مختلف إلى تثبيت جديد وجلسة جديدة.

كيفية احتساب مرات تحميل الخرائط

تُحتسب مرة تحميل واحدة كلما حصل SDK على جلسة Tile:

الحدث	مرات تحميل الخريطة
تثبيت الخريطة	1
تجديد الجلسة مع استمرار التثبيت	1 لكل تجديد
حذف التثبيت وإعادته أو إعادة إدراج العنصر	1
`setCamera` أو `setStyle` أو تحريك الخريطة أو تكبيرها	0

تدوم الجلسة افتراضيًا 15 دقيقة، ويجددها SDK قبل انتهائها بـ90 ثانية سواء في الواجهة أو الخلفية. تستهلك الزيارة القصيرة تحميلًا واحدًا، بينما تستهلك الصفحة المفتوحة لمدة ساعة نحو خمس مرات تحميل.

لتقليل الاستخدام:

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

إذا استنفدت مؤسستك الحد المسموح لعمليات تحميل الخرائط خلال الفترة، تُرفض الجلسة الجديدة برمز HTTP 429 والاستجابة {"detail":"map_load_quota_exceeded"}. تبقى الخريطة المعروضة ظاهرة، لكن التثبيت الجديد لا يعرض شيئًا. راجع الحصص وحدود المعدل.

التحقق من عمل الخريطة

في الصفحة: تعمل الخريطة تفاعليًا وتظهر معلومات نسب المصادر أسفلها.
في وحدة التحكم: لا يوجد سطر يحتوي [kaleidr.
في Network: يُحمّل kaleidr.js وtile.js من https://cdn.kaleidr.com، ويعيد POST …/sdk/sessions الحالة 200 مع حقلي session_token وexpires_in، ثم يظهر طلب مستند إلى https://map-embed.kaleidr.com/?style=….
في مستمع الأحداث: رسالة kaleidr-embed:ready قيمتها source هي "tile".

إذا لم يعمل

يسجل SDK فشل التثبيت في وحدة التحكم بالصيغة [kaleidr:tile] …. وعند رفض الجلسة، يسجل رمز HTTP فقط. اقرأ السبب من استجابة طلب sessions في Network. يحمل رفض 403 الرمز في detail، وكذلك map_load_quota_exceeded، أما 429 من النوع rate_limited فيحمله في error.

العَرَض	السبب	الحل
لا يظهر شيء، وخطأ CORS في `…/sdk/sessions` مع خطأ `[kaleidr:tile]`	المفتاح غير معروف أو ملغى، أو المصدر غير مسموح به؛ ولا تحتوي الاستجابة المرفوضة على ترويسات CORS.	افحص المفتاح وأضف المصدر الدقيق (البروتوكول والمضيف والمنفذ) في kaleidr.com/api-keys، وانتظر دقائق ثم أعد التحميل. يظهر رمز 401 أو 403 في Network.
`[kaleidr:tile] kaleidr session exchange failed (403)`	يفتقر المفتاح إلى `maps` (`insufficient_scope`)، أو يقتصر على منتجات أخرى (`product_not_allowed`)، أو لا تسمح الخطة بالطلب (`tier_capability_not_allowed`).	راجع `detail` في Network، وأنشئ مفتاحًا بالنطاقات الافتراضية.
`[kaleidr:tile] kaleidr session exchange failed (429)`	انتهت حصة تحميل الخرائط (`map_load_quota_exceeded`) أو زاد معدل الطلبات (`rate_limited`).	راجع `detail` للأول و`error` للثاني، ثم الحصص وحدود المعدل.
يعيد طلب `sessions` الحالة 404	تجاوز `api-base` لا يحتوي `/inference-api`.	أزل التجاوز أو استخدم `https://api.kaleidr.com/inference-api`.
`[kaleidr:tile] Kaleidr: a server key (kld_sk_…) must never be used in the browser…`	استُخدم مفتاح خادم، ويرفضه SDK قبل أي طلب.	استخدم مفتاحًا قابلًا للنشر وبدّل مفتاح الخادم إذا كُشف سابقًا.
`[kaleidr:tile] Kaleidr tile: invalid style "…"…`	يحتوي `style-id` على حرف غير مسموح به، مثل مسافة أو `?`.	استخدم معرّفًا من الخطوة 2.
يعرض الإطار «Couldn't find a map id in the URL.» ويستقبل المستمع `code: 'no_id'` و`id: null`	لم يُحدد `style-id` ولا توجد خريطة أساسية افتراضية للمؤسسة.	مرّر `style-id`.
إطار فارغ ورسالة `kaleidr-embed:error` مع `maplibre_error`	التصميم غير موجود، غالبًا لخطأ في معرّفه.	اختر معرّفًا من الخطوة 2.
`[kaleidr] <kaleidr-map> requires product="chat\|viewer\|editor\|tile"`	السمة `product` مفقودة أو خاطئة.	اضبط `product="tile"`.
يبقى ارتفاع الخريطة 500 بكسل	لم يكن للعنصر ارتفاع عند التثبيت، أو كان `display:inline`، أو كان Safari قبل 16.4 دون `display:block`.	أضف ارتفاعًا و`display:block`. `height`
مساحة فارغة وخطأ سياسة أمان محتوى	تحظر السياسة برنامج التحميل أو طلب الجلسة أو الإطار.	اسمح بالمضيفين الثلاثة في قبل البدء.
لا تعمل `setStyle` أو `setCamera`	استُدعيت الدالة على العنصر أو لم تجهز الخريطة بعد.	استدعها على كائن التحكم من `Kaleidr.mount`. افحص `kaleidr-embed:error` ووحدة التحكم؛ تُطبق الاستدعاءات المبكرة عند الجاهزية. إذا لم تُبلغ الخريطة عن جاهزيتها خلال مهلة محدودة، تكون عادةً 10 ثوانٍ بعد تحميل إطار iframe، تُرسل الاستدعاءات رغم ذلك، وتعرض وحدة التحكم `[kaleidr] the map frame has not reported ready`؛ ولا توجد خريطة لتحريكها أو تعديلها في إطار يعرض خطأ.
لا يؤدي تغيير `style-id` على العنصر إلى شيء	سلوك متوقع؛ يُقرأ `style-id` مرة واحدة عند التثبيت.	استخدم `handle.setStyle` أو أدرج عنصرًا جديدًا.

القيود

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

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

مرجع Tile لجميع الخيارات والسمات والرسائل.
تكامل أطر العمل للتثبيت والإزالة في React وNext.js وVue دون تحميلات إضافية.
Chat لإضافة المساعد إلى الخريطة.
الحصص وحدود المعدل لمراجعة الحصص المسموح بها لتحميل الخرائط.

قبل البدء​

الخطوة 1: إضافة الخريطة​

الخطوة 2: اختيار التصميم​

الخطوة 3: ضبط الكاميرا​

الخطوة 4: تحريك الكاميرا وتغيير التصميم برمجيًا​

الخطوة 5: ربط لوحة محادثة بالخريطة (اختياري)​

الخطوة 6: معرفة اكتمال تحميل الخريطة (اختياري)​

صفحة كاملة​

آلية العمل​

كيفية احتساب مرات تحميل الخرائط​

التحقق من عمل الخريطة​

إذا لم يعمل​

القيود​

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