مرجع Viewer

يعرض product="viewer" خريطة منشورة في Kaleidr Studio. يستبدل SDK محتويات عنصر التثبيت بإطار iframe يحمّل https://map-embed.kaleidr.com/embed/<id>. تُرسَم الخريطة داخل ذلك الإطار.

المفتاح	لا حاجة لأي مفتاح. لا تمرّر واحداً.
الخطة	جميع الخطط، بما فيها Free.
مكان العرض	إطار iframe من https://map-embed.kaleidr.com.
القياس	تحميل خريطة واحد لكل مشاهدة، يُحتسب على مؤسسة مالك الخريطة.
سياسة أمان المحتوى	script-src https://cdn.kaleidr.com وframe-src https://map-embed.kaleidr.com.

للخطوات التفصيلية، راجع تضمين خريطة منشورة.

التثبيت

باستخدام العنصر:

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

من JavaScript:

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

دون استخدام SDK إطلاقاً:

<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>

شريط الدردشة

يحوّل layout="bar" منتج Viewer إلى شريط دردشة: حقل سؤال واحد لصفحتك، بلا خريطة إلى أن يطرح الزائر سؤالًا. يفتح السؤال الخريطة المنشورة، ويجيب عنه Kaleidr AI الخاص بالخريطة هناك.

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="bar"
             chat-title="Ask about the neighborhood"
             prompts="Coffee within a short walk|Parks nearby"></kaleidr-map>

تُفتح الإجابات في أحد موضعين:

الإعداد	ما يفعله السؤال
دون results-url (الافتراضي)	تُفتح الخريطة فوق الصفحة وتملأ النافذة، وتطرح السؤال. يغلقها الزائر بزر الإغلاق. ويُطرح أي سؤال لاحق على الخريطة نفسها، فتستمر المحادثة.
results-url="/map"	ينتقل المتصفح إلى تلك الصفحة مع ?q=<question>. ويطرح Viewer في تلك الصفحة يحمل prompt-param="q" السؤالَ عند فتح الخريطة، إذا جاء الزائر من صفحة من الأصل نفسه.

صفحة نتائج:

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" prompt-param="q"
             style="display:block; height:600px"></kaleidr-map>

• الخريطة هي التي تجيب. يذهب السؤال إلى لوحة Ask Kaleidr الخاصة بالخريطة، لذا يجب أن يكون Control Tower مفعّلًا للخريطة (Studio، Kaleidr AI)، وتسري قواعد Kaleidr AI على خريطة منشورة: يدفع المالك، وتحدد النطاقات المسموحة للخريطة أين تجيب. على خريطة بلا Control Tower، تُفتح الخريطة ولا يُطرح السؤال.
• لا يحمّل الشريط أي خريطة. تُحمَّل الخريطة، وتُحتسب تحميل خريطة، عندما يطرح الزائر سؤالًا.
• يُرسم الشريط داخل shadow root خاص به، فلا يغيّر CSS صفحتك مظهره، ولا تحتاج أنماطه إلى إذن style-src. عرضه بعرض العنصر وارتفاعه بقدر محتواه.
• تتبع تسمياته الخاصة lang، أو لغة متصفح الزائر إن لم تُضبط lang: الإنجليزية والإسبانية والفرنسية والألمانية والبرتغالية واليابانية والكورية والصينية المبسطة والتقليدية والعربية. أما chat-title وplaceholder وprompts التي تحددها فتُعرض كما تكتبها.
• يملأ prompt الحقل مسبقًا، ويطرح handle.send() السؤال من الشيفرة. يطرح handle.send('Parks nearby') ذلك السؤال؛ ويطرح handle.send() ما هو مكتوب في الحقل.

يكتب المنشئ في template.kaleidr.com المقتطفين كليهما لخريطة تختارها.

تخطيطات الأماكن

يعرض layout="locator" وlayout="listings" الخريطة المنشورة بجانب قائمة لمجموعة من مكتبة الأماكن ترسمها الخريطة، مع عوامل تصفية المجموعة وبطاقاتها.

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="locator"
             filters="search|category|open_now"
             style="display:block; height:600px"></kaleidr-map>

<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="listings"
             filters="price|beds|baths"
             style="display:block; height:720px"></kaleidr-map>

التخطيط	القائمة	الدبابيس
locator	أماكن مرتبة حسب المسافة، مع حقل بحث وزر بالقرب مني وعوامل التصفية وعدد. البحث الذي لا يطابق أي مكان في القائمة ينقل الخريطة إلى المكان المبحوث عنه.	طبقة المجموعة بالنمط المحدد في Studio.
listings	بطاقات بالصور، في عمودين ضمن إطار عريض، مرتبة حسب المسافة أو السعر: من الأقل إلى الأعلى أو السعر: من الأعلى إلى الأقل.	تسميات الأسعار.

• تظهر القائمة بجانب الخريطة في إطار عرضه 768 بكسل أو أكثر، وفي إطار أضيق تظهر في لوحة فوق الخريطة يسحبها الزائر إلى الأعلى.
• تبقى القائمة والخريطة متزامنتين. اختيار مكان في القائمة ينقل الخريطة إليه ويفتح بطاقته، واختيار دبوس يمرّر القائمة إليه. تعرض القائمة والدبابيس والعدد الأماكن نفسها دائمًا.
• تعرض القائمة 50 مكانًا في كل مرة، مع عرض المزيد.
• يطلب زر بالقرب مني موقع الزائر. يسمح iframe الذي ينشئه SDK بذلك؛ أما iframe المباشر فيحتاج إلى allow="geolocation".
• على خريطة لا ترسم أي مجموعة، يعرض كلا التخطيطين الخريطة وحدها.

تختار filters أيًّا من عوامل تصفية الزوار الخاصة بالمجموعة يُعرض، مفصولة بـ |. تظهر بترتيب المجموعة أيًّا كان الترتيب الذي تكتبها به، ويُتجاهل أي عامل تصفية لا تتيحه المجموعة. دون filters يعرض التخطيط كل عوامل تصفية المجموعة.

عامل التصفية	يعرض	يطابق
search	حقل نص	الأماكن التي يحتوي اسمها أو عنوانها أو فئتها على النص.
category	أزرار الفئات، حتى أكثر 30 فئة شيوعًا	الأماكن في أي فئة مختارة.
price	حد أدنى وحد أقصى	الأماكن التي يقع سعرها ضمن النطاق. يُخفى المكان الذي لا سعر له بمجرد تضييق النطاق.
beds وbaths	الكل، 1+، 2+، 3+، 4+	الأماكن التي لديها هذا العدد على الأقل.
open_now	مفتاح تبديل	الأماكن المفتوحة الآن، بحسب منطقتها الزمنية. تُخفى الأماكن التي لا ساعات عمل لها ما دام المفتاح مفعّلًا.

تُطبَّق كل عوامل التصفية التي يضبطها الزائر معًا.

تحدد card مقدار ما تعرضه بطاقة المكان. القيمة الافتراضية auto هي البطاقة المصممة في Studio. تعرض compact العنوان الرئيسي والعنوان الفرعي والإجراءات فقط، لإطار صغير.

تعمل إجراءات المكان كما تحددها المجموعة. يرسم إجراء الاتجاهات المسار في الخريطة ويعرض Apple Maps وGoogle Maps؛ ويُفتح رابط في علامة تبويب جديدة؛ ويفتح اتصال رابط هاتف؛ ويفتح إجراء الطلب، مثل Schedule a Tour، نموذج الطلب الخاص بالنشاط التجاري فوق الخريطة.

تخطيط الدليل

يفتح layout="guide" خريطة للمنشآت وبجانبها لوحة Ask Kaleidr الخاصة بها: دليل الحي لفندق، أو خريطة المنطقة حول منشأة. يعرض مجموعة المنشآت (collection، وإلا فأول مجموعة منشآت ترسمها الخريطة) ويتطلب تفعيل Control Tower. على خريطة لا ترسم أي مجموعة منشآت، يعرض التخطيط الخريطة وحدها.

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="guide"
             style="display:block; height:640px"></kaleidr-map>

• الدردشة أولًا. في إطار عرضه 769 بكسل أو أكثر، تكون اللوحة بعرض 400 بكسل على يسار الخريطة. وفي الإطار الأضيق تكون لوحة فوق الخريطة بارتفاع 45%، يسحبها الزائر حتى 85%. وتبقى الملاحظة التي تفيد بأن الإجابات من إنشاء الذكاء الاصطناعي تحت الحقل.
• شرائح الفئات فوق الحقل هي الفئات الثماني الأكثر شيوعًا في المجموعة. تعرض الشريحة دبابيس تلك الفئة وتسأل بلغة الزائر: "أرني الفئة بالقرب من نقطة الارتكاز". ويسأل Plan My Day: "خطط يومي حول نقطة الارتكاز".
• نقطة الارتكاز هي دبوس الانطلاق الخاص بالخريطة، وتُحدد في إعدادات الخريطة في Studio: مكان من مجموعة ترسمها الخريطة، أو نقطة توضع على الخريطة، مثل فندقك. تُرسم كدبوس مستقل باسمها، و"بالقرب" في الدليل تعني بالقرب منها. وتستخدم الخريطة التي لا نقطة ارتكاز لها مركزها.
• خطة اليوم. عند طلب تخطيط يوم، يرسم الدليل مسارًا يبدأ من نقطة الارتكاز ويزور أولًا أماكن من مجموعاتك الخاصة ثم بيانات الأماكن الخاصة بـ Kaleidr، ويعرضه بطاقةً لمحطات مسماة مع أوقاتها، بلغة الزائر.
• بطاقات المنشآت تعرض البطاقة المصممة في Studio، مع Staff Pick على الأماكن التي تميّزها، وتحتها بطاقات الاتصالات الخاصة بك. يظهر المحتوى المتصل على البطاقات فقط، ولا يظهر أبدًا في إجابات الدليل.
• الطلبات. يفتح إجراء Reserve لمنشأة نموذج الطلب الخاص بالنشاط التجاري.

الدليل في تدفق الدردشة

يُعلم viewer الذكاء Kaleidr AI الخاص بالخريطة بالتخطيط الذي يعرضه. يرى عميل POST /chat/control/stream حقلين يخصان الدليل:

الحقل	المكان	الشكل
layout	نص الطلب	"guide" ما دام تخطيط الدليل معروضًا؛ ويُحذف في غير ذلك، وهو دور خريطة عادي. 16 حرفًا على الأكثر، وإلا يُرفض الطلب بالرمز 422 invalid_layout.
itinerary	حدث في التدفق، ويتكرر في الحدث end	{ title, stops: [{ name, time?, note? }] }: عنوان خطة اليوم ومن 1 إلى 12 محطة مسماة، بلغة الزائر مسبقًا. لا تظهر note إلا لأماكنك الخاصة.

يمكن للعميل الذي لا يعرض خطط الأيام تجاهل الحدث.

التخطيط المباشر

يعرض layout="live" مكان مركباتك الآن وأين تتوقف اليوم: مسار شاحنة طعام، أو حافلة مكوكية، أو خدمة متنقلة. يقرأ مجموعتين: مجموعة المركبات، التي تأتي مواقعها من التتبع المباشر، ومجموعة المحطات التي تضم الجدول.

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="live"
             collection="VEHICLES_COLLECTION_ID" stops="STOPS_COLLECTION_ID"
             style="display:block; height:640px"></kaleidr-map>

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

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

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

الشارة	متى
هنا الآن	سجّلت المركبة وصولها إلى المحطة.
مغلق اليوم	وضع السائق علامة على أن المركبة مغلقة اليوم.
مفتوح الآن	تتضمن إحدى فترات المحطة هذه اللحظة.
التالي: 11:00–14:00	للمحطة فترة لاحقة اليوم.
ليس اليوم	ليس للمحطة أي فترة اليوم. وتذكر بطاقتها تاريخ الخدمة التالي خلال 14 يومًا.

ما يراه الزائر يتحرك بسلاسة ولا يخمّن أبدًا. تنزلق المركبة من موقع مُبلَّغ عنه إلى التالي ولا تسبق آخر تقرير لها أبدًا. تتحدّث المواقع كل 10 ثوانٍ ما لم يختر مؤلف الخريطة فاصلًا آخر (من 5 إلى 60 ثانية)، وتتوقف مؤقتًا ما دامت الصفحة مخفية. وتتحدّث حالات اليوم والتقديرات كل دقيقة. ويُبقي التحديث الفاشل الصورة الأخيرة.

لا تُعرض إلا المركبات التي في مناوبة، وبالدقة التي تسمح بها الدقة العامة للأسطول. وتختفي المركبة التي تنتهي مناوبتها عند التحديث التالي.

كل وقت هو تقدير. يُحسب من المسافة على الطرق والسرعات المعتادة، ولا تُحتسب حركة المرور. يُقرَّب إلى الدقيقة الأعلى ويُعرض بصيغة نحو 12 دقيقة أو نحو ساعة و20 دقيقة، ولا يُعرض أبدًا كوقت وصول. إذا لم يوجد مسار على الطرق بين النقطتين، يعرض الصف لا يوجد تقدير. تُبنى مسارات الطرق من بيانات OpenStreetMap، © OpenStreetMap contributors، بموجب ODbL.

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

تتبع تسميات اللوحة لغة viewer، باللغات العشر نفسها التي يدعمها شريط الدردشة.

الخيارات

خيار التثبيت	السمة	النوع	الافتراضي	مطلوب	الوصف
product	product	'viewer'	لا شيء	نعم	يحدد Viewer.
shareId	share-id	سلسلة نصية	لا شيء	نعم	معرّف الخريطة المنشورة من رمز تضمين Studio. يجب أن يطابق ^[A-Za-z0-9._~-]{1,100}$.
mapId	map-id	سلسلة نصية	لا شيء	لا	اسم بديل عن shareId ويُستخدم فقط عند غياب shareId.
center	center	[longitude, latitude]؛ وصيغة السمة "longitude,latitude"	العرض المحفوظ	لا	المركز الأولي.
zoom	zoom	رقم	العرض المحفوظ	لا	مستوى التكبير الأولي، ويُتجاهل عند التثبيت إذا لم يُرسل center.
pitch	pitch	رقم، بالدرجات	العرض المحفوظ	لا	الميل الأولي.
bearing	bearing	رقم، بالدرجات	العرض المحفوظ	لا	الدوران الأولي.
viewerBase	viewer-base	URL	https://map-embed.kaleidr.com	لا	أصل تحميل iframe؛ لا يُستخدم إلا الأصل. لا يلزم في الإنتاج.
base	base	URL	https://cdn.kaleidr.com	لا	الأصل الذي يحمّل SDK منه viewer.js. لا يُستخدم إلا الأصل، ولا تُقبل سوى الأصول المذكورة في تجاوز العنوان الأساسي.
enabled	flag	قيمة منطقية	لا شيء	لا	تحكم لكل تثبيت في بوابة التفعيل.
prompt	prompt	سلسلة نصية	لا شيء	لا	سؤال لطرحه على Kaleidr AI الخاص بالخريطة عند فتحها. وفي شريط الدردشة، النص المعبأ مسبقًا في الحقل. 500 حرف كحد أقصى.
promptParam	prompt-param	سلسلة نصية	لا شيء	لا	يقرأ prompt من معامل الاستعلام هذا في عنوان URL للصفحة نفسها: q في صفحة نتائج شريط الدردشة. لا يُقرأ إلا عندما يأتي الزائر من صفحة من الأصل نفسه، حتى لا يتمكن رابط من مكان آخر من جعل خريطتك تطرح أي سؤال.
layout	layout	'map' أو 'bar' أو 'locator' أو 'listings' أو 'guide' أو 'live'	'map'	لا	تثبّت القيمة bar شريط الدردشة. تعرض locator وlistings الخريطة بجانب قائمة لمجموعة: راجع تخطيطات الأماكن. تفتح guide الدردشة بجانب خريطة للمنشآت: راجع تخطيط الدليل. تعرض live المركبات ومحطات اليوم: راجع التخطيط المباشر.
collection	collection	string	أول مجموعة من نوع التخطيط ترسمها الخريطة	لا	محدد المواقع وقائمة العقارات والدليل: معرّف المجموعة المعروضة في القائمة. المباشر: معرّف مجموعة المركبات.
stops	stops	string	أول مجموعة محطات ترسمها الخريطة	لا	المباشر: معرّف مجموعة المحطات.
filters	filters	مصفوفة سلاسل نصية؛ وتفصل السمة بينها بـ |	كل عوامل تصفية المجموعة	لا	محدد المواقع وقائمة العقارات: أيٌّ من search وcategory وprice وbeds وbaths وopen_now يُعرض، مما تتيحه المجموعة.
card	card	'auto' أو 'compact'	'auto'	لا	تعرض بطاقات compact العنوان الرئيسي والعنوان الفرعي والإجراءات فقط.
prompts	prompts	مصفوفة سلاسل نصية؛ وتفصل السمة بينها بـ |	لا شيء	لا	شريط الدردشة: أمثلة أسئلة تظهر كأزرار تطرحها.
title	chat-title	سلسلة نصية	لا شيء	لا	شريط الدردشة: التسمية فوق الحقل.
placeholder	placeholder	سلسلة نصية	«Ask about this map» بلغة الشريط	لا	شريط الدردشة: النص الإرشادي للحقل.
accent	accent	لون CSS	#2da84a	لا	شريط الدردشة: لون زر الإرسال والأيقونة وحلقة التركيز.
theme	theme	'light' أو 'dark' أو 'auto'	'light'	لا	شريط الدردشة: ألوانه. تتبع auto إعداد نظام الزائر.
lang	lang	وسم لغة	لغة متصفح الزائر	لا	شريط الدردشة: لغة تسمياته الخاصة.
resultsUrl	results-url	URL	لا شيء	لا	شريط الدردشة: يرسل الزوار إلى هذه الصفحة مع ?q=<question> بدلًا من فتح الخريطة فوق الصفحة.

ليس لـ publishableKey أو styleId أو map أو mapTarget أو contained أي تأثير على تثبيت Viewer. تمرير مفتاح أسوأ من عدم الحاجة إليه: يتبادل SDK المفتاح مقابل جلسة لا يستخدمها Viewer، وإذا رُفض التبادل فلن تُعرض الخريطة.

المعرّف

تقبل shareId نوعين من معرّفات الخريطة التي ينتجها Studio:

• معرّف الخريطة المنشورة. يظهر في شيفرة صفحة النشر والتضمين، وفي علامة التضمين من مربع المشاركة؛ وهما يعرضان المعرّف نفسه.
• معرّف رابط المشاركة. هو المعرّف المكوّن من 16 حرفاً في نهاية عنوان URL في علامة مشاركة الرابط من مربع المشاركة.

يعرض معرّف الخريطة المنشورة الخريطة بحالتها المحفوظة الحالية، بينما يعرض معرّف رابط المشاركة لقطة تصميم عند إنشاء الرابط. يقبل Kaleidr AI أيّاً من المعرّفين: على رابط المشاركة يتبع مفاتيح Kaleidr AI في اللقطة، ما دامت الخريطة منشورة وعلى النطاقات المسموحة الحالية للخريطة. راجع Chat على خريطة منشورة.

لا يرمي المعرّف الفارغ أو المشوّه استثناءً. يسجّل SDK رسالة

[kaleidr:viewer] Kaleidr map: invalid id "" — must match ^[A-Za-z0-9._~-]{1,100}$.

ولا يعرض شيئاً. ومع ذلك يعيد Kaleidr.mount مقبضاً لا تفعل طرائقه شيئاً.

عنوان iframe المباشر

https://map-embed.kaleidr.com/embed/<id>?camera=<lon>,<lat>[,<zoom>]&pitch=<deg>&bearing=<deg>&q=<question>&layout=<layout>&collection=<id>&stops=<id>&filters=<a|b>&card=<card>

معامل الاستعلام	القيمة	الأثر
camera	longitude,latitude أو longitude,latitude,zoom	المركز الأولي، والتكبير اختيارياً.
pitch	رقم، بالدرجات	الميل الأولي.
bearing	رقم، بالدرجات	الدوران الأولي.
q	نص، 500 حرف كحد أقصى	سؤال لطرحه على Kaleidr AI الخاص بالخريطة عند فتحها. لا يُطرح إلا عندما يكون Viewer مضمّنًا في صفحة، ويُتجاهل على خريطة بلا Control Tower.
layout	locator أو listings أو guide أو live	أحد تخطيطات الأماكن، أو الدليل، أو التخطيط المباشر. أي قيمة أخرى تعرض الخريطة.
collection	معرّف مجموعة	المجموعة التي يعرضها التخطيط؛ وفي live مجموعة المركبات.
stops	معرّف مجموعة	في live، مجموعة المحطات.
filters	أسماء عوامل تصفية مفصولة بـ |	عوامل التصفية التي يعرضها التخطيط.
card	auto أو compact	مقدار ما تعرضه بطاقة المكان.

ينشئ SDK عنوان URL نفسه من خيارات الكاميرا ومن prompt وlayout وcollection وstops وfilters وcard.

الكاميرا

تُجمَّع الكاميرا الأولية من المصادر التالية، ويستبدل المصدر اللاحق الحقول التي يقدّمها فقط.

1. العرض الافتراضي لخريطة الأساس.
2. العرض الذي حفظه المؤلف في Studio. يمكنه حفظ عروض مستقلة لأحجام الحاسوب واللوحي والهاتف، وتختار الخريطة ما يناسب عرض iframe. ويمكنه بدلاً من ذلك ضبط الخريطة لتحتوي المحتوى تلقائياً داخل الإطار.
3. الكاميرا التي تمرّرها الصفحة (center وzoom وpitch وbearing في الخيارات أو السمات، أو camera وpitch وbearing في عنوان iframe المباشر).

تعلو إعدادات الكاميرا التي تمرّرها صفحتك على عرض المؤلف، بما في ذلك العروض حسب عرض الشاشة وتأطير المحتوى. أما الحقول التي لا تمرّرها فتحتفظ بقيم المؤلف.

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

يأتي خط الطول أولاً في center؛ فالإحداثيان [-0.1276, 51.5072] يشيران إلى لندن.

التحجيم

• يشغل iframe عرض عنصر التثبيت بنسبة 100% دون حدود، مع زوايا مدوّرة.
• ارتفاعه 100% من العنصر إذا كان للعنصر ارتفاع عند التثبيت؛ وإلا فارتفاع ثابت 500 بكسل.
• يستبدل التثبيت أبناء العنصر ويضبط position:relative (إن لم يكن موضع مضمن) وoverflow:hidden.
• تكون قيمة <kaleidr-map> هي display:block افتراضياً، لذا يسري height. حدد ارتفاعاً. تتضمن الأمثلة display:block أيضاً لإصدارات Safari الأقدم من 16.4، حيث يبقى العنصر مضمن العرض.

المقبض

يعيد Kaleidr.mount المقبض بشكل متزامن. راجع مصفوفة المقابض لجميع المنتجات.

العضو	في Viewer
handle.product	'viewer'
handle.setCamera(camera)	يحرك الخريطة.
handle.setTheme(theme)	غير مدعوم؛ يصدر تحذيراً دون أثر.
handle.setStyle(style)	غير مدعوم؛ يصدر تحذيراً دون أثر.
handle.send(text)	يطرح سؤالًا على Kaleidr AI الخاص بالخريطة كما لو كتب الزائر text. في شريط الدردشة، يطرح send() دون نص ما هو مكتوب في الحقل. والسؤال المُرسَل أثناء الإجابة عن سؤال آخر ينتظره، ويحلّ سؤال أحدث محلّ أي سؤال لا يزال منتظرًا.
handle.setFilters(filters)	يضبط عوامل تصفية الزوار في تخطيط أماكن. لا يفعل شيئًا في التخطيط map.
handle.showVehiclesLayer(layer)	ترسم طبقة المركبات الخاصة بك أو تحركها.
handle.clearVehiclesLayer()	تزيل طبقة المركبات الخاصة بك.
handle.destroy()	يزيل iframe ويتوقف عن الاستماع للرسائل.

setCamera(camera)

handle.setCamera({
  center: [2.3522, 48.8566], // [longitude, latitude]
  zoom: 12,
  pitch: 45,
  bearing: -20,
  duration: 800,             // milliseconds
});

الحقل	النوع	الوصف
center	[number, number]	خط الطول، خط العرض.
zoom	رقم	مستوى التكبير. على خلاف التثبيت، يعمل zoom هنا دون center.
pitch	رقم	الميل بالدرجات.
bearing	رقم	الدوران بالدرجات.
duration	رقم	مدة الحركة بالمللي ثانية. عند حذفه أو ضبطه على 0 تكون النقلة فورية.

كل الحقول اختيارية. الحقول المحذوفة تحتفظ بقيمها الحالية.

يمكنك استدعاء setCamera فور رجوع Kaleidr.mount، حتى في السطر التالي. إذا لم تكن خريطة iframe جاهزة بعد، يُحفظ الاستدعاء ويُطبّق بالترتيب عند إعلان الجاهزية. تُحفظ أحدث 256 عملية استدعاء. إذا لم تُبلغ الخريطة عن جاهزيتها خلال انتظار محدود، عادةً 10 ثوانٍ بعد تحميل الإطار، تُرسَل الاستدعاءات رغم ذلك ويظهر تحذير في وحدة التحكم. لا حاجة لانتظار kaleidr-embed:ready. ولضبط عرض الفتح، تظل خيارات التثبيت أقصر طريق، فتفتح الخريطة عليه مباشرة بدلاً من الانتقال إليه بعد ذلك.

لا توجد طريقة لقراءة حالة الكاميرا الحالية.

setFilters(filters)

handle.setFilters({
  q: 'downtown',
  category: ['Outlet', 'Flagship'],
  price: [250000, null],     // [min, max]; null leaves that end open
  beds: 2,
  baths: 1,
  open_now: true,
});

الحقل	النوع	يضبط
q	سلسلة نصية	حقل البحث.
category	مصفوفة سلاسل نصية	الفئات المختارة.
price	[number | null, number | null]	الحد الأدنى والحد الأقصى للسعر.
beds	رقم	الحد الأدنى لعدد غرف النوم.
baths	رقم	الحد الأدنى لعدد الحمامات.
open_now	قيمة منطقية	مفتاح مفتوح الآن.

كل الحقول اختيارية. يرى الزائر عوامل التصفية تتغير كما لو ضبطها بنفسه، ويمكنه تغييرها مجددًا. يُتجاهل أي حقل لعامل تصفية لا يعرضه التخطيط، وأي حقل آخر. كما في setCamera، يُحتفظ بالاستدعاء الذي يسبق جاهزية الخريطة ويُطبَّق حين تجهز. حزمة viewer الأقدم من تخطيطات الأماكن لا تتضمن setFilters؛ وعندها لا يفعل الاستدعاء شيئًا ويُصدر تحذيرًا في وحدة التحكم بأن التثبيت لم يوفّره.

showVehiclesLayer(layer)

ترسم على الخريطة المضمّنة مركبات تتتبعها صفحتك أصلًا، مثل المواقع من نظام التوزيع الخاص بك. تنتقل البيانات من صفحتك إلى iframe ولا تذهب إلى أي مكان آخر: لا يمر شيء عبر خوادم Kaleidr، ولا يجلب viewer أي شيء لهذه الطبقة.

handle.showVehiclesLayer({
  layer_id: 'shuttles',
  vehicles: [
    { id: 'bus-1', name: 'Shuttle 1', lat: 40.7411, lng: -73.9897, bearing: 90, color: '#1f6feb' },
    { id: 'bus-2', name: 'Shuttle 2', lat: 40.7527, lng: -73.9772 },
  ],
});

// Ten seconds later, the same layer_id: each shuttle slides to its new point.
handle.showVehiclesLayer({ layer_id: 'shuttles', vehicles: nextPositions });

handle.clearVehiclesLayer();

الحقل	النوع	الوصف
layer_id	string	يسمّي الطبقة. المعرّف نفسه مرة أخرى يحدّثها في مكانها.
vehicles	array، 2,000 على الأكثر	المركبات المراد رسمها.
vehicles[].id	string	مطلوب. يعرّف المركبة من استدعاء إلى التالي.
vehicles[].lat, vehicles[].lng	number	مطلوب. موقع المركبة.
vehicles[].name	string	التسمية المرسومة بجانب المركبة.
vehicles[].color	لون CSS سداسي عشري	لون المركبة. وبدونه تُرسم باللون الرمادي.
vehicles[].bearing	number، بالدرجات	الاتجاه الذي تواجهه المركبة.
attribution	string	إسناد لبياناتك، يُعرض على بطاقة المركبة عند النقر عليها.

• layer_id نفسه يحدّث الطبقة في مكانها. تنزلق كل مركبة من حيث هي مرسومة إلى نقطتها الجديدة خلال الوقت المنقضي منذ استدعائك السابق، 30 ثانية على الأكثر. وتختفي المركبة الغائبة عن الاستدعاء الجديد.
• layer_id جديد، أو عدم وجوده، يستبدل الطبقة. تعرض الخريطة طبقة مركبات واحدة في كل مرة.
• تُسقط المركبة التي بلا id، أو بلا lat وlng محدودين، وكذلك كل مركبة بعد الألفين.
• لتحريك المركبات، استدعِ مرة أخرى. لا يستعلم viewer أبدًا عن بيانات لهذه الطبقة.
• كما في setCamera، يُحتفظ بالاستدعاء الذي يسبق جاهزية الخريطة ويُطبَّق حين تجهز.

تصرّح أنواع SDK LiveLayerData وLiveVehicle بشكل الطبقة. showVehiclesLayer وclearVehiclesLayer من وظائف viewer: على chat وeditor وtile تُصدر تحذيرًا ولا تفعل شيئًا. حزمة viewer الأقدم من هذه الطبقة لا تتضمن أيًّا منهما؛ وعندها لا يفعل الاستدعاء شيئًا ويُصدر تحذيرًا في وحدة التحكم بأن التثبيت لم يوفّرها.

سمات العنصر بعد التثبيت

في <kaleidr-map product="viewer"> مثبَّت، يحرك تغيير center أو zoom أو pitch أو bearing الخريطة دون حركة انتقالية. ولا يؤثر تغيير share-id أو أي سمة أخرى. لعرض خريطة مختلفة، أزل العنصر وأدرج عنصراً جديداً.

رسائل iframe

يرسل iframe رسائل إلى الصفحة المضمِّنة. اثنتان منها إشارتان عامتان إلى «تم التحميل» و«فشل»:

// The map drew for the first time.
{ type: 'kaleidr-embed:ready', id: string, source: 'publish' | 'share' }

// The map could not load, or part of it failed to draw.
{ type: 'kaleidr-embed:error', id: string | null, code: string, message: string }

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://map-embed.kaleidr.com') return;
  if (event.source !== iframe.contentWindow) return; // which embed sent it
  const msg = event.data;
  if (msg?.type === 'kaleidr-embed:ready') onReady(msg);
  if (msg?.type === 'kaleidr-embed:error') onError(msg);
});

عند استخدام SDK، تكون iframe هي أول <iframe> داخل هدف التثبيت: target.querySelector('iframe').

رموز الأخطاء

code	نهائي	المعنى
no_id	نعم	لا يتضمن URL لإطار iframe معرّف خريطة، وتكون id هي null.
not_found	نعم	لا توجد خريطة منشورة ولا رابط مشاركة بهذا المعرّف: لم تُنشر الخريطة قط أو أُلغي نشرها، أو حُذفت خريطة رابط المشاركة أو أزالت Kaleidr الرابط، أو كُتب المعرّف خطأ.
domain_not_allowed	نعم	الخريطة مقيّدة بنطاقات مسموحة والصفحة ليست بينها أو لم ترسل مرجعاً.
map_loads_exhausted	نعم	استنفدت المؤسسة المالكة حصة تحميل الخرائط للفترة.
fetch_failed	نعم	تعذّر جلب الخريطة.
maplibre_error	لا	بدأت الخريطة لكن تعذّر رسم جزء منها. قد يصل عدة مرات قبل ready أو بعدها.

بعد رمز نهائي، يعرض iframe رسالة قصيرة بدلاً من الخريطة ولا يرسل ready.

القواعد

• تُرسل ready مرة واحدة لكل تحميل، بعد رسم الخريطة واحتساب المشاهدة.
• ينشئ SDK إطار iframe بقيمة loading="lazy"، فلا تصل الرسائل حتى يقترب من منطقة العرض.
• يرسل iframe رسائل أخرى يبدأ فيها type بـ kaleidr-embed:. يستخدمها SDK لربط Chat بالخريطة. ليست جزءاً من العقد العام وقد تتغير، فلا تعتمد عليها.
• لا ينفذ iframe رسائل التحكم، مثل حركة الكاميرا من setCamera، إلا إذا جاءت من الصفحة التي تضمّنه مباشرة. يتجاهل رسائل النوافذ أو الإطارات الأخرى؛ لذا استدعِ setCamera من الصفحة الحاوية للإطار.
• لا يطلق SDK ولا العنصر أحداث DOM، ولا يوفران وعد ready.

رسائل تظهر للزائر

تظهر هذه النصوص داخل iframe بدلاً من الخريطة:

النص	الرمز
"Loading map…"	لا شيء: الخريطة قيد التحميل
"Couldn't find a map id in the URL."	no_id
"This map isn't available — it may have been unpublished, paused, or the link is incorrect."	not_found
"This map isn't allowed to render on this site. Please contact the map owner."	domain_not_allowed
"This map has reached its map load limit. It will be available again when the owner's allowance resets."	map_loads_exhausted
"Could not load the map. Please try again in a moment."	fetch_failed
"Unexpected error loading the map."	لا شيء: خطأ غير متوقع عند بدء التشغيل

البيانات المرفوعة

ترسم الخريطة المنشورة مجموعات البيانات وطبقات الصور التي أضافها المؤلف من لوحة البيانات في Studio. يحمّل iframe هذه المواد بنفسه، دون خيار أو سمة أو مفتاح، ولا تمر البيانات عبر صفحتك.

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

توضح البيانات المرفوعة على خريطة منشورة كل هذه الحالات.

النطاقات المسموحة

يمكن لمالك الخريطة حصر المواقع التي تعرضها من Studio عبر المشاركة، التضمين، نطاقات محددة.

• يشمل النطاق المُدرج نطاقاته الفرعية.
• تقارن عملية التحقق القائمة باسم مضيف المرجع الذي يرسله المتصفح لطلب iframe. يفشل التحقق إذا غاب المرجع.
• عند الفشل تُعرض رسالة «غير مسموح» ويُرسَل domain_not_allowed.
• لا تُحتسب المشاهدة المرفوضة بسبب النطاق كتحميل خريطة.

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

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

رسائل وحدة التحكم

الرسالة	المعنى
[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"	ليس للعنصر product صالح، فلا يُثبَّت.
[kaleidr:viewer] Kaleidr map: invalid id "…" — must match ^[A-Za-z0-9._~-]{1,100}$.	المعرّف فارغ أو مشوّه.
[kaleidr:viewer] mount target not found: <selector>	لم يجد Kaleidr.mount عنصراً يطابق المحدد.
[kaleidr:viewer] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/viewer.js	تعذّر تحميل حزمة Viewer بسبب الشبكة أو أداة حجب أو سياسة script-src.
[kaleidr] setStyle() is not supported on product "viewer" — the call is a no-op. …	استُدعيت طريقة مقبض لا يدعمها Viewer.

غير متاح

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

صفحات ذات صلة

• تضمين خريطة منشورة
• العنصر <kaleidr-map>
• المحمّل kaleidr.js
• Chat على خريطة منشورة