سواء كنت تطلق متجراّ إلكترونياً غنياً بالميزات، تطور تجربة افتراضية، أو تبني محرك ذكاء اصطناعي قابل للتوسع، فإن البنية المصممة للمطورين لدينا تسهل عليك عملية الدمج، التخصيص، والنشر لأدوات الذكاء الاصطناعي والواقع المعزز داخل بنيتك الرقمية.
نوفر لك حلولاً مرنة ومقسمة إلى وحدات يمكن ربطها مباشرة ببنيتك التحتية، دون الحاجة إلى مجهود كبير.
واجهات RESTful API و Webhooks
حزم SDK جاهزة للويب والموبايل
كود نظيف وموثق بشكل احترافي
دعم تقني كامل وأدلة تكامل شاملة
منصتنا مصممة لتتناسب مع بيئتك. نعمل بسلاسة عبر جميع الأطر وأنظمة إدارة المحتوى من شوبيفاي وماجنتو إلى الأنظمة المخصصة.
لا تعتمد على واجهات أمامية معينة
جاهزة للهيكلة الرأسية (Headless)
خيارات سهلة للإضافات في أنظمة CMS والمتاجر الإلكترونية
1
4
خادمك يوقّع client_assertion بمفتاحك الخاص ES256 ويرسله إلى /api/token، فيستلم access_token قصير العمر (5 دقائق). تُمرّر هذا الرمز إلى واجهتك الأمامية، التي تُلصقه على وسم <script> الخاص بالـ SDK كـ ?sessionToken=…. يقرأ الـ SDK هذا الرمز من عنوان السكربت ويرفقه كـ Authorization: Bearer لكل طلب نوڤاجيتس.
احفظها على الخادم فقط
آمن للإرسال إلى المتصفح
أعد جلب رمز جديد من خادمك قبل انتهاء الخمس دقائق. لا تُرسل المفتاح الخاص ولا client_assertion إلى المتصفح أبداً.
التثبيت
# Requires bash, curl, jq.# Pre-sign client_assertion with one of the language tabs below.
التنفيذ
CLIENT_ASSERTION="$(node ./scripts/sign-client-assertion.js)"curl -sS -X POST https://novagates.com/api/token \-H 'Content-Type: application/json' \-d "{\"client_assertion\": \"${CLIENT_ASSERTION}\",\"client_assertion_type\": \"urn:ietf:params:oauth:client-assertion-type:jwt-bearer\"}" | jq -r .access_token
POST /api/token — مخطط الطلب والاستجابة
النقطة الوحيدة التي يستدعيها خادمك مباشرةً. كل ما عداها يستدعيه الـ SDK نيابةً عنك باستخدام sessionToken الذي حقنته في وسم <script>.
الطلب
POST · application/json أو application/x-www-form-urlencoded
client_assertion (مطلوب) — JWT موقّع بـ ES256، الترويسة تحوي jwk عام، الحمولة iss=sub=apiKey و aud=https://novagates.com/api/token (مطابقة تامة) مع jti فريد.client_assertion_type (مطلوب) — ثابت: urn:ietf:params:oauth:client-assertion-type:jwt-bearerdpop_jkt (اختياري) — بصمة base64url بطول 42–44 حرفاً لمفتاح متصفح مؤقت لربط الرمز به.الاستجابة
200 OK · application/json
access_token — JWT موقّع بـ HS256؛ المطالبات: sub=apiKey، cnf.jkt=البصمة المربوطة، iss=novagates، jti فريد.token_type — "Bearer"expires_in — 300 (5 دقائق)أخطاء: 400 لمدخلات غير صالحة، 401 إذا لم يطابق jkt الترويسة بصمة apiKey المخزّنة، أو كانت aud مفقودة أو لا تطابق عنوان /api/token تماماً، أو تم استخدام jti سابقاً.
تتم تهيئة الـ SDK ببساطة عبر تضمين sessionToken في وسم <script>. واجهتك الأمامية تجلب الرمز من خادمك (الذي يستدعي /api/token)، ثم تحقن وسم سكربت الـ SDK مع ?sessionToken=… و?module=…، ويبدأ الـ SDK تلقائياً ويُرفق هذا الرمز كـ Bearer لكل طلب نوڤاجيتس.
تدفق التهيئة
التنفيذ
<!doctype html><html lang="en"><head><meta charset="utf-8" /><title>Novagates Virtual Try-On</title></head><body><div id="novagates-root"></div><script>(async function bootNovagates() {// 1. Mint a short-lived sessionToken on YOUR backend.const res = await fetch("/api/sdk-token", { credentials: "include" });if (!res.ok) throw new Error("Failed to fetch SDK session token");const { sessionToken } = await res.json();// 2. Inject the SDK loader with sessionToken + module on the URL.const params = new URLSearchParams({sessionToken: sessionToken,module: "virtual-try-on",});const script = document.createElement("script");script.src ="https://cdn.novagates.com/sdk/novagates-sdk.js?" + params.toString();script.async = true;script.onload = function () {// 3. Init once the loader has registered the global.window.Novagates.init({rootId: "novagates-root",productsSource: "/api/products.json",immediate: true,});};document.body.appendChild(script);})();// 4. Listen for product events emitted by the SDK.window.addEventListener("sdk:addToCart", function (e) {console.log("[novagates] add to cart", e.detail);// forward to your cart, analytics, etc.});</script></body></html>
يعمل الـ SDK داخل صفحتك أنت، ولذلك يخضع لسياسة أمان المحتوى الخاصة بموقعك لا بسياستنا. إن كان لديك CSP صارمة فأضف التوجيهات التالية قبل التفعيل، وإلا فسيتعطل الـ SDK بطرق يصعب تشخيصها من الخارج: إطار أسود، أو خطأ CompileError صادر من داخل حزمة مصغّرة.
إطار srcdoc لا يعزلك عن سياستك
يُشغّل الـ SDK داخل إطار من نوع about:srcdoc، وهذا النوع من الإطارات لا يملك عنوان URL تُشتق منه سياسة، فيرث سياسة المستند المُضمّن ويرث أصله كذلك. من يفترض أن الإطار يعزل الـ SDK عن سياسته سيكون مخطئاً، وهذا هو سوء الفهم الأشيع في هذا الموضوع.
| التوجيه | المصادر المسموح بها | السبب |
|---|---|---|
script-src | 'self' https://cdn.novagates.com | المُحمِّل وحزم الوحدات وملف ONNX Runtime بصيغة .mjs تُحمّل جميعها عبر وسم script من الـ CDN. |
script-src | 'wasm-unsafe-eval' | تستدعي MediaPipe و ONNX Runtime و TFLite جميعها WebAssembly.compile / instantiate، وهي محكومة بسياسة CSP. بدون هذا التصريح يُحمّل الـ SDK ثم يفشل من الداخل برسالة CompileError دون أي إشارة إلى مورد محجوب، وهو أصعب أنواع الأعطال في التشخيص. التصريح 'unsafe-eval' يعمل أيضاً لكنه أوسع بكثير ولا يُنصح به. |
connect-src | 'self' blob: https://cdn.novagates.com | تُجلب أوزان النماذج (.nova) وملفات MediaPipe بصيغة .task وبيئات التشغيل .wasm وأصول المشاهد .glb و .hdr إضافةً إلى بيانات التصنيفات. كما تُفكّك أوزان TFLite إلى Blob ويُعاد جلبها عبر عنوان كائن، ولهذا يلزم blob: هنا أيضاً. |
worker-src | 'self' blob: https://cdn.novagates.com | عامل الاستدلال مُضمّن داخلياً ويُنشأ من عنوان blob:. عند حذف هذا التوجيه فإنه لا يعود إلى default-src مباشرةً — بل يمر عبر child-src ثم script-src ثم default-src — فيرث ما يسمح به script-src ضمنياً. المنع نفسه يظهر في الـ console وفي تقرير المخالفة؛ الصامت هو تراجع الـ SDK إلى الاستدلال على الخيط الرئيسي، فتستمر الصفحة في العمل وتغدو أبطأ فحسب. |
media-src | 'self' blob: data: | يُشغّل الفيديو المرفوع والمسجّل والصوت المولّد عبر URL.createObjectURL. أما مسار الكاميرا المباشرة فيستخدم srcObject الذي لا تحكمه سياسة CSP، لذا تستمر التجربة عبر الكاميرا في العمل بينما تتعطل التجربة عبر الرفع، وهي طريقة مربكة لاكتشاف المشكلة. |
style-src | 'self' 'unsafe-inline' | يُرسم الـ SDK داخل صفحتك ويطبّق أنماطه مباشرةً. في غياب style-src يعود الأمر إلى default-src، فتظهر واجهة التجربة بلا تنسيق بدل أن تُحجب — خلل مرئي دون أي خطأ. هذه هي القيمة التي يقدّمها موقعنا نفسه، في وضع Report-Only، وهو يشغّل الـ SDK ذاته، وهو التوجيه الوحيد هنا الذي يمثّل تخفيفاً حقيقياً لسياستك: فـ 'unsafe-inline' على style-src يسمح بأي CSS محقون في صفحاتك، فتأكّد أنك تريده فعلاً بدل نسخه كما هو. ويمكن استخدام nonce أو hash للأنماط أيضاً إن فضّلت، مقابل التنسيق مع كل إصدار من الـ SDK؛ إن كانت سياستك أضيق فاختبرها في وضع Report-Only قبل الترقية. |
font-src | 'self' data: | خطوط الأيقونات والواجهة التي يضمّنها الـ SDK بصيغة data:. عند حذفه يعود الأمر إلى default-src فتسقط إلى خط المتصفح الافتراضي — خلل مرئي لا خطأ مرفوع. |
img-src | 'self' data: blob: https://cdn.novagates.com | اللقطات التي ينتجها الـ SDK من الـ canvas بصيغتَي data: و blob:، إضافةً إلى أصول الصور التي يحمّلها من الأصل الذي يُقدَّم منه هو نفسه. أمّا صور منتجاتك فليست مشمولة هنا: فهي تأتي من الأصل الذي يشير إليه كتالوجك، فأضف ذلك الأصل بنفسك. وهذا هو الصف الوحيد غير المشتق من سياسة موقعنا الوسيطة: فذلك الملف يسمح بالأصل نفسه في img-src لسبب مختلف تماماً، إذ يشاركه CDN الوسائط التسويقية، فهو يعزّز هذا الصف ولا يثبته. وإن فضّلت عدم منحه فاحذفه وراقب تقارير Report-Only. |
سكربت الإقلاع أعلاه مُضمَّن — امنحه nonce
مقطع Vanilla JS في قسم التكامل أعلاه يضع دالة الإقلاع داخل وسم script مُضمَّن في صفحتك. مع سياسة script-src صارمة يُحجب هذا الوسم ولا يُحمَّل الـ SDK إطلاقاً — وهذا أول ما يقع فيه من ينسخ المقطع والسياسة معاً. أضف nonce تُولّده لكل طلب على الوسم وفي الترويسة معاً، أو انقل الدالة إلى ملف يغطّيه 'self'. لا تلجأ إلى 'unsafe-inline': فهي تفتح كل سكربت مُضمَّن في موقعك، وهو ثمن أكبر بكثير ممّا يلزم. وانتبه إلى أثر الـ nonce على سياستك القائمة، ففي CSP الإصدار الثالث، وجود nonce أو hash داخل script-src يجعل 'unsafe-inline' في التوجيه نفسه مُهمَلاً. إن كنت تقدّم اليوم script-src 'self' 'unsafe-inline' ثم أضفت هذا الـ nonce، تتوقف كل السكربتات المُضمَّنة الأخرى في متجرك عن العمل على مستوى الموقع بأكمله. فأضف nonce لجميعها في التغيير نفسه، أو انقل هذه الدالة إلى ملف مستقل.
# THESE ARE THE SDK'S DIRECTIVES, NOT A COMPLETE POLICY. Merge each source# expression into the directive you already serve - pasting this block as your# whole CSP replaces yours and breaks the rest of your site.## NOTE on the nonce: a script-src that contains a nonce makes 'unsafe-inline'# in that same directive IGNORED (CSP Level 3). If you serve 'unsafe-inline'# today, nonce your other inline scripts in the same change or they stop# running.## Roll it out FIRST in Report-Only, with a collector at /csp-report, and read# the reports before you promote. Shown wrapped for readability - send it as# ONE header line; HTTP header folding is obsolete and proxies will not# reassemble it.add_header Content-Security-Policy-Report-Only "script-src 'self' 'wasm-unsafe-eval' https://cdn.novagates.com 'nonce-<PER-REQUEST>';connect-src 'self' blob: https://cdn.novagates.com;worker-src 'self' blob: https://cdn.novagates.com;style-src 'self' 'unsafe-inline';font-src 'self' data:;media-src 'self' blob: data:;img-src 'self' data: blob: https://cdn.novagates.com;report-uri /csp-report;report-to csp-endpoint" always;# report-to needs this companion header to bind the group name to a URL.add_header Reporting-Endpoints 'csp-endpoint="https://your-site.example/csp-report"' always;
تحقّق من connect-src إن كان تكاملك يستدعي واجهة REST من المتصفّح مباشرةً. القيم أعلاه تغطّي ما يجلبه الـ SDK من الـ CDN ومن أصلك أنت؛ أمّا تبادل الرموز عبر novagates.com فيجري من خادمك ولا تحكمه سياسة CSP أصلاً. إن أضفت أنت استدعاءً من المتصفّح إلى تلك الواجهة، فأضف أصلها إلى connect-src أيضاً.
ابدأ بوضع Report-Only ثم رقِّها
انشر السياسة أولاً عبر ترويسة Content-Security-Policy-Report-Only مع نقطة تجميع للبلاغات، واتركها دورة مرور كاملة قبل التحويل إلى الوضع الملزِم. هذا هو الترتيب نفسه الذي نلتزم به على موقعنا.
أعلن report-uri و report-to معاً
report-uri مهجور في المواصفة لكنه الوحيد الذي تدعمه Firefox و Safari، بينما تتجاهله Chrome و Edge كلياً متى وُجد report-to. الاكتفاء بأحدهما لا يجمع شيئاً من عائلة متصفحات كاملة، وهو ما يبدو تماماً كأنه غياب المخالفات.
لا حاجة لإضافة أصل الـ SDK إلى frame-src: الإطار من نوع about:srcdoc ولا يحكمه هذا التوجيه لأنه يرث السياسة. لن يلزم ذلك إلا إذا انتقل الـ SDK مستقبلاً إلى عنوان حقيقي من أصل مختلف.
بالنسبة لمتاجر WordPress / WooCommerce و Magento و Shopify و OpenCart — قمنا بشحن الإضافة بالكامل. تتولّى توقيع client_assertion، وتبادل الرموز عبر /api/token، وتدوير sessionToken، وتزامن الكتالوج تلقائياً. تعليمات التنزيل والتثبيت متوفرة داخل لوحة التحكم الخاصة بك.
يستهلك الـ SDK كتالوج JSON يطابق هذا المخطط. يتم تحديد ميزات التجربة الافتراضية وتحليل الجلد والعرض ثلاثي الأبعاد بناءً على حقل `technologies`، بينما توجّه `product_types` و `category` تجربة المستخدم.
simple
SKU واحد، مجموعة سمات واحدة
configurable
SKU أب يكشف متغيرات (درجات/أحجام)
variable
متغيرات بأسعار مستقلة
// GET /api/products → Product[]//// Three product shapes, distinguished by `type_id`:// "simple" — single SKU, single set of attributes// "configurable" — parent SKU exposes child variants (size/shade swatches)// "variable" — parent SKU with priced variants (e.g. fragrance volumes)//// Every product family below extends this base. Required vs null fields// depend on the family — see the next tabs.interface Product {/* identity */id: number;uid: string;sku: string; // unique merchant SKUtype_id: "simple" | "configurable" | "variable";name: string;brand: string | null;manufacturer: string | null;country_of_manufacture: string | null;made_in: string | null;/* taxonomy */category: string; // e.g. "Women > Makeup > Face > Foundation"product_types: string; // see family tabsproduct_type_id: string; // your CMS taxonomy id/* commerce */url_key: string;url_path: string;price: { regularPrice: { amount: { currency: string; value: number } } };/* media */image: { url: string };swatch_image: { url: string };thumbnail: { url: string };small_image?: { url: string };/* try-on / 3D pipeline switch */is_product_try_on: 0 | 1;is_product_skin_improvement: 0 | 1;asset_url: string | null; // PNG texture, .glb, or null per familytechnologies: string; // pipe-separated; activates SDK modules/* configurable / variable parents */variants?: Array<{ product: Product }>;}
نوڤاجيتس ليست مجرد منصة بل شريك تقني حقيقي.
ندعم المطورين في كل خطوة، من خلال جلسات مع الخبراء، مستودعات كود مشتركة، ومجتمع تقني متنامٍ.