الحصول على مفتاح API

يحدد مفتاح واجهة API مؤسستك لدى Kaleidr. تُفحص كل طلبات المفتاح، سواء من المتصفح أو الخادم، وفق خطة مؤسستك وتُحتسب ضمن استخدام المؤسسة. يمكنك إنشاء المفاتيح وإدارتها في kaleidr.com/api-keys.

تحتاج إلى مفتاح لاستخدام Chat وEditor وTile ولاستدعاء واجهة الخادم. لا تحتاج إلى مفتاح لتضمين خريطة منشورة عبر Viewer، إذ يكفي معرّف الخريطة.

نوعا المفاتيح

هناك نوعان من المفاتيح، ويعتمد اختيار النوع على مكان تشغيل الشيفرة التي تستخدمه.

	مفتاح قابل للنشر	مفتاح خادم
البادئة	`kld_pk_live_…`	`kld_sk_live_…`
مكان التشغيل	صفحة ويب عبر SDK وعنصر `<kaleidr-map>`	خوادمك فقط
هل يمكن وضعه في مصدر الصفحة؟	نعم	لا. عامله ككلمة مرور.
طريقة الاستخدام	يستبدله SDK برمز جلسة قصير العمر، وتنفّذ الجلسة الاستدعاءات	يُرسل مباشرة مع كل طلب عبر `Authorization: Bearer` أو `X-Api-Key`
القيود الممكنة	المواقع المدرجة في قائمة الأصول المسموح بها	أي قيد تضبطه عبر واجهة إدارة المفاتيح، مثل قائمة عناوين IP المسموح بها
الخطط	Free وPro وEnterprise	Pro وEnterprise
الاسم في صفحة API Keys	Browser / Embed Key	Server Key

استخدم مفتاحًا قابلًا للنشر في كل ما يعمل داخل متصفح الزائر؛ فقد صُمم ليكون ظاهرًا. تحميه قائمة الأصول المسموح بها وعدم قدرته على استدعاء API مباشرة: تُرفض محاولة إرسال المفتاح القابل للنشر مباشرة إلى نقطة نهاية بحالة 401 publishable_requires_session.

استخدم مفتاح خادم حين يستدعي نظامك الخلفي Kaleidr، مثل مهمة الترميز الجغرافي للعناوين أو مسار API يرسل الإجابة تدريجيًا إلى واجهتك أو الخادم الخلفي لتطبيق جوال. يُرفض مفتاح الخادم حين يحمل الطلب ترويسة Origin التي ترسلها المتصفحات، مع 403 server_key_in_browser، ويرفض SDK تركيبه أيضًا قبل إرسال أي طلب. لا تضع مفتاح خادم داخل صفحة ويب أو ملف تطبيق جوال.

ينتمي النوعان إلى المؤسسة نفسها ويستهلكان حصص الاستخدام نفسها. راجع آلية عمل Kaleidr لمعرفة الجلسات والمؤسسات وقياس الاستخدام.

تبدأ المفاتيح المنشأة قبل ظهور النوعين بالبادئة kld_live_. ولا تزال تعمل وتُرسل مباشرة مثل مفتاح الخادم.

ما تسمح به كل خطة

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

الخطة	قابل للنشر	للخادم	الصلاحيات المتاحة	المنتجات المتاحة
Free	نعم	— (403 `free_plan_publishable_only`)	`ai` و`maps` و`design`	`chat` و`editor` و`viewer` و`tile`
Pro	نعم	نعم	`ai` و`maps` و`design`	`chat` و`editor` و`viewer` و`tile`
Enterprise	نعم	نعم	`ai` و`maps` و`design` و`vendor`*	`chat` و`editor` و`viewer` و`tile`

* لا تتضمن المفاتيح vendor افتراضيًا، ولا تحمله إلا مفاتيح Enterprise. راجع نطاقات الصلاحيات.

تقيّد كل خطة أيضًا عدد المفاتيح النشطة التي تحتفظ بها المؤسسة:

الخطة	المفاتيح النشطة
Free	2
Pro	10
Enterprise	25

عند تجاوز الحد يُرفض إنشاء المفتاح بالحالة 409 key_limit_reached. ألغِ مفتاحًا لإنشاء آخر. لا يُحتسب تدوير المفتاح إنشاءً جديدًا، لكن المفتاح القديم يظل ضمن الحد حتى انتهاء فترة السماح.

خمس نقاط مهمة بشأن هذا الجدول:

تتيح Free جميع منتجات المتصفح. يمكن لمؤسسة Free وضع Chat وEditor وTile وViewer على موقعها. تستهلك إجابات Chat رصيد الذكاء الاصطناعي الشهري، وبعد نفاده تُرجع الطلبات 429 حتى دورة الفوترة التالية أو شراء حزمة إضافية أو الترقية.
إدراج Viewer يعني أن الخطة تتيحه، لا أنه يحتاج إلى مفتاح. يمكن تضمين خريطة منشورة دون مفتاح في جميع الخطط.
تضيف Pro مفاتيح الخادم وعددًا أكبر من المفاتيح. يمكن لمؤسسة Pro إنشاء مفاتيح لخادمها الخلفي والاحتفاظ بعشرة مفاتيح نشطة بدلًا من مفتاحين. وتدعم صلاحيات ومنتجات Free نفسها.
الاستعانة ببيانات مؤسستك التجارية في إجابات الذكاء الاصطناعي حصرية لـEnterprise، من جهة الرفع والوصول. يستطيع مالك مؤسسة Enterprise أو مسؤولها رفع بيانات تجارية ضمن القيود المحددة بالعقد؛ ويستخدم مساعد Kaleidr Studio تلك البيانات لأعضاء المؤسسة المسجلين. لا تستطيع Free وPro رفعها. كما أن المفتاح المخوّل عبر API أو SDK للوصول إليها بنطاق vendor متاح فقط لـEnterprise. وتُرفض محاولة إنشاء مفتاح بـvendor على Free أو Pro مع 403 tier_capability_not_allowed. راجع بياناتك.
يمكن لجميع الخطط إضافة مجموعات بيانات إلى خرائط Kaleidr Studio. يرفع المستخدم المسجل جداول بيانات وملفات جغرافية من لوحة Data. حدود Free هي 50,000 صف للمجموعة الواحدة و32 MiB للملف و250,000 صف للمؤسسة كلها. وفي Pro هي 100,000 صف و64 MiB و5,000,000 صف إجمالًا. أما Enterprise فلها الحدود نفسها للمجموعة والملف مثل Pro (100,000 صف و64 MiB) ويحدد العقد إجمالي المؤسسة. تُرسم هذه البيانات على الخريطة في Studio ولزوار الخريطة المنشورة، ويمكن لمساعد Studio الإجابة عنها، لكنها لا تُقرأ بواسطة مفتاح API. راجع مجموعات البيانات على الخريطة.

الأسعار والحصص موضحة في صفحة الأسعار. وتُحدد حدود Enterprise بصورة مخصصة في العقد.

نطاقات الصلاحيات

النطاق (scope) إذن يحمله المفتاح؛ ويتحقق المنتج أو نقطة النهاية من النطاق الذي يحتاجه.

النطاق	ما يسمح به	في مفتاح جديد
`ai`	Chat ونقاط نهاية الدردشة والأماكن والترميز الجغرافي في API الخادم	مضمن
`maps`	جلسات الخرائط الأساسية في Tile	مضمن
`design`	Editor ونقاط نهاية التصميم في API الخادم	مضمن
`vendor`	استخدام بيانات مؤسستك التجارية المنشورة ضمن إجابات Chat	غير مضمن، ويجب طلبه. Enterprise فقط.

تحمل المفاتيح المنشأة من صفحة API Keys دائمًا ai وmaps وdesign، ولا يوجد فيها اختيار للنطاقات. لإنشاء مفتاح بنطاق vendor (Enterprise فقط) أو استبعاد نطاق افتراضي استخدم واجهة المفاتيح.

تُثبت النطاقات عند إنشاء المفتاح. لا يمكن تعديلها لاحقًا، ويحتفظ بها المفتاح عند تدويره باستثناء حالتين: يُحذف أي نطاق لم تعد الخطة الحالية تسمح به من البديل؛ وفي Free يحمل البديل دومًا جميع صلاحيات Free (انظر عند تغيير خطتك). لتعديل نطاقات المفتاح أنشئ مفتاحًا جديدًا وألغِ القديم.

عند تغيير خطتك

ما يمكن للمفتاح فعله هو تقاطع صلاحياته مع ما تسمح به الخطة الحالية؛ ويُتحقق من ذلك عند كل طلب.

من Enterprise إلى Pro أو Free. تستمر المفاتيح القائمة بالعمل. يحتفظ مفتاح vendor بالنطاق في إعداداته المحفوظة لكن يتوقف تطبيقه؛ فلا تعود الإجابات تستند إلى بيانات مؤسستك، ولا يظهر خطأ، بل تعتمد على المعرفة العامة. تنتهي جلسات المتصفح المصدرة قبل التغيير: يعيد طلبها التالي 401، ويحصل SDK على جلسة جديدة وفق الخطة الجديدة. في Pro يُنتج تدوير هذا المفتاح بديلًا من دون vendor مع بقاء النطاقات الأخرى وقائمة المنتجات. ويُرفض رفع البيانات التجارية الجديدة مع 403 vendor_data_not_on_plan، بينما يمكن للمالكين والمسؤولين عرض الإصدارات المرفوعة وإلغاء نشرها وحذفها.

الانتقال إلى Free. لا تستطيع مؤسسة Free إنشاء مفاتيح خادم جديدة أو تدوير مفاتيح خادم أو مفاتيح قديمة تملكها، إذ يُرفض ذلك مع 403 free_plan_publishable_only. ويُنتج تدوير مفتاح قابل للنشر في Free بديلًا يضم جميع إمكانات Free (ai وmaps وdesign والمنتجات الأربعة) بغض النظر عن إعدادات القديم. تبقى مجموعات البيانات الموجودة على خرائط Studio، لكن الرفع الجديد يخضع لحدود مجموعات البيانات في Free. تنتهي جلسات المتصفح السابقة بالطريقة نفسها ويحصل SDK على جلسات أخرى.

عند العودة إلى خطة أعلى تعود الإمكانات المسموح بها. ويستعيد مفتاح ما زال يخزّن vendor حق الوصول إلى البيانات عند العودة إلى Enterprise. أما المفتاح الذي دُوّر في خطة أدنى فلا يستعيد هذا النطاق؛ أنشئ مفتاحًا جديدًا.

إنشاء مفتاح

يجب أن تكون مالكًا أو مسؤولًا في مؤسستك.

سجّل الدخول إلى kaleidr.com وافتح kaleidr.com/api-keys. تعرض الصفحة مفاتيح مؤسستك تحت Your API Keys.
اختر Create Key لتفتح نافذة Create a Key التي تحتوي ثلاثة حقول.
Key Name. أدخل اسمًا مثل Production site. لا يراه الزوار. سمّ المفاتيح بحسب موقع استخدامها حتى تميزها عند الإلغاء.
Key Type. اختر Browser / Embed Key (قابل للنشر) أو Server Key. خيار Server Key غير ظاهر في خطة Free، ولا يمكن تغيير النوع لاحقًا.
Allowed Origins. للمفتاح القابل للنشر، أدخل المواقع المسموح لها باستخدامه مفصولة بفواصل، مثل https://www.example.com, https://app.example.com. اترك الحقل فارغًا للسماح بجميع المواقع. راجع الأصول المسموح بها للتنسيق. لا يرتبط مفتاح الخادم بموقع، لذا اترك الحقل فارغًا.
اختر Create Key.
انسخ المفتاح الآن. تعرض النافذة قيمة المفتاح الكاملة مرة واحدة مع التحذير «Copy this key now — it won't be shown again.» اختر Copy واحفظ المفتاح بأمان ثم Done. لا يحتفظ Kaleidr بالقيمة الكاملة؛ وإذا فقدتها فدوّر المفتاح للحصول على قيمة جديدة.

النتيجة المتوقعة: يظهر المفتاح الجديد في الجدول مع بدايته تحت Key واسمه ونوعه (Browser أو Server) وحالته Active وتاريخ اليوم.

إذا ظهرت رسالة "You must be an organization admin to manage API keys." فاطلب من مالك أو مسؤول إنشاء المفتاح أو تغيير دورك.

المصادر المسموح بها

الأصول المسموح بها هي المواقع التي يعمل منها المفتاح القابل للنشر. عند مبادلة المفتاح بجلسة، يرسل المتصفح أصل الصفحة في الترويسة Origin ويقارنه Kaleidr بالقائمة.

القائمة الفارغة تسمح لجميع المواقع. وهي مريحة أثناء التطوير، لكن من ينسخ المفتاح من مصدر صفحتك يستطيع استخدامه على موقعه وإنفاق حصتك. ضع قائمة لكل مفتاح إنتاجي.
القائمة ذات المدخل الواحد أو أكثر تسمح فقط بالأصول المحددة. المطابقة دقيقة: لا يغطي https://example.com العنوان https://www.example.com، ولا يغطي http://localhost:3000 العنوان http://localhost:5173. أدرج كل عنوان على حدة.

يتكون الأصل من البروتوكول والمضيف ومنفذ اختياري من دون مسار:

القيمة	مقبولة
`https://www.example.com`	نعم
`https://app.example.com:8443`	نعم
`http://localhost:8000`	نعم. يُقبل `http` لـ`localhost` و`127.0.0.1` فقط. ويمكن إعداد `http://[::1]` عبر واجهة إدارة المفاتيح، لا من هذه الصفحة.
`http://www.example.com`	لا. يجب أن تستخدم المواقع غير المحلية `https`.
`https://www.example.com/store`	لا. لا يحتوي الأصل على مسار.
`*.example.com`	لا. لا تُدعم أحرف البدل. يُحفظ `https://*.example.com` كما هو ولا يطابق أي موقع.

يحتوي المفتاح على 100 أصل كحد أقصى.

لتعديل القائمة، اختر إجراء التحرير (القلم) في صف المفتاح. غيّر Allowed Origins في نافذة Edit Key ثم اختر Save changes. ويمكنك أيضًا تغيير اسم المفتاح من النافذة نفسها.

تسري إضافة أصل على الجلسات الجديدة الصادرة من ذلك الموقع.
تؤدي إزالة الأصل إلى إيقاف الموقع. وتفشل الجلسات الصادرة سابقًا للصفحات من ذلك الأصل في الطلب التالي مع 401 Invalid or missing API key بدل الاستمرار حتى انتهاء صلاحيتها.

ما يحدث للموقع المحظور. إذا حاولت صفحة من أصل غير مدرج تركيب منتج، تُرفض مبادلة الجلسة مع 403 origin_not_allowed. ولا يتضمن الرد ترويسات CORS؛ فيُظهر المتصفح خطأ CORS عند الطلب إلى …/b2b/v1/sdk/sessions، ويسجل SDK خطأ [kaleidr:<product>] ولا يظهر شيء. تجد النص الدقيق في استكشاف الأخطاء.

تقيد قائمة الأصول المواقع التي يعمل منها المفتاح في المتصفح، لكنها لا تجعله سرًا: يمكن لأي عميل خارج المتصفح إرسال قيمة Origin التي يختارها. يوضح نموذج الأمان ما تحميه القائمة وما لا تحميه، وتوضح CORS والأصول المسموح بها تفاصيل الطلبات.

تدوير المفاتيح وإلغاؤها

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

دوّر المفتاح عند مغادرة شخص كان لديه وصول إليه، أو حسب الجدول الذي تحدده سياسة الأمان. أما إذا تسرّب فقم بإلغائه: فالتدوير من هذه الصفحة يبقي القيمة القديمة صالحة 24 ساعة.

ألغِ المفتاح لإيقافه فورًا. اختر إجراء الحذف (سلة المهملات) في صفه وأكّد. تعرض الصفحة التحذير «Revoke this API key? Any site using it will stop working immediately.» يُنهي الإلغاء أيضًا جميع الجلسات الصادرة من المفتاح، لذا تفشل الصفحات المفتوحة عند طلبها التالي. ولا يمكن استعادة المفتاح الملغى.

عند تسرب مفتاح خادم، ألغِه بدل تدويره، لأن فترة السماح البالغة 24 ساعة ستبقي قيمته المتسربة صالحة.

مفاتيح الاختبار

لكل نوع نسخة للاختبار: kld_pk_test_… وkld_sk_test_….

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

ميزة مفتاح الاختبار هي الفصل؛ إذ يرتبط مرور موقع التجارب بمفتاح مستقل يمكنك إلغاؤه دون التأثير على الإنتاج. لا تعتبر مرور الاختبار مجانيًا.

تنشئ صفحة API Keys مفاتيح مباشرة فقط. لإنشاء مفتاح اختبار استخدم واجهة المفاتيح مع "environment": "test".

خيارات غير متاحة من صفحة المفاتيح

تتيح صفحة API Keys ضبط اسم المفتاح ونوعه وأصوله المسموح بها. وتتوفر إعدادات أخرى عبر واجهة المفاتيح في https://api.kaleidr.com/shared-api/api-keys.

تصادق واجهة المفاتيح على هويتك أنت لا على مفتاح: أرسل رمز وصول مالك المؤسسة أو مسؤولها المسجل دخوله باستخدام Authorization: Bearer. ولا يستطيع مفتاح API إنشاء المفاتيح أو تغييرها.

الحقل	النوع	الافتراضي	الوظيفة
`name`	سلسلة من 1 إلى 200 حرف	مطلوب	تسمية المفتاح.
`org_id`	UUID	مؤسستك الأساسية	المؤسسة التي يُنشأ المفتاح فيها. أرسله في جسم الطلب؛ يُتجاهل معامل الاستعلام `org_id` عند الإنشاء.
`key_type`	`"publishable"` أو `"server"`	`"publishable"`	نوع المفتاح، ثابت بعد الإنشاء.
`environment`	`"live"` أو `"test"`	`"live"`	ينشئ مفتاحًا مباشرًا أو مفتاح اختبار، ثابت بعد الإنشاء.
`scopes`	مصفوفة سلاسل	`["ai", "maps", "design"]`	نطاقات المفتاح، ثابتة بعد الإنشاء.
`vendor_acknowledged`	قيمة منطقية	`false`	يجب أن تكون `true` لإنشاء مفتاح قابل للنشر يحمل `vendor`.
`allowed_origins`	مصفوفة سلاسل حتى 100	`[]`	الأصول المسموح بها، للمفاتيح القابلة للنشر فقط.
`allowed_products`	مصفوفة سلاسل	`[]` (كل المنتجات)	يحد المفتاح ببعض `chat` و`editor` و`viewer` و`tile`، ويشمل كل أنواع المفاتيح؛ راجع الملاحظة أدناه.
`allowed_ips`	مصفوفة سلاسل حتى 100	`[]` (أي عنوان)	عناوين IP أو نطاقات CIDR التي يُسمح لها باستخدام مفتاح الخادم.
`monthly_cap_tokens`	عدد صحيح من 0 فأكثر	لا يوجد	أقصى أرصدة ذكاء اصطناعي يمكن للمفتاح استهلاكها في دورة فوترة. 1 فأكثر يضع حدًا، و`0` أو `null` يعني بلا حد.
`expires_at`	تاريخ ووقت مستقبليان	لا يوجد	وقت توقف المفتاح عن العمل.

في Free تُضبط scopes وallowed_products دائمًا على كل ما تسمح به الخطة (ai وmaps وdesign؛ chat وeditor وviewer وtile) بغض النظر عن القيم في الطلب، وينطبق ذلك على تدوير المفتاح في Free. وفي جميع الخطط يُرفض طلب نطاق أو منتج لا تسمح به الخطة مع 403 tier_capability_not_allowed ولا يُحذف أي جزء بصمت.

تسري قيود المنتجات أينما استُخدم المفتاح. إذا حاول مفتاح قابل للنشر محصور بمنتجات محددة تركيب منتج آخر، تُرفض مبادلة الجلسة مع 403 product_not_allowed. وكذلك تُرفض كل مكالمة من مفتاح خادم أو مفتاح قديم مقيد إلى نقطة نهاية تخص منتجًا آخر مع 403 product_not_allowed. تنتمي نقاط نهاية الدردشة والأماكن والترميز الجغرافي إلى chat، ونقاط التصميم إلى editor. لكي يستطيع مفتاح خادم استدعاء كل نقاط النهاية التي تسمح بها نطاقاته، اترك allowed_products فارغة. جدول الربط في المصادقة والنطاقات.

ينشئ هذا الطلب مفتاح اختبار قابلًا للنشر محصورًا في Chat على موقع تجريبي واحد:

curl -X POST https://api.kaleidr.com/shared-api/api-keys \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Staging site chat",
    "key_type": "publishable",
    "environment": "test",
    "allowed_origins": ["https://staging.example.com"],
    "allowed_products": ["chat"]
  }'

يتضمن رد 201 إعدادات المفتاح وقيمته الكاملة مرة واحدة فقط في plaintext_key:

{
  "id": "5f0c2a9e-…",
  "name": "Staging site chat",
  "key_prefix": "kld_pk_test_…",
  "key_type": "publishable",
  "environment": "test",
  "scopes": ["ai", "maps", "design"],
  "allowed_origins": ["https://staging.example.com"],
  "allowed_products": ["chat"],
  "allowed_ips": [],
  "monthly_cap_tokens": null,
  "status": "active",
  "expires_at": null,
  "plaintext_key": "kld_pk_test_…"
}

مفتاح يمكنه قراءة بيانات أعمالك

يتيح نطاق vendor لإجابات Chat الاستناد إلى البيانات التجارية التي نشرتها مؤسستك. كل من رفع تلك البيانات وحمل نطاق قراءتها بالمفتاح متاحان لـEnterprise فقط، ولا يُمنح النطاق إلا عبر واجهة المفاتيح:

curl -X POST https://api.kaleidr.com/shared-api/api-keys \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Site chat with our data",
    "key_type": "publishable",
    "scopes": ["ai", "vendor"],
    "vendor_acknowledged": true,
    "allowed_origins": ["https://www.example.com"]
  }'

يوجد vendor_acknowledged لأن المفتاح القابل للنشر يظهر في مصدر صفحتك: يستطيع أي زائر سؤال Chat، وقد تتضمن الإجابات بياناتك المرفوعة. يؤدي ضبط الحقل على true إلى تسجيل قصدك السماح بذلك.

يُرفض المفتاح القابل للنشر الذي يطلب vendor دون "vendor_acknowledged": true بالحالة 422 vendor_scope_requires_acknowledgement.
لا يحتاج مفتاح الخادم إلى إقرار.
في Free وPro يُرفض أي طلب يتضمن vendor بالحالة 403 tier_capability_not_allowed سواء أُرسل vendor_acknowledged أم لا، ولا يُنشأ مفتاح.

تشرح بياناتك رفع البيانات والتحقق من استخدامها في الإجابات.

يقبل تعديل المفتاح (PATCH /shared-api/api-keys/{id}) الحقول name وallowed_origins وallowed_products وallowed_ips وmonthly_cap_tokens وexpires_at. ويقبل التدوير (POST /shared-api/api-keys/{id}/rotate) قيمة grace_hours من 0 إلى 8760؛ والافتراضي 0 يوقف المفتاح القديم فورًا. يتم الإلغاء عبر POST /shared-api/api-keys/{id}/revoke. رموز الرفض موضحة في الأخطاء.

شرطان أساسيان لكل تضمين

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

1. تقديم الصفحة من مصدر يسمح به المفتاح

قدّم الصفحة عبر HTTP أو HTTPS حتى أثناء التطوير. الملف المفتوح من القرص (file://) لا يملك أصلًا يمكن إضافته إلى قائمة المفتاح.
إن حدد المفتاح أصولًا مسموحًا بها، يجب إدراج أصل صفحتك حرفيًا بما يشمل البروتوكول والمضيف والمنفذ. في التطوير المحلي عادةً ما تضيف http://localhost:<port>.

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

2. سماح سياسة أمان المحتوى بتحميل المنتج

إذا أرسل موقعك ترويسة Content-Security-Policy فعليها أن تسمح بمضيفي Kaleidr الذين تستخدمهم المنتجات. أما إذا لم يرسلها فلا حاجة لإعداد شيء.

المنتج	ما يجب أن تسمح به السياسة
Viewer وTile	نصوص من `https://cdn.kaleidr.com` وإطار من `https://map-embed.kaleidr.com`، واتصال إلى `https://api.kaleidr.com` عند التركيب باستخدام مفتاح
Chat وEditor	نصوص من `https://cdn.kaleidr.com` واتصالات إلى `https://api.kaleidr.com` وأنماط مضمنة، لأن المنتجين يضيفان أنماطًا إلى الصفحة. ويحمّل Editor خريطته الأساسية من `https://tile.kaleidr.com`.

تشرح سياسة أمن المحتوى التعليمات الكاملة المطلوبة لكل منتج.

عند الخطأ يسجل المتصفح Refused to load… أو Refused to connect… موضحًا العنوان والتعليمة التي تسببت بالمنع.

استخدام المفتاح

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

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

النتيجة المتوقعة: تظهر الخريطة الأساسية وتعرض علامة Network ردًا 200 من https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions. يتضمن البدء السريع صفحة مكتملة لكل منتج.

من الخادم أرسل مفتاح الخادم في كل طلب. يسرد هذا الاستدعاء أنماط الخرائط التي تعرفها نقاط نهاية التصميم، دون استهلاك أرصدة ذكاء اصطناعي، وهو اختبار أول جيد للمفتاح.

curl https://api.kaleidr.com/inference-api/b2b/v1/design/styles \
  -H "Authorization: Bearer kld_sk_live_…"

النتيجة المتوقعة: رد 200 وكائن JSON يتضمن مصفوفة styles. وتعني 401 مع {"detail":"Invalid or missing API key"} أن المفتاح خاطئ أو ملغى. أما 403 مع {"detail":"server_key_in_browser"} فتعني أن الطلب حمل ترويسة Origin؛ احذفها. تابع في البدء السريع للخادم.

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

البدء السريع: صفحة عاملة لكل من Chat وViewer وTile.
آلية عمل Kaleidr: الجلسات والمؤسسات وحصتا الاستخدام.
المصادقة والنطاقات: كيفية إرسال بيانات الاعتماد وفحصها.
قائمة مراجعة الإنتاج: مفتاح لكل موقع والأصول المسموح بها وبقية التحضيرات قبل الإطلاق.

نوعا المفاتيح​

ما تسمح به كل خطة​

نطاقات الصلاحيات​

عند تغيير خطتك​

إنشاء مفتاح​

المصادر المسموح بها​

تدوير المفاتيح وإلغاؤها​

مفاتيح الاختبار​

خيارات غير متاحة من صفحة المفاتيح​

مفتاح يمكنه قراءة بيانات أعمالك​

شرطان أساسيان لكل تضمين​

1. تقديم الصفحة من مصدر يسمح به المفتاح​

2. سماح سياسة أمان المحتوى بتحميل المنتج​

استخدام المفتاح​

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