تضمين خريطة تفاعلية في موقع ويب

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

تتناول الأقسام التالية اختيار الطريقة وإعداد Kaleidr Viewer والحاويات المتجاوبة والأمان وإمكانية الوصول وتحسين محركات البحث والأخطاء الشائعة. لربط المحادثة بعارض حي، راجع كيفية إضافة دردشة الذكاء الاصطناعي إلى خريطة. وللتعرّف إلى فئة SDK نفسها، راجع ما حزمة تطوير خرائط الذكاء الاصطناعي؟.

أساسيات تضمين الخريطة

• اختر الطريقة أولاً: اختر iframe أو مكوّن الويب أو SDK أو مكتبة خرائط أصلية وفق مقدار التحكم الذي تحتاج إليه الصفحة المضيفة، لا وفق طول نموذج الشفرة.
• احجز الارتفاع: حدّد ارتفاعاً صريحاً لحاوية الخريطة قبل التحميل لتجنّب انهيارها وتغيّر التخطيط.
• Viewer المنشور: يستخدم Kaleidr Viewer السمة product="viewer" ومعرّف مشاركة؛ ويخضع الوصول لرابط المشاركة والنطاقات التي يسمح بها الناشر.
• نص خارج اللوحة: تجعل العناوين والملخصات وقوائم المواقع الصفحة مفيدة لمستخدمي لوحة المفاتيح والتقنيات المساعدة ومحركات البحث.
• قِس إنجاز المهام: تتبّع التحميلات والاختيارات وطلبات الاتجاهات والتحويلات، لا مرات ظهور الخريطة وحدها.

كيف تضمّن تجربة خريطة تفاعلية؟

ينشئ هذا الدليل قسماً متجاوباً للخريطة يصلح لموقع تسويقي أو دليل وجهة أو صفحة عقار أو محدد متاجر أو مقال أو منتج برمجي. تشمل النتيجة خريطة تفاعلية منشورة، وحاوية تعمل على سطح المكتب والهاتف، وعنواناً وملخصاً نصياً واضحين خارج الخريطة، وتحكماً اختيارياً في الكاميرا من الصفحة المضيفة، وقيوداً على النطاق أو بيانات الاعتماد، وحالات للتحميل والفشل، وبدائل سهلة الوصول للمعلومات التي تظهر على الخريطة، وأحداثاً لقياس التفاعل. تستخدم الأمثلة Kaleidr Viewer لأنه يتيح تضمين خريطة منشورة عبر أداة تحميل واحدة وعنصر مخصص واحد؛ وينطبق إطار القرار نفسه عند الاختيار بين iframe من مزوّد أو مكوّن ويب للخريطة أو تطبيق مخصص باستخدام Mapbox أو Google Maps أو MapLibre أو Leaflet.

كيف تختار طريقة التضمين المناسبة؟

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

استخدم iframe المباشر عندما تكون الخريطة مكتفية ذاتيًا ، وتحتاج صفحة المضيف فقط إلى عرضها ، والحد الأدنى من العمل الهندسي هو الأولوية.HTML iframe يخلق العنصر سياق تصفح مضمن منفصل - عزل مفيد ، ولكن بيئة مستند أخرى بمواردها الخاصة واعتبارات إمكانية الوصول.استخدم مكون ويب عندما يريد الفريق عنصر HTML توضيحيًا ، تكون سمات مثل معرف الخريطة أو الكاميرا كافية ، ويحافظ المزود على التنفيذ الداخلي ؛ عناصر مخصصة يمكن إخفاء التحميل والرسائل وراء عقد عام مستقر.استخدم JavaScript SDK عندما يجب على المضيف الاحتفاظ بمقبض أو تحديث الكاميرا أو السمة أو تدمير الخريطة على تغييرات المسار أو إرفاقها بمعرض مباشر أو تنسيق مصادقة المتصفح أو الأحداث أو سير عمل الذكاء الاصطناعي.

كيف يعمل تضمين Kaleidr Viewer؟

يضمّن Kaleidr Viewer خريطة Kaleidr منشورة باستخدام معرّف المشاركة. يمتلك Viewer الخريطة ويعمل عبر إطار iframe داخل مكوّن <kaleidr-map>؛ ويمكن للصفحة المضيفة التحكم في السلوك المدعوم من خلال مقبض SDK وقناة المراسلة الموثقة. للعقد الحالي أربع خصائص مهمة: يختار product="viewer" عارض الخريطة المنشورة؛ ويحدد share-id الخريطة؛ ويخضع الوصول لرابط المشاركة من دون الحاجة إلى مفتاح API؛ وتظل النطاقات التي يسمح بها الناشر سارية. يختلف Viewer عن Kaleidr Chat: يمتلك Viewer خريطته، بينما يمكن لـ Chat الارتباط بنسخة حية من Mapbox أو Google Maps أو MapLibre أو Leaflet تعمل في التطبيق المضيف.

حمّل أداة التحميل ذات الإصدار المحدد مرة واحدة من https://cdn.kaleidr.com/embed/v1/kaleidr.js قبل تركيب أي منتج. تعرّف الأداة <kaleidr-map> وتثبت window.Kaleidr، ثم تحمّل حزمة المنتج المحدد عند الحاجة. يضع الحد الأدنى من تضمين خريطة منشورة العنصر المخصص داخل حاوية ذات ارتفاع صريح:

<kaleidr-map
  product="viewer"
  share-id="abcd1234"
  style="display:block; height:520px;">
</kaleidr-map>

يتبع المثال دليل البدء السريع الحالي ومرجع <kaleidr-map> ووثائق تضمين Viewer. استبدل abcd1234 بمعرّف مشاركة الخريطة المنشورة. يجب نشر الخريطة والسماح بعرضها على النطاق المضيف. استخدم المكوّن الموثق بدلاً من إنشاء عنوان URL داخلي لـ Viewer لا يشكل جزءاً من العقد العام.

كيف تنشئ صفحة خريطة متجاوبة وسهلة الوصول؟

الخريطة المضمنة تحتاج إلى ارتفاع واضح.بدون واحد ، قد تنهار الحاوية ، أو تنتج تخطيطًا غير مستقر ، أو تعود إلى افتراضي خاص بمزود الخدمة.لف العنصر في قذيفة تحتفظ بمساحة قبل تحميل الخريطة - عرض كامل ، والحد الأدنى للارتفاع ، وغالبًا ما تكون نسبة العرض إلى الارتفاع 16:9 على سطح المكتب مع الحد الأدنى الثابت الأطول على الهواتف الضيقة.تقلل مساحة الحجز من حركة التخطيط غير المتوقعة ؛ التضمينات بدون أبعاد محددة هي سبب شائع لنوبة التخطيط التراكمية (web.dev CLS التوجيه)(اختبر الخريطة الحقيقية بدلاً من الاعتماد فقط على نسبة العرض إلى الارتفاع: غالبًا ما تعمل الخريطة الضحلة عريضة الشاشة على سطح المكتب ولكن يصبح من الصعب استخدامها على الهاتف.

عنصر المشاهد يلاحظ center, zoom, pitch, bearing, و theme حيثما يكون مدعوم؛ center يستخدم خط الطول، ترتيب خط العرض.اختر الكاميرا الافتتاحية بحيث يكون الغرض من الخريطة واضحًا - المنطقة المميزة والتطوير والعبور ، أو وجهة نظر وطنية أوسع مع بحث أو مرشح واضح.عندما تحتاج صفحة المضيف إلى مقبض ، قم بالتركيب باستخدام واجهة برمجة التطبيقات الحتمية بعد وجود اللودر:

const viewer = Kaleidr.mount("#featured-map", {
  product: "viewer",
  shareId: "abcd1234",
  center: [-0.12, 51.5],
  zoom: 11
});

// In an SPA, call destroy before removing the page or component.
window.addEventListener("pagehide", () => {
  viewer.destroy();
});

يعيد Kaleidr.mount() مقبضاً بصورة متزامنة أثناء تحميل حزمة المنتج، وتدخل الاستدعاءات التي تتم قبل جاهزية الحزمة في قائمة انتظار. يوفّر المقبض دائماً destroy() وقد يوفّر setCamera() أو setTheme() عندما يدعم المنتج المحدد ذلك. ينبغي لتطبيقات الصفحة الواحدة ربط عملية الإزالة بدورة حياة المسار حتى لا يؤدي التنقل المتكرر إلى إنشاء عمليات تضمين مكررة.

لا يمكن أن تكون الخريطة التفاعلية هي الطريقة الوحيدة للوصول إلى المعلومات الأساسية. WCAG 2.2 يوفر إطارًا لمحتوى الويب الذي يمكن الوصول إليه: امنح الخريطة عنوانًا ذا مغزى ومنطقة مصنفة ، ونشر قائمة مواقع مكافئة تحتوي على أسماء وعناوين وفئات وإجراءات ، وتأكيد وصول مستخدمي لوحة المفاتيح إلى الخريطة وتركها دون فخاخ ، وتجنب علامات الألوان فقط.بالنسبة إلى iframe الخام ، قم بتضمين سمة title الوصفية بدلاً من تسمية عامة مثل "الخريطة".

كيف تتعامل الفرق مع النطاقات والأداء وتحسين محركات البحث؟

لا يمثل معرّف المشاركة نموذج صلاحية عامة غير مقيّدة. يخضع Kaleidr Viewer لرابط المشاركة، وتظل النطاقات التي يحددها الناشر سارية؛ فلن تُعرض خريطة محصورة بالمواقع المعتمدة في موقع آخر لمجرد معرفة معرّف المشاركة. خطط لقائمة النطاقات لتشمل الإنتاج ومتغيرات www عند استخدامها وبيئة الاختبار والتطوير المحلي عند دعمه. تدرج أسعار Kaleidr الحالية دعم التضمين في خطتي Pro وEnterprise؛ ولا يحتاج Viewer نفسه إلى مفتاح API، لكن على الفرق التحقق من الخطة وحد تحميل الخريطة وضوابط النشر قبل الإنتاج (الأسعار).

تعامل مع الخريطة كسطح تطبيق ذي مغزى.حجز الأبعاد قبل التحميل.تحميل كسول أو تأجيل أسفل الخرائط المطوية عندما لا تكون ضرورية لميناء المشاهدة الأولي - الأصلي loading="lazy" ينطبق على iframes الخام، في حين أن المكون المخصص قد يحتاج إلى مراقب تقاطع من جانب المضيف أو واجهة النقر إلى التحميل.لا تؤجل الخريطة التي هي التجربة الأساسية للصفحة فوق الطي.تجنب تحميل أكوام الخرائط المكررة في صفحة واحدة ، وقياس وقت اللودر والوقت حتى التفاعلية ونقل البلاط والذاكرة المتنقلة على الأجهزة الحقيقية.

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

الخلاصة

استخدم iframe مباشراً عندما تكفي خريطة مستقلة من المزوّد. واستخدم مكوّن ويب عندما يريد الفريق تضميناً تعريفياً واضحاً بعقد عام يديره المزوّد. واستخدم JavaScript SDK عندما يحتاج التطبيق المضيف إلى التحكم في الكاميرا أو إدارة دورة الحياة أو تفاعل الذكاء الاصطناعي أو المصادقة أو تكامل أعمق مع المنتج. صُمم Kaleidr Viewer للخرائط المنشورة التي ينبغي عرضها باتساق عبر مواقع الويب من دون مفتاح API في المتصفح: تحمّل الصفحة المضيفة kaleidr.js، وتقدم معرّف المشاركة، وتحجز حاوية متجاوبة، وتحترم النطاقات المسموح بها. يجب أن يكون التضمين الناجح موثوق التحميل، واضح الغرض، صالحاً للاستخدام على الهاتف وبواسطة لوحة المفاتيح، وأن يعرض المعلومات الأساسية خارج الخريطة ويساعد الزائر على إكمال مهمة قابلة للقياس.

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

انشر خريطة في Kaleidr Studio، وانسخ معرّف المشاركة، ثم أضف Viewer عبر أداة تحميل JavaScript ذات الإصدار المحدد. تشرح وثائق تضمين Viewer عقد المكوّن والمراسلة. راجع Chat وEditor وTiles والمصادقة وPlatform API في وثائق المطورين عندما تصبح الخريطة جزءاً من سير عمل أوسع للمنتج.

الأسئلة الشائعة

كيف أضمّن خريطة تفاعلية في موقع ويب؟

اختر خريطة أو مزود منشور ، وأضف iframe أو مكون الويب أو JavaScript SDK إلى الصفحة ، واحتفظ بحاوية سريعة الاستجابة ، وتكوين الوصول ، ووفر نصًا يمكن الوصول إليه خارج الخريطة.

هل iframe أسهل طريقة لتضمين خريطة؟

عادة.Iframe يناسب عندما تكون الخريطة مكتفية ذاتيًا وتحتاج الصفحة إلى القليل من التحكم.يكون مكون الويب أو SDK أفضل عندما يحتاج المضيف إلى عقد منتج مستقر أو تحديثات كاميرا أو التحكم في دورة الحياة أو الأحداث أو تفاعل الذكاء الاصطناعي.

هل يحتاج Kaleidr Viewer إلى مفتاح API؟

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

كيف أجعل الخريطة المضمّنة متجاوبة؟

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

هل يمكنني التحكم في خريطة Kaleidr مضمّنة من JavaScript؟

نعم.يقوم تكامل Viewer الضروري بإرجاع مقبض يمكن أن يدعم تحديثات الكاميرا ويوفر دائمًا destroy() من أجل التمزق

المراجع

• Google. Embed a Map. Google Maps Embed API documentation. Accessed 2 August 2026. https://developers.google.com/maps/documentation/embed/embedding-map
• Google. Understand JavaScript SEO Basics. Google Search Central. Accessed 2 August 2026. https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics
• Kaleidr. kaleidr.js — the Loader. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/sdk/kaleidr-js
• Kaleidr. kaleidr-map — the Element. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/sdk/kaleidr-map-element
• Kaleidr. Pricing & Plans. kaleidr.com. Accessed 2 August 2026. https://kaleidr.com/pricing
• Kaleidr. Quickstart. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/quickstart
• Kaleidr. Viewer — Embed a Published Map. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/sdk/viewer-embed
• MDN Web Docs. iframe: The Inline Frame Element. Accessed 2 August 2026. https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe
• MDN Web Docs. Using Custom Elements. Accessed 2 August 2026. https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements
• World Wide Web Consortium. Web Content Accessibility Guidelines (WCAG) 2.2. Accessed 2 August 2026. https://www.w3.org/TR/WCAG22/
• web.dev. Optimize Cumulative Layout Shift. Accessed 2 August 2026. https://web.dev/articles/optimize-cls

@misc{kaleidr_viewer_embed,
  title  = {Viewer -- Embed a Published Map},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 2 August 2026},
  url    = {https://docs.kaleidr.com/sdk/viewer-embed}
}

@misc{kaleidr_loader,
  title  = {kaleidr.js -- the Loader},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 2 August 2026},
  url    = {https://docs.kaleidr.com/sdk/kaleidr-js}
}

@misc{mdn_iframe,
  title  = {iframe: The Inline Frame Element},
  author = {{MDN Web Docs}},
  note   = {Accessed 2 August 2026},
  url    = {https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe}
}

@misc{w3c_wcag22,
  title  = {Web Content Accessibility Guidelines 2.2},
  author = {{World Wide Web Consortium}},
  note   = {Accessed 2 August 2026},
  url    = {https://www.w3.org/TR/WCAG22/}
}

@misc{google_javascript_seo,
  title  = {Understand JavaScript SEO Basics},
  author = {{Google}},
  note   = {Google Search Central; accessed 2 August 2026},
  url    = {https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics}
}