تضمين خريطة منشورة

بنهاية هذا الدليل ستكون الخريطة التي أنشأتها في Kaleidr Studio معروضة على صفحتك، مع إمكانية تقييد المواقع التي تظهر عليها ومعرفة نجاح تحميلها أو فشله. تعمل الميزة في جميع الخطط بما فيها Free. تحتاج إلى حساب Kaleidr للنشر، ولا تحتاج إلى مفتاح API.

قبل البدء

خريطة في Kaleidr Studio جاهزة للعرض العام.
صفحة يمكنك تعديلها. يحتاج عنصر SDK إلى وسم <script>، أما iframe العادي فيحتاج إلى HTML فقط.
إذا كان موقعك يطبّق سياسة أمان المحتوى، اسمح بالإطار https://map-embed.kaleidr.com وبتحميل النصوص البرمجية من https://cdn.kaleidr.com لعنصر SDK. راجع Content Security Policy.
وسيلة لتقديم الصفحة عبر HTTP للاختبار، مثل npx serve . داخل المجلد.

الخطوة 1: نشر الخريطة

افتح الخريطة في Studio واختر Publish. تُفتح صفحة Publish & embed.
تحت Project status تكون الحالة Draft. اختر Go Live.

النتيجة المتوقعة: تتحول الحالة إلى Live والزر إلى Re-publish، ويظهر Unpublish بجانبه، وقسم Embed code مع معاينة مباشرة أسفله.

تعرض الخريطة المنشورة ما هو محفوظ حاليًا في Studio، وليس نسخة من لحظة الضغط على Go Live. يحفظ Studio التعديلات أثناء العمل، لذلك تظهر كل التعديلات اللاحقة، بما فيها مجموعات البيانات المضافة، للزوار عند تحميل التضمين في المرة التالية. لا يلزم الضغط على Re-publish لذلك. يسجّل هذا الزر إصدار نشر جديدًا مع الاحتفاظ بالمعرّف والرابط ورمز التضمين نفسها؛ ويرى الزوار الخريطة نفسها قبل إعادة النشر وبعدها.

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

يشمل النشر بياناتك المرفوعة. تظهر مجموعات البيانات وتراكبات الصور التي أضفتها في لوحة Data كطبقات بالتنسيق الذي حددته للزوار. اقرأ البيانات المرفوعة على خريطة منشورة قبل نشر خريطة تحتوي على معلومات لا ينبغي إتاحتها للجميع.

الخطوة 2: نسخ رمز التضمين

يوفر قسم Embed code تنسيقين.

التنسيق في Studio	ما تحصل عليه	متى تستخدمه
iFrame	عنصر `<iframe>` عادي يشير إلى الخريطة المنشورة.	عندما لا تستطيع الصفحة تشغيل نصوصك البرمجية، مثل منشئ المواقع أو CMS أو wiki، أو عندما تريد عرض الخريطة فقط.
Developer	أداة تحميل SDK وعنصر `<kaleidr-map product="viewer">`.	عندما تتحكم في الصفحة وتريد ضبط الكاميرا أو تحريكها بالكود، أو إضافة الدردشة فوق الخريطة، أو إدارة دورة حياة الخريطة في تطبيق أحادي الصفحة.

اختر التنسيق واضغط Copy.

تنسيق iFrame:

<iframe
  src="https://map-embed.kaleidr.com/embed/YOUR_MAP_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>

تنسيق Developer:

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js" async></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
  style="display:block;width:100%;height:480px;"></kaleidr-map>

يشير YOUR_MAP_ID إلى المعرّف الذي يضعه Studio في المقتطف. يتألف من الأحرف والأرقام والرموز ., _, ~, - بطول لا يتجاوز 100 حرف. يعمل المعرّف نفسه مع كلا التنسيقين.

يحمل التنسيقان كلاهما Kaleidr AI الخاص بالخريطة: لوحة Ask Kaleidr عندما يكون Control Tower مفعّلًا، ومحادثة AI في نوافذها المنبثقة عندما يكون Popup Window مفعّلًا. راجع Kaleidr AI على خريطة منشورة.

الخطوة 3: إضافتها إلى الصفحة وضبط أبعادها

ألصق المقتطف في الموضع الذي تريد ظهور الخريطة فيه.

النتيجة المتوقعة: يظهر مؤشر «Loading map…»، ثم الخريطة بالعرض الذي حفظته في Studio.

قواعد الأبعاد:

iframe عادي: عيّن width وheight كما تفعل مع أي iframe.
عنصر SDK: حدد ارتفاعًا. يكون <kaleidr-map> من نوع display:block افتراضيًا، لذا يعمل الارتفاع. وتستخدم الأمثلة style="display:block; height:480px" أيضًا؛ وهو آمن ويحل مشكلة Safari قبل الإصدار 16.4 حيث يبقى العنصر مضمنًا ويتجاهل height. يمكنك كذلك ضبطهما في ملف CSS.
```
kaleidr-map { display: block; height: 480px; }
```
تملأ الخريطة عرض العنصر. إن لم يكن له ارتفاع عند التركيب، يعود إلى ارتفاع ثابت قدره 500 بكسل ويبقى كذلك حتى لو حددت ارتفاعًا لاحقًا. لا يكون للعنصر داخل تبويب مخفي أو لوحة مطوية ارتفاع؛ لذلك ركّبه عند ظهوره أو امنحه ارتفاعًا صريحًا.
للارتفاع المتجاوب استخدم CSS ينتج ارتفاعًا محددًا، مثل height:60vh أو aspect-ratio:16/9 أو خلية flex/grid.

الخطوة 4: ضبط الكاميرا الافتتاحية (اختياري)

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

على العنصر:

<kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
             center="-0.1276,51.5072" zoom="12" pitch="45" bearing="-20"
             style="display:block; height:480px"></kaleidr-map>

في iframe العادي أضف إعدادات الكاميرا إلى عنوان URL بصيغة camera=longitude,latitude,zoom:

<iframe
  src="https://map-embed.kaleidr.com/embed/YOUR_MAP_ID?camera=-0.1276,51.5072,12&pitch=45&bearing=-20"
  width="100%" height="480" style="border:0;" loading="lazy"
  referrerpolicy="no-referrer-when-downgrade" allow="geolocation; microphone; fullscreen; clipboard-write"
  title="Kaleidr map"></iframe>

تتقدم الكاميرا التي تمررها على العرض الذي حفظه المؤلف، بما في ذلك إعدادات أحجام الشاشات والتأطير التلقائي. يستبدل كل حقل تمرره قيمته فقط، وتبقى الحقول المحذوفة بقيم المؤلف. بعد ضبط الكاميرا من صفحتك تتوقف إعادة التأطير التلقائية عند تغيير حجم الإطار. تذكر: يُتجاهل zoom ما لم تمرر center أيضًا. ويعمل pitch وbearing منفردين.

النتيجة المتوقعة: تُفتح الخريطة بالكاميرا التي حددتها، مع بقاء العلامات والطبقات والبيانات المرفوعة كما كانت.

لتحريك الكاميرا بعد التحميل، ركّب الخريطة عبر JavaScript واحتفظ بالمقبض:

<div id="map" style="height:480px"></div>
<button id="paris">Paris</button>

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<script>
  const handle = Kaleidr.mount('#map', {
    product: 'viewer',
    shareId: 'YOUR_MAP_ID',
  });

  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: 800 });
  });
</script>

نقطتان مهمتان حول setCamera:

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

الخطوة 5: تقييد المواقع التي تعرض الخريطة (اختياري)

افتراضيًا، يمكن لأي موقع يملك معرّف الخريطة المنشورة عرضها. للتقييد:

افتح الخريطة في Studio واختر Share. يؤدي فتح مربع المشاركة إلى نشر الخريطة إن لم تكن منشورة وإنشاء رابط مشاركة جديد في كل مرة.
افتح تبويب Embed.
غيّر اختيار الوصول من Any domain إلى Specific domains.
أدخل نطاقًا واحدًا في كل سطر، مثل:
```
example.com
blog.example.org
```
انقر خارج الحقل. يحفظ Studio القائمة ويعرض Saved.

النتيجة المتوقعة: تستمر الخريطة في الظهور على المواقع المدرجة. في المواقع الأخرى يعرض الإطار «This map isn't allowed to render on this site. Please contact the map owner.»

كيفية مطابقة القائمة:

أدخل أسماء المضيفين فقط. تُتجاهل بادئة https://. لا تضع مسارًا أو منفذًا.
يشمل النطاق نطاقاته الفرعية. يتيح example.com كلا من example.com وwww.example.com وshop.eu.example.com.
للاختبار محليًا أثناء سريان التقييد أضف localhost.

يعتمد التحقق على المُحيل

تحدد الخريطة ما إذا كان موقعك مسموحًا من المُحيل الذي يرسله المتصفح عند تحميل iframe. إذا لم يُرسل مُحيل فلن تظهر الخريطة المقيّدة بالنطاق. يحدث ذلك عندما:

ترسل الصفحة Referrer-Policy: no-referrer أو same-origin في ترويسة الاستجابة أو وسم <meta name="referrer">؛
يحمل iframe الخاصية referrerpolicy="no-referrer"؛
تُفتح الصفحة من القرص بعنوان file://؛
يفتح شخص عنوان iframe مباشرة في تبويب المتصفح.

ترسل سياسة المتصفح الافتراضية strict-origin-when-cross-origin أصل الصفحة وتعمل بصورة صحيحة. إذا كان موقعك أشد تقييدًا، احتفظ بـ referrerpolicy="no-referrer-when-downgrade" في iframe العادي، أو خفف سياسة صفحة التضمين.

إذا عُرضت الخريطة داخل إطار آخر، يكون المُحيل هو عنوان ذلك الإطار الخارجي، ويجب أن يظهر نطاقه في القائمة.

تتحكم النطاقات المسموح بها في مكان ظهور الخريطة، لكنها لا تجعل بيانات الخريطة المنشورة سرية، بما فيها مجموعات البيانات: راجع البيانات المرفوعة على خريطة منشورة. لا تنشر بيانات يجب أن تبقى خاصة.

الخطوة 6: معرفة نجاح التحميل أو فشله (اختياري)

لا يوفر SDK وعدًا ready ولا يصدر العنصر أحداثًا. يرسل iframe رسالة إلى صفحتك في حالتين:

الرسالة	متى	الحقول
`kaleidr-embed:ready`	عند رسم الخريطة لأول مرة.	`type` و`id` (معرّف الخريطة) و`source` (`"publish"` أو `"share"`)
`kaleidr-embed:error`	عند تعذر تحميل الخريطة أو رسم جزء منها.	`type` و`id` و`code` و`message`

استمع على window وتحقق من أصل الرسالة ومن الإطار الذي أرسلها:

const el = document.getElementById('locations'); // the <kaleidr-map> element

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://map-embed.kaleidr.com') return;
  const frame = el.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') {
    console.log('map loaded', msg.id);
  } else if (msg.type === 'kaleidr-embed:error') {
    console.warn('map problem', msg.code, msg.message);
  }
});

في iframe العادي قارن event.source بقيمة contentWindow الخاصة به.

يمكن أن يحمل الحقل code في رسالة الخطأ إحدى القيم:

`code`	المعنى	ما يراه الزائر داخل الإطار
`no_id`	عنوان iframe لا يحتوي على معرّف خريطة.	“Couldn't find a map id in the URL.”
`not_found`	الخريطة لم تُنشر أو أُلغي نشرها أو المعرّف خاطئ.	“This map isn't available — it may have been unpublished, paused, or the link is incorrect.”
`domain_not_allowed`	النطاق غير مسموح أو لم يُرسل مُحيل.	“This map isn't allowed to render on this site. Please contact the map owner.”
`map_loads_exhausted`	استُنفدت حصة تحميل الخرائط للمؤسسة.	“This map has reached its map load limit. It will be available again when the owner's allowance resets.”
`fetch_failed`	تعذر جلب الخريطة، مثلًا بسبب الشبكة.	“Could not load the map. Please try again in a moment.”
`maplibre_error`	بدأت الخريطة لكن تعذر رسم جزء منها؛ يحمل `message` التفاصيل.	خريطة قد تنقصها بعض العناصر.

ملاحظات بشأن التوقيت:

لا تظهر الخريطة ولا تصل رسالة ready لأي رمز عدا maplibre_error.
يمكن أن يظهر maplibre_error قبل ready أو بعدها مرات متعددة. تعامل معه كتحذير لا كدليل على عدم صلاحية الخريطة.
يحمّل SDK الإطار بشكل كسول. الخريطة البعيدة أسفل الصفحة لا تبدأ التحميل حتى يقترب الزائر منها بالتمرير؛ فلا تتوقع رسالة قبل ذلك، ولا تعتبر بضع ثوانٍ من الصمت فشلًا.
يرسل الإطار أيضًا رسائل kaleidr-embed: داخلية. تعامل مع النوعين أعلاه فقط بوصفهما واجهة عامة وتجاهل البقية.

صفحة كاملة

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

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Our locations</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 2rem; }
    #map { height: 480px; }
  </style>
</head>
<body>
  <h1>Our locations</h1>
  <p id="status">Loading the map…</p>

  <div id="map"></div>
  <p>
    <button id="london">London</button>
    <button id="paris">Paris</button>
  </p>

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

    const handle = Kaleidr.mount(target, {
      product: 'viewer',
      shareId: 'YOUR_MAP_ID',
    });

    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') {
        status.textContent = 'Map loaded.';
      } else if (msg.type === 'kaleidr-embed:error' && msg.code !== 'maplibre_error') {
        status.textContent = 'The map could not load (' + msg.code + ').';
      }
    });

    document.getElementById('london').addEventListener('click', () => {
      handle.setCamera({ center: [-0.1276, 51.5072], zoom: 12, duration: 800 });
    });
    document.getElementById('paris').addEventListener('click', () => {
      handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 800 });
    });
  </script>
</body>
</html>

كيفية عمله

الموضوع	السلوك
العرض الابتدائي	عرض المؤلف المحفوظ، إلا إذا مررت كاميرا فتتقدم عليه حقلًا بحقل.
التمرير	التمرير والمؤشر فوق الخريطة يقرّب الخريطة، كما في Studio. وحين يكون المؤشر خارج الخريطة يحرك التمرير صفحتك. على الشاشات اللمسية، يحرك السحب الخريطة ويقرّبها ضم الأصابع.
التحديثات	يظهر ما هو محفوظ حاليًا في Studio، وتظهر التعديلات عند التحميل التالي دون إعادة نشر.
البيانات المرفوعة	تظهر مجموعات البيانات وتراكبات الصور في طبقاتها. راجع البيانات المرفوعة على خريطة منشورة.
إلغاء النشر	تعرض التضمينات رسالة عدم الإتاحة؛ وتعود عناوينها نفسها للعمل بعد إعادة النشر. راجع إلغاء نشر الخريطة.
النوافذ المنبثقة	تُفتح عند النقر فقط إذا فعّل المؤلف النوافذ المنبثقة.
الارتفاع	يأخذ ارتفاع العنصر وقت التركيب، وإلا يثبت عند 500 بكسل.
التحميل	يُحمّل iframe من SDK عند اقترابه من نطاق العرض.
المفتاح	غير مطلوب. لا تمرر مفتاحًا عامًا إلى viewer، لأنه ينشئ طلب جلسة غير ضروري، وإذا رُفض فلن تظهر الخريطة.

البيانات المرفوعة على خريطة منشورة

تُعد مجموعات البيانات التي ترفعها في لوحة Data في Studio جزءًا من الخريطة المنشورة. يرى الزائر كل مجموعة وتراكب صورة بالطبقة التي نسّقتها، سواء في iframe عادي أو عنصر SDK أو رابط مشاركة. لا يلزم تفعيل إعداد إضافي أو تقديم مفتاح في صفحة التضمين.

لأن الخريطة المنشورة تعرض أحدث حالة محفوظة، تصبح أي مجموعة بيانات تضيفها لاحقًا عامة بمجرد حفظ الخريطة، دون إعادة النشر.

ما الذي يُقدّم، ولمن:

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

كيفية إيقاف تقديم مجموعة بيانات:

الإجراء في Studio	التأثير على الخريطة المنشورة	التأثير على رابط المشاركة
حذف المجموعة من لوحة Data	تُحذف ولا تُقدّم مجددًا، وتبقى بقية الخريطة كما هي.	تظهر الخريطة دون طبقة تلك المجموعة.
إلغاء نشر الخريطة	يتوقف تقديم الخريطة وكل بياناتها.	لا يتأثر الرابط ويستمر بعرض البيانات التي لديه.

لحذف مجموعة بيانات، اختر رمز سلة المهملات في صفها داخل لوحة البيانات وأكّد الحذف. توضح صفحة حذف مجموعة بيانات أو استبدالها الخطوات وما يحدث عند استخدام «تراجع» بعد ذلك. حذف الطبقات التي تعرض مجموعة البيانات فقط ليس حذفًا للمجموعة نفسها؛ إذ تبقى محفوظة ومرتبطة بالخريطة، ولذلك يستمر تقديمها.

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

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

يفتح مربع Share في Studio عملية النشر وينشئ رابطًا جديدًا في كل مرة، لذلك قد تكون للخريطة عدة روابط، يمثل كل منها لقطة التصميم لحظة إنشائه.

لا يوجد في Studio زر لحذف رابط مشاركة أو إيقافه مؤقتًا. يستمر حتى تحذف البيانات التي يعرضها أو تطلب من Kaleidr إزالة الرابط. لمشاركة أحدث حالة افتح Share مجددًا واستخدم الرابط الجديد؛ وتبقى الروابط القديمة على شكلها السابق.

إلغاء نشر خريطة

في Publish & embed يظهر Unpublish بجانب Re-publish للخريطة المباشرة. يؤكد Studio أن إلغاء النشر يوقف التضمينات مع استمرار روابط المشاركة المرسلة سابقًا. اختر Unpublish للموافقة أو Cancel للإبقاء عليها.

تتوقف جميع تضمينات الخريطة، فيظهر تنبيه عدم الإتاحة وتُرسل not_found.
تحتفظ الخريطة بمعرّفها. يعيد Go Live تفعيل عناوين التضمين نفسها دون تغيير الرموز الموجودة بصفحاتك.
تواصل روابط المشاركة السابقة عملها بالبيانات التي كانت لديها. ويتوقف Kaleidr AI فيها حتى تنشر الخريطة مجددًا.

لا يحدث الإيقاف فورًا في كل مكان:

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

كيفية التحميل:

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

حدود رفع البيانات في حدود مجموعات البيانات.

كيفية احتساب المشاهدات

كل تحميل للتضمين من زائر يُحتسب تحميل خريطة واحدًا على المؤسسة المالكة للخريطة، لا الموقع الذي يضمّنها. لا يُحتسب تحميل الزائر نفسه للخريطة نفسها مرة أخرى خلال 24 ساعة. ولا تُحتسب مشاهدات صفحات Kaleidr الخاصة مثل معاينة Studio.

عند استنفاد حصة تحميل الخرائط للفترة، تعرض التضمينات رسالة الحد وترسل map_loads_exhausted حتى إعادة ضبط الحصة. راجع الحصص وحدود المعدل.

التحقق من النجاح

في الصفحة: تظهر العلامات والمسارات ومجموعات البيانات وتراكبات الصور المضافة في لوحة Data بالطبقات التي نسّقتها، وتعمل أزرار التكبير، ويظهر سطر الإسناد أسفل الخريطة.
في وحدة التحكم: لا توجد رسالة تحتوي على [kaleidr.
في تبويب Network: طلب مستند إلى https://map-embed.kaleidr.com/embed/YOUR_MAP_ID بحالة 200، ومع SDK تظهر kaleidr.js وviewer.js من https://cdn.kaleidr.com.
في المستمع: تصل رسالة kaleidr-embed:ready واحدة.

إذا لم يعمل

العَرَض	السبب	الحل
ارتفاع الخريطة 500 بكسل مهما غيّرت `height`	لم يكن للعنصر ارتفاع عند التركيب، أو CSS يعين `display:inline`، أو Safari قبل 16.4 بلا `display:block`.	حدد `display:block` وارتفاعًا وركّب العنصر وهو ظاهر.
رسالة `[kaleidr] <kaleidr-map> requires product="chat\|viewer\|editor\|tile"`	سمة `product` مفقودة أو خاطئة.	استخدم `product="viewer"`.
معرّف الخريطة غير صالح	`share-id` مفقود أو يحتوي رمزًا غير مسموح.	انسخ المعرّف من Studio مجددًا. `[kaleidr:viewer] Kaleidr map: invalid id "" — must match ^[A-Za-z0-9._~-]{1,100}$.`
`[kaleidr:viewer] mount target not found: #map`	التنفيذ قبل وجود العنصر أو المحدد خاطئ.	نفّذ بعد العنصر أو صحح المحدد. `Kaleidr.mount`
`Kaleidr is not defined`	نُفّذ الكود قبل انتهاء تحميل `kaleidr.js` غير المتزامن.	أزل `async` أو انتظر حدث `load`. `async`
الخريطة غير متاحة	لم تُنشر أو أُلغي نشرها أو المعرّف خاطئ.	انشر باستخدام Go Live وتحقق من المعرّف.
النطاق غير مسموح	ليس في القائمة أو لا يوجد مُحيل.	صحح القائمة أو سياسة المُحيل.
بلوغ حد تحميل الخرائط	استُهلكت حصة المؤسسة.	انتظر إعادة الضبط أو زد الحصة. الحصص وحدود المعدل.
“Could not load the map”	تعذر جلب الخريطة.	أعد التحميل وافحص الشبكة وعنوان iframe.
خطأ CSP في `frame-src`	سياسة تمنع الإطار.	اسمح بـ `https://map-embed.kaleidr.com`. `frame-src`
خطأ CSP في `script-src`	سياسة تمنع أداة التحميل.	اسمح بـ `https://cdn.kaleidr.com` أو استخدم iframe عاديًا. `script-src`
`setCamera` لا تعمل	استُدعيت على العنصر أو الخريطة لم تُحمّل.	استخدم مقبض `Kaleidr.mount`، وافحص `kaleidr-embed:error` ووحدة التحكم. إذا لم تُبلغ الخريطة عن جاهزيتها خلال مهلة محدودة، تكون عادةً 10 ثوانٍ بعد تحميل إطار iframe، تُرسل الاستدعاءات رغم ذلك، وتعرض وحدة التحكم `[kaleidr] the map frame has not reported ready`؛ ولا توجد خريطة لتحريكها أو تعديلها في إطار يعرض خطأ.
`el.setCamera is not a function`	استُدعيت `setCamera` على العنصر.	استخدم المقبض أو غيّر السمات. Kaleidr.mount
يتوقف تمرير الصفحة عند الخريطة	هذا متوقع؛ فالتمرير والمؤشر فوق الخريطة يقرّب الخريطة.	مرّر والمؤشر بجانب الخريطة. واجعل ارتفاع الخريطة أقل من ارتفاع الشاشة، ليتمكن الزوار من التمرير متجاوزين إياها.
لا تظهر التعديلات	حُمّلت الخريطة قبل حفظ التعديل.	أعد تحميل الصفحة دون إعادة النشر.
ظهرت تعديلات غير مقصودة للعامة	المنشور يعرض أحدث حالة محفوظة.	تراجع عن التعديل أو ألغ النشر أثناء العمل أو اعمل على نسخة. المرجع
طبقة بيانات مفقودة	حُذفت المجموعة أو تعذر تحميلها.	راجع لوحة Data ثم أعد التحميل.
تأخر ظهور مجموعة كبيرة	ينزل كل زائر البيانات كاملة.	قلّل الصفوف والأعمدة؛ راجع البيانات المرفوعة على خريطة منشورة.

الحدود

التضمين للقراءة فقط؛ لا يمكن للصفحة إضافة علامات أو طبقات إليه أو قراءة بياناته أو تلقي نقراته.
الإشارات الوحيدة هي kaleidr-embed:ready وkaleidr-embed:error.
لا يمكنك تغيير تنسيق الخريطة أو خريطتها الأساسية من التضمين. غيّرها في Studio لتظهر عند التحميل التالي.
تغيير share-id بعد التركيب لا يؤثر. أزل العنصر وأضفه مجددًا، أو نفذ handle.destroy() ثم أعد التركيب.
تعتمد قيود النطاقات على مُحيل المتصفح ولا توفر سرية حقيقية.

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

مرجع Viewer: الخيارات والسمات والرسائل.
Kaleidr AI على خريطة منشورة: أسئلة الزوار حول الخريطة.
مجموعات البيانات على الخريطة: الملفات والحدود وأدوار الأعمدة.
الدمج مع أطر العمل: التركيب والإزالة في React وNext.js وVue.
Content Security Policy: إذا كان الموقع يطبق سياسة أمان.

قبل البدء​

الخطوة 1: نشر الخريطة​

الخطوة 2: نسخ رمز التضمين​

الخطوة 3: إضافتها إلى الصفحة وضبط أبعادها​

الخطوة 4: ضبط الكاميرا الافتتاحية (اختياري)​

الخطوة 5: تقييد المواقع التي تعرض الخريطة (اختياري)​

الخطوة 6: معرفة نجاح التحميل أو فشله (اختياري)​

صفحة كاملة​

كيفية عمله​

البيانات المرفوعة على خريطة منشورة​

روابط المشاركة​

إلغاء نشر خريطة​

كيفية احتساب المشاهدات​

التحقق من النجاح​

إذا لم يعمل​

الحدود​

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