إصدارات شبكة توزيع المحتوى
تُقدَّم SDK في خمسة ملفات ضمن مسار واحد يتضمن رقم الإصدار. تشير صفحتك إلى الملف الأول الذي يحمّل البقية عند تثبيت منتج.
https://cdn.kaleidr.com/embed/v1/kaleidr.js the loader: window.Kaleidr and <kaleidr-map>
https://cdn.kaleidr.com/embed/v1/chat.js the chat panel
https://cdn.kaleidr.com/embed/v1/viewer.js the viewer's iframe loader
https://cdn.kaleidr.com/embed/v1/tile.js the tile iframe loader
https://cdn.kaleidr.com/embed/v1/editor.js the editor
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
يُطلب ملف حزمة المنتج عند تثبيته للمرة الأولى على الصفحة، ولمرة واحدة كحد أقصى لكل صفحة. الصفحة التي تعرض Viewer فقط لا تنزّل chat.js ولا editor.js.
ما معنى v1
يسمّي v1 عقد توافق وليس نسخة بناء محددة.
- يوجد ملف واحد في كل عنوان URL، ويستبدله الإصدار الجديد في المكان نفسه.
- لا توجد إصدارات تصحيحية منفصلة ولا مسارات تتضمن بصمة المحتوى. لا يمكن تثبيت
/embed/v1.2.3/kaleidr.jsلأن هذا المسار غير موجود. - تُنشر الإصلاحات والإضافات المتوافقة مع الإصدارات السابقة إلى
/embed/v1/وتصل إلى صفحتك دون أي تعديل.
Kaleidr.version سلسلة نصية للتشخيص، ولا تمثل نسخة بناء تستطيع طلبها.
ما يبقى ثابتًا ضمن v1
| العنصر الثابت | المعنى |
|---|---|
| عناوين URL الخمسة | تظل متاحة. |
window.Kaleidr | تحتفظ mount وinit وenable وversion بالسلوك الموثّق. |
| خيارات التثبيت وسمات العناصر | يحتفظ كل خيار موثّق باسمه ومعناه. |
| مقبض التحكم | يحتوي كل مقبض على setCamera وsetTheme وsetStyle وdestroy. إذا لم يدعم المنتج دالةً، تعرض تحذيرًا ولا تفعل شيئًا؛ ولا ترمي استثناءً أو تُزال. |
| رسالتا iframe | تحتفظ kaleidr-embed:ready وkaleidr-embed:error بحقولهما الموثّقة. |
ما الذي يمكن تغييره داخل v1:
- إضافات. قد تظهر خيارات وسمات ودوال للمقبض وحقول رسائل ورموز خطأ وأحداث بث جديدة. اكتب شيفرة تتجاهل ما لا تتعرف عليه من حقول الرسائل أو قيم
codeأو الأحداث. - المظهر. قد يتغير شكل لوحة المحادثة والمحرر وعناصر التحكم في الخريطة.
- السلوك غير الموثّق. أي شيء لا تصفه الوثائق، بما فيه رسائل
kaleidr-embed:الأخرى بين SDK وإطاراتها، والمتغيرات العامة التي تعرّفها حزم المنتجات، والنص الدقيق لرسائل وحدة التحكم.
تتبع واجهة HTTP القاعدة نفسها في /inference-api/b2b/v1/: لا يظهر v2 إلا عند تغيير يكسر التوافق. وتُسجل التغييرات في سجل التغييرات.
كيفية نشر تغيير غير متوافق
لا يُنشر التغيير الذي سيعطل تكامل v1 يعمل حاليًا ضمن /embed/v1/. بل يُطلق إصدار رئيسي جديد إلى جانبه:
https://cdn.kaleidr.com/embed/v2/kaleidr.js
https://cdn.kaleidr.com/embed/v2/<product>.js
يظل وسم السكربت v1 يحمّل ملفات v1. بعد قراءة التغييرات والاستعداد للترقية، غيّر المسار في وسم السكربت إلى الإصدار الرئيسي الجديد. يطلب المحمّل حزم منتجات تنتمي إلى إصداره الرئيسي نفسه.
التخزين المؤقت
يُقدَّم كل ملف مع
Cache-Control: public, max-age=300
وتُستبدل نسخة شبكة التوزيع عند كل إصدار.
| السؤال | الإجابة |
|---|---|
| متى يصل الإصدار الجديد إلى الزائر؟ | خلال نحو خمس دقائق. إذا جلب المتصفح الملف القديم خلال الدقائق الخمس الماضية، يستمر في استخدامه حتى تنتهي صلاحية النسخة المخزنة. |
| هل يُعاد تنزيل SDK عند فتح كل صفحة؟ | لا. يستخدم المتصفح النسخة المخبأة لمدة خمس دقائق من جلبها، ثم يتحقق من شبكة التوزيع مجددًا. |
| هل يمكنني تخزين الملفات مؤقتًا مدة أطول؟ | لا. فقد يواصل الخادم الوسيط أو عامل الخدمة أو عملية البناء تقديم شيفرة قديمة بعد التحديث. |
هل يمكنني إضافة تكامل الموارد الفرعية (integrity="sha384-…")؟ | لا. تتغير بصمة الملف مع كل إصدار ويرفض المتصفح أي سكربت لا تطابق بصمته. وعندها تتوقف العناصر المضمّنة عن التحميل بعد الإصدار التالي. |
هل يمكنني نسخ kaleidr.js إلى حزمتي؟ | لا، للسبب نفسه. استخدم عنوان URL مباشرة. |
إذا كان لدى موقعك عامل خدمة يخزن سكربتات من مصادر أخرى، فاستثنِ https://cdn.kaleidr.com من قواعد إعطاء الأولوية للتخزين المؤقت، أو استخدم استراتيجية تعيد التحقق.
يُنشر المحمّل والحزم بشكل منفصل
تُطلق الملفات الخمسة باستقلالية، لذا قد تستخدم صفحة لفترة قصيرة بعد الإصدار kaleidr.js أحدث مع حزمة منتج قديمة من ذاكرة المتصفح، أو العكس. صُممت SDK لتتحمل ذلك:
-
يمرر المحمّل الخيارات إلى الحزمة ويتسامح مع عدم تعرف الحزمة القديمة على خيار أحدث.
-
إذا استدعيت دالة يدعمها المنتج لكنها غير موجودة بعد في الحزمة المخزنة مؤقتًا، فلا يحدث شيء وتظهر رسالة في وحدة التحكم:
[kaleidr] setStyle() IS supported on product "tile", but this mount did not expose it, so the call did nothing. …تؤدي إعادة تحميل الصفحة مع تجاوز التخزين المؤقت إلى جلب الحزمة الحالية. وتزول الحالة تلقائيًا عند انتهاء صلاحية النسخة المخزنة.
تُقدّم الصفحات داخل إطارات Viewer وTile من https://map-embed.kaleidr.com وتُنشر مستقلة كذلك. لا يؤثر أسلوب تخزين SDK في صفحتك عليها.
الاستضافة الذاتية
يم كنك تقديم الملفات الخمسة من مصدرك الخاص، لتكون جميع مصادر السكربتات تابعة لك. لكن انتبه للمقايضة: النسخة المستضافة ذاتيًا لا تتلقى الإصلاحات تلقائيًا. تواصل واجهة API والصفحات داخل الإطارات التطور لدى Kaleidr، فتبتعد النسخة التي لا تحدّثها عن توافقها معها.
للاستضافة الذاتية:
-
انسخ الملفات الخمسة جميعًا إلى
https://your-origin/embed/v1/. المسار ثابت ولا يتغير إلا المصدر. -
أخبر المحمّل بمكان حزمه قبل تشغيله:
<script>window.__KALEIDR_EMBED_BASE__ = 'https://cdn.example.com';</script><script src="https://cdn.example.com/embed/v1/kaleidr.js"></script>أو عند كل تثبيت باستخدام الخيار
baseأو السمةbase. -
أعد نسخ الملفات بانتظام وقدّمها بمدة تخزين مؤقت قصيرة، كما يفعل Kaleidr.
المصادر المقبولة لتجاوز عنوان base
لا يحمّل المحمّل الحزم من أي مصدر عشوائي. ولا يعمل تجاوز base (المتغير العام للصفحة أو خيار base أو سمة base) إلا إذا كان المصدر:
- شبكة Kaleidr (
https://cdn.kaleidr.com)؛ - المصدر الذي حُمّل منه
kaleidr.jsنفسه؛ أو - مصدر الصفحة الحالية.
تعمل الاستضافة الذاتية عندما يُقدّم المحمّل والحزم من المصدر نفسه. هذا هو ترتيب الخطوة 2: يأتي kaleidr.js من https://cdn.example.com، لذلك يُقبل https://cdn.example.com كعنوان base. كما يُقبل تقديم الحزم من المصدر الخاص بالصفحة.
تُتجاهل أي قيمة أخرى، بما فيها مضيف آخر ضمن kaleidr.com. يستمر تثبيت العنصر المضمّن، لكنه يحمّل الحزم من https://cdn.kaleidr.com، وتظهر في وحدة التحكم رسالة:
[kaleidr] base "https://other.example.net" is IGNORED — bundles load from https://cdn.kaleidr.com. A base must be the Kaleidr CDN, the origin kaleidr.js was loaded from, or this page's own origin.
لا تسمح القاعدة بهذين الترتيبين:
- تحميل
kaleidr.jsمنhttps://cdn.kaleidr.comمع توجيه base إلى مصدر ثالث. حمّل المحمّل من ذلك المصدر أيضًا. - وجود المحمّل على أحد مصادرك والحزم على مصدر آخر، ولا يماثل أيهما مصدر الصفحة. قدّم الملفات الخمسة من مصدر واحد.
إذا ظهر التحذير في صفحة لا تسمح سياسة أمان المحتوى فيها إلا بمصدر سكربتاتك، فستحظر السياسة طلب الحزم من https://cdn.kaleidr.com ولن يظهر شيء. أصلح base لا السياسة.
ما الذي تغيّره الاستضافة الذاتية وما الذي لا تغيّره:
- استضافة
kaleidr.jsوحده لا تكفي؛ دون تجاوز base يستمر المحمّل في جلب الحزم منhttps://cdn.kaleidr.com. - يُستخدم مصدر
baseفقط، ويُهمل أي مسار في القيمة، وتُطلب الحزم من/embed/v1/على ذلك المصدر. - يجب أن يكون
window.__KALEIDR_EMBED_BASE__سلسلة نصية، وتتجاهل القيم الأخرى. - تنقل الاستضافة الذاتية السكربتات فقط. يظل تبادل الجلسة يستخدم
https://api.kaleidr.com، وإطارات Viewer وTile تستخدمhttps://map-embed.kaleidr.com، وخريطة أساس Editor تأتي منhttps://tile.kaleidr.com. يجب أن تواصل سياسة أمان المحتوى السماح بهذه المصادر.