إنتقل إلى المحتوى الرئيسي

Tile

يضيف Tile خريطة أساس من Kaleidr إلى صفحتك. تختار نمطًا مثل kaleidr-morning أو kaleidr-night، فيعرضه SDK داخل iframe تستضيفه Kaleidr. ولا تحتاج صفحتك إلى تحميل مكتبة خرائط.

استخدم Tile عندما تريد خريطة أساس تفاعلية جذابة من دون الحاجة إلى الرسم عليها بنفسك: خلفية لموقع، أو لوحة «أين نحن»، أو خريطة يضع عليها مساعد دردشة Kaleidr إجاباته.

إذا كانت لديك خريطة تستخدم Mapbox أو MapLibre أو Google Maps أو Leaflet بالفعل، فلن تحتاج إلى Tile. اربط Chat بخريطتك الحالية.

نظرة سريعة​

السؤالالإجابة
ماذا أحتاج؟مفتاح قابل للنشر (kld_pk_live_…) يحمل النطاق maps. وتتضمنه المفاتيح الجديدة افتراضيًا.
أي خطة؟جميع الخطط، بما فيها Free.
كيف يُعرض؟داخل iframe من https://map-embed.kaleidr.com.
كيف أختار المظهر؟باستخدام style-id. تُعرض أدناه ستة أنماط عامة.
ما التكلفة؟تحميل خريطة واحد لكل جلسة Tile. راجع كيفية احتساب تحميلات الخرائط.
هل يمكن للصفحة التحكم بالخريطة؟يمكنها تحديد الكاميرا وتحريكها وتغيير النمط والاستماع إلى رسائل التحميل والخطأ.

أبسط تضمين​

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

يتطلب التشغيل ثلاثة أمور:

  1. مفتاح. أنشئ مفتاحًا قابلًا للنشر في kaleidr.com/api-keys. راجع الحصول على مفتاح API.
  2. مصدر مسموح به. إذا حدد المفتاح مصادر مسموحة، فيجب أن يكون مصدر صفحتك ضمنها. قدّم الصفحة عبر HTTP أو HTTPS، ولا تفتحها مباشرة من القرص.
  3. ارتفاع. يُعرض العنصر افتراضيًا باستخدام display:block، ولذلك يُطبق height. ويحدد المثال display:block أيضًا لدعم Safari قبل 16.4، حيث يبقى العنصر مضمنًا في السطر.

الأنماط​

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

مرّر style-id دائمًا. إذا حذفته، يستخدم التضمين خريطة الأساس الافتراضية لمؤسستك عند إعدادها، ويعرض خطأ عند عدم وجودها.

كيفية العمل​

  1. يرسل SDK مفتاحك القابل للنشر إلى Kaleidr ويتلقى جلسة Tile قصيرة العمر. في هذه الخطوة يتحقق من المفتاح ونطاقه ومصدر صفحتك، ويحتسب تحميل خريطة واحدًا. وتتضمن الاستجابة خريطة الأساس الافتراضية لمؤسستك إن كانت محددة. هذا هو الغرض الوحيد من جلسة Tile؛ ولا تجري الخريطة طلبات أخرى باستخدامها.
  2. يستبدل SDK محتوى العنصر بإطار iframe يعرض النمط المطلوب. يحتوي عنوان URL للإطار على معرّف النمط والكاميرا التي مررتها فقط؛ ولا يحتوي المفتاح القابل للنشر أو رمز الجلسة.
  3. تُرسم الخريطة داخل iframe. لا تحتاج سياسة أمان المحتوى في صفحتك إلا إلى السماح ببرنامج التحميل وطلب الجلسة والإطار.
  4. عند انتهاء رسم الخريطة، يرسل iframe رسالة kaleidr-embed:ready إلى صفحتك.

ما يستطيع الزائر فعله​

تحريك الخريطة وتدويرها وإمالتها، والتكبير بأزرار الخريطة أو حركة القرص بالأصابع أو عجلة التمرير. يكبّر التمرير الخريطة حين يكون المؤشر فوقها؛ وحين يكون المؤشر خارج الخريطة يحرّك التمرير صفحتك.

ما تستطيع صفحتك فعله​

  • تحديد الكاميرا الابتدائية باستخدام center وzoom وpitch وbearing.
  • تحريك الكاميرا لاحقًا باستخدام handle.setCamera(...).
  • تبديل النمط باستخدام handle.setStyle('kaleidr-night') دون إعادة تحميل.
  • إقران لوحة دردشة. يمكن لإعداد الدردشة الإشارة إلى عنصر Tile وعرض الإجابات عليه.
  • معرفة اكتمال التحميل من رسالة kaleidr-embed:ready.

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

يُقاس استخدام Tile بتحميلات الخرائط، وهي الوحدة نفسها المستخدمة لمشاهدات خرائطك المنشورة. ويُحتسب تحميل خريطة واحد كلما حصل SDK على جلسة Tile:

  • عند تركيب الخريطة أول مرة؛
  • وكلما جدد SDK الجلسة قبل انتهائها بقليل، ما دام التركيب قائمًا. تستمر الجلسات 15 دقيقة افتراضيًا؛
  • وعند إتلاف التركيب وإعادة إنشائه، أو إزالة العنصر وإدراجه مرة أخرى.

يستهلك الزائر الذي يشاهد الصفحة بضع دقائق تحميل خريطة واحدًا. وتستهلك الصفحة المفتوحة ساعةً نحو خمسة تحميلات. هذا ليس «تحميلًا واحدًا لكل مشاهدة صفحة»، لذا أتلف تركيبات Tile التي لم تعد تعرضها.

إذا استنفدت مؤسستك رصيد تحميلات الخرائط للفترة، تُرفض جلسات Tile الجديدة برمز HTTP 429. لا يعرض التركيب الجديد شيئًا، لكن الخريطة الموجودة في الصفحة تظل ظاهرة. راجع حدود الاستخدام في الحصص وحدود المعدل.

القيود​

  • Tile خريطة أساس؛ لا تستطيع صفحتك إضافة علامات أو طبقات أو نوافذ منبثقة خاصة بها إليها، ولا تتلقى أحداث النقر أو الكاميرا منها. تستطيع لوحة الدردشة المقترنة رسم أماكن عليها.
  • منتج Tile هو الطريقة المدعومة لعرض خريطة أساس من Kaleidr.
  • تغيير style-id في عنصر تم تركيبه لا يؤثر. استخدم handle.setStyle أو أدرج عنصرًا جديدًا.
  • لا يوجد مفتاح مستقل لـTile. يمكنك استخدام المفتاح القابل للنشر نفسه المستخدم مع منتجات Kaleidr الأخرى.

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