حزمة SDK لمحرر الخرائط: كيفية إضافة إنشاء الخرائط إلى منتج SaaS

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

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

أساسيات حزمة SDK لمحرر الخرائط

• سطح التحرير مقابل المنتج: يملك المحرر لوحة التحرير؛ ويملك التطبيق المضيف المستخدمين والمشروعات والصلاحيات والتخزين الدائم والإصدار.
• في الذاكرة افتراضيًا: لا يحفظ Kaleidr Editor المستقل التعديلات بشكل دائم، لذا خطط للحفظ والنشر قبل الإطلاق.
• مفتاح قابل للنشر + design: استخدم مفتاح متصفح مقيّدًا بنطاقات المصدر ويحمل نطاق design؛ ولا تكشف مفاتيح الخادم مطلقًا.
• ركّب مرة واحدة ودمّر مرة واحدة: اربط دورة الحياة بمسارات تطبيق الصفحة الواحدة وتبديل المستأجرين.
• افصل صلاحيات النشر: تحرير مسودة لا يمنح الصلاحية نفسها اللازمة لإصدار خريطة عامة.

كيف تضيف حزمة SDK لمحرر الخرائط إلى منتج SaaS؟

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

ما الفرق بين حزمة SDK لمحرر الخرائط وStudio أو Viewer أو GIS؟

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

Kaleidr Studio هو منتج التأليف الكامل الذي يبدأ بالموجّه وينظم العمل وفق Prompt → Process → Refine → Deploy. أما Kaleidr Editor فهو سطح التحرير القابل للتضمين، ويعرض Kaleidr Viewer خريطة منشورة. تشترك هذه المسارات في مفاهيم الرسم والأنماط، لكنها ليست أسطح منتجات قابلة للاستبدال.

كيف ينبغي لبنية SaaS أن تدير ملكية حالة المحرر؟

يتطلب سير عمل إنتاجي لتحرير الخرائط ملكية واضحة عبر إطار التطبيق والمحرر وبيانات الاعتماد وسياسة الواجهة الخلفية وأنظمة البيانات والتسليم. يملك تطبيق SaaS المضيف الهوية والمستأجر والتنقل والمشروعات والفوترة والصلاحيات وسير العمل. ويملك Kaleidr Editor سطح التحرير داخل الصفحة وخريطة MapLibre ودورة الحياة والأدوات المتاحة من جانب العميل. يمنح المفتاح القابل للنشر وصول المتصفح إلى منتج Editor وإمكان design. وتملك الواجهة الخلفية للتطبيق المضيف التفويض والتخزين الدائم والإصدارات والتدقيق والاستيراد والتصدير وسياسة النشر. وتملك أنظمة البيانات الموثوقة مجموعات البيانات وقواعد الأعمال. ويقدم Viewer أو وجهة أخرى المخرجات المعتمدة للقراءة فقط.

يجب ألا تثق الواجهة الخلفية للتطبيق المضيف بمعرّف مشروع أو مستأجر أو مجموعة بيانات أو هدف نشر يرسله المتصفح من دون إعادة تفويضه. يجعل تركيب المحرر إنشاء الخرائط طبيعيًا داخل المنتج، لكن المتصفح يظل بيئة غير موثوقة. توضح الوثائق العامة أن product: "editor" يحدد حزمة Editor، وأن المدخل الافتراضي هو attach/in-process وليس iframe، وأن styleId يقبل معرّف خريطة أساس من الكتالوج أو عنوان URL كاملًا للنمط، وأن خريطة الأساس الافتراضية هي kaleidr-morning، وأن المقبض يوفر دائمًا destroy()، بينما تتوفر تحديثات الكاميرا والسمة حيثما كانت مدعومة. لا يحفظ التضمين المستقل التعديلات بشكل دائم، ولا يتضمن واجهات Studio الكاملة المعتمدة على الذكاء الاصطناعي أو Control Tower أو مكتبة أصول ثلاثية الأبعاد مكتفية بذاتها من دون إعداد إضافي للواجهة الخلفية.

كيف تركّب Kaleidr Editor بأمان؟

تحقق من توفر Pro أو Enterprise لمفاتيح API وعمليات التضمين، ومن وجود مفتاح قابل للنشر مسموح له باستخدام Editor ويحمل نطاق design، ونطاقات مصدر دقيقة لبيئات التطوير والاختبار والإنتاج، وعنصر هدف بارتفاع صريح، ونمط ابتدائي، ونموذج للمشروع والصلاحيات لدى التطبيق المضيف، واستراتيجية تخزين دائم، وآلية تفكيك لتطبيق الصفحة الواحدة. حمّل أداة التحميل ذات الإصدار مرة واحدة من https://cdn.kaleidr.com/embed/v1/kaleidr.js. تكون أداة التحميل خاملة افتراضيًا، لذا فعّل عمليات التضمين قبل تحميلها أو مرر خيار enabled لكل عملية تركيب. يبدو التركيب الأدنى كما يلي:

const editor = Kaleidr.mount("#editor", {
  product: "editor",
  publishableKey: "kld_pk_live_REPLACE_ME",
  styleId: "kaleidr-morning",
  enabled: true
});

window.addEventListener("pagehide", () => {
  editor.destroy();
});

استبدل المفتاح النائب بمفتاح حقيقي قابل للنشر، وخصص ارتفاعًا كافيًا للوحة كي تستوعب أدوات التحرير، وأعلن حالة التحميل أو الفشل خارج الخريطة. يتبع المثال مرجع إرفاق Editor الحالي، ودليل تكامل Editor، ومرجع أداة التحميل kaleidr.js. يركّب المثال المحرر، لكنه لا يحفظ المواصفات الموجودة في الذاكرة لأن مرجع المقبض العام لا يوثّق أساليب التخزين الدائم. يمكن لعنصر <kaleidr-map> تحديد product="editor" مع publishable-key وstyle-id عندما تكفي الصيغة التصريحية. فضّل واجهة API الإجرائية عندما يحتاج التطبيق المضيف إلى مقبض صريح أو دورة حياة تديرها بنية العمل. في React أو أي تطبيق صفحة واحدة آخر، ركّب مرة واحدة داخل effect واستدعِ destroy() عند التنظيف؛ ولا تعِد التركيب مع كل تغيير في حقول النموذج.

كيف تخطط للتخزين الدائم والأمان وتجربة المستخدم؟

يحتفظ التضمين المستقل بالتعديلات في الذاكرة. تختار الفرق عادةً أحد ثلاثة مسارات: استخدام Editor كسطح مؤقت للنماذج الأولية؛ أو إبقاء التأليف الكامل في Kaleidr Studio عندما يستطيع المستخدمون مغادرة إطار SaaS؛ أو بناء سير عمل متكامل مع التطبيق المضيف يشمل تحميل المشروع والتحقق وحفظ المسودة وإدارة الإصدارات ومعالجة التعارض والموافقة والنشر والتراجع والتدقيق. لا يوثّق مرجع Editor SDK العام أساليب يمكن افتراضها مثل الحفظ غير الموثق أو مستمعي التغيير؛ لذلك أكّد مع Kaleidr نقطة نقل الحالة المدعومة قبل الوعد بحفظ موجّه للعملاء. تنتمي مسارات design في المنصة—مثل تحليل مجموعات البيانات والتطبيق الجزئي لمواصفات الخريطة وكتالوجات الأنماط أو السمات—إلى الواجهة الخلفية للتطبيق المضيف خلف مفتاح خادم؛ بينما يواصل Editor في المتصفح استخدام المفتاح القابل للنشر عبر حزمة SDK.

قيّد المفاتيح القابلة للنشر بنطاقات المصدر الدقيقة، واشترط HTTPS خارج التطوير المحلي، واحصر نطاق المفاتيح في design والمنتجات المطلوبة فقط، ودمّر المحرر عند تبديل الحساب أو المستأجر. في الواجهة الخلفية، فوّض كل مشروع ومجموعة بيانات حسب المستخدم والمستأجر، وتحقق من الملكية بصورة مستقلة عن حالة المتصفح، وتحقق من مواصفات الخريطة قبل حفظها أو نشرها، وافصل صلاحيات المسودة والمراجعة والنشر. يعدّ OWASP API Security Top 10 كسر التفويض على مستوى الكائن من المخاطر الرئيسية؛ لذلك لا يكفي معرّف مشروع يقدمه المتصفح للتفويض أبدًا. أبقِ إطار المنتج ظاهرًا كي يعرف المستخدم المشروع الذي يحرره، وضع إجراءات الحفظ والنشر في واجهة التطبيق المضيف بدل اختلاق حالة «تم الحفظ» غير صحيحة اعتمادًا على تعديلات الذاكرة وحدها، وخصص مساحة رأسية أكبر مما يحتاجه العارض عادةً. امنح منطقة المحرر اسمًا يسهل الوصول إليه، وحافظ على وصول لوحة المفاتيح إلى الإجراءات المحيطة، وتجنب مصائد التركيز، وأعلن حالة الحفظ والأخطاء، ووفّر بدائل لا تعتمد على السحب حيثما أمكن وفق WCAG 2.2.

الحكم النهائي

يمكن لحزمة SDK لمحرر الخرائط أن تضيف إنشاء الخرائط إلى منتج SaaS من دون إعادة بناء لوحة تحرير كاملة وتكامل محرك الرسم ونموذج مصادقة المتصفح من الصفر. يوفر Kaleidr Editor حاليًا سطحًا داخل الصفحة وقابلًا للتضمين ومبنيًا على MapLibre، وتتم مصادقته بمفتاح قابل للنشر يحمل نطاق design. يحتفظ التضمين المستقل بالتعديلات في الذاكرة، لذا لا يعني تركيب المحرر إطلاق نظام تأليف كامل ذي تخزين دائم. اختر Editor SDK عندما يحتاج المنتج إلى سطح تحرير متكامل، ويكون فريق التطبيق المضيف مستعدًا لامتلاك المشروعات والصلاحيات والتخزين الدائم والنشر وإمكان التدقيق. اختر Kaleidr Studio عندما يكون سير عمل تأليف كامل ومنفصل مقبولًا. وأكّد نقطة نقل الحالة وأي نقاط تكامل بمساعدة الذكاء الاصطناعي قبل الوعد بحفظ موجّه للعملاء.

أضف تحرير الخرائط إلى منتج SaaS الخاص بك

ركّب Kaleidr Editor باستخدام أداة تحميل JavaScript ذات إصدار، ومفتاح قابل للنشر ومقيّد بنطاقات المصدر، ونطاق design. اقرأ دليل تكامل Editor لمعرفة خيارات الإرفاق ودورة الحياة. ولمراجعة المصادقة ونقاط نهاية التصميم ومسارات العمل المتكاملة مع التطبيق المضيف، راجع وثائق المطورين ومتطلبات Enterprise.

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

ما حزمة SDK لمحرر الخرائط؟

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

هل يمكن تضمين Kaleidr Editor في منتج SaaS؟

نعم. توثّق حزمة SDK الحالية product: "editor" للتركيب داخل عنصر هدف. وينشئ Editor خريطة MapLibre خاصة به داخل الصفحة.

هل يحفظ Editor المستقل خرائط المستخدمين؟

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

ما بيانات الاعتماد التي يستخدمها Editor؟

استخدم مفتاح متصفح قابلًا للنشر عبر حزمة SDK، ويحمل نطاق design ويقتصر على نطاقات المصدر المعتمدة. لا تضع مفتاح خادم في شيفرة المتصفح مطلقًا.

هل Kaleidr Editor هو نفسه Kaleidr Studio؟

لا. Studio هو منتج الإنشاء والنشر الكامل الذي يبدأ بالموجّه. أما Editor فهو سطح التحرير القابل للتضمين لاستخدامه داخل تطبيق آخر.

References

• Kaleidr. Attach the Map Editor. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/guides/attach-the-editor
• Kaleidr. Auth & Scopes. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/platform-api/auth-and-scopes
• Kaleidr. CORS & Allowed Origins. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/platform-api/cors-and-allowed-origins
• Kaleidr. Editor — Mount the Map Editor. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/sdk/editor-attach
• Kaleidr. Endpoints. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/platform-api/endpoints
• Kaleidr. kaleidr.js — the Loader. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/sdk/kaleidr-js
• Kaleidr. Pricing & Plans. kaleidr.com. Accessed 3 August 2026. https://kaleidr.com/pricing
• MapLibre. Map — MapLibre GL JS. Accessed 3 August 2026. https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/
• OWASP. OWASP Top 10 API Security Risks — 2023. Accessed 3 August 2026. https://owasp.org/API-Security/editions/2023/en/0x11-t10/
• World Wide Web Consortium. Web Content Accessibility Guidelines (WCAG) 2.2. Accessed 3 August 2026. https://www.w3.org/TR/WCAG22/

@misc{kaleidr_editor_attach,
  title  = {Editor -- Mount the Map Editor},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 3 August 2026},
  url    = {https://docs.kaleidr.com/sdk/editor-attach}
}

@misc{kaleidr_editor_guide,
  title  = {Attach the Map Editor},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 3 August 2026},
  url    = {https://docs.kaleidr.com/guides/attach-the-editor}
}

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

@misc{kaleidr_auth_scopes,
  title  = {Auth and Scopes},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 3 August 2026},
  url    = {https://docs.kaleidr.com/platform-api/auth-and-scopes}
}

@misc{owasp_api_security,
  title  = {OWASP Top 10 API Security Risks -- 2023},
  author = {{OWASP}},
  note   = {Accessed 3 August 2026},
  url    = {https://owasp.org/API-Security/editions/2023/en/0x11-t10/}
}

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