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

ابدأ

OneEntry Platform SDK هو SDK يوفر وسيلة سهلة للتفاعل مع واجهة برمجة تطبيقات OneEntry Platform.

الموقع الرسمي

قم بزيارة الموقع الرسمي لـ OneEntry على https://oneentry.cloud لمعرفة المزيد عن OneEntry Platform.

التسجيل

للبدء مع OneEntry، قم بالتسجيل للحصول على حساب على https://account.oneentry.cloud/authentication/register.

التثبيت

لتثبيت OneEntry Platform SDK في مشروعك، قم بتشغيل الأمر التالي:

npm install oneentry

لاستخدام OneEntry Platform SDK في مشروعك، استورد دالة defineOneEntry:

import { defineOneEntry } from 'oneentry'

const config = {
token: 'your-app-token',
}
const {
Admins,
AttributesSets,
AuthProvider,
Blocks,
Events,
Forms,
FormData,
FileUploading,
GeneralTypes,
IntegrationCollections,
Locales,
Menus,
Orders,
Pages,
Products,
ProductStatuses,
System,
Templates,
TemplatePreviews,
Users,
WS,
} = defineOneEntry('your-url', config)

أو

const config = {
token: 'your-app-token',
}
const api = defineOneEntry('your-url', config)

الإعدادات

المعلمة الثانية في المُنشئ تأخذ 'config'. تحتوي على القيم التالية:

  • 'token' - قم بتعيين مفتاح الرمز إذا كان مشروعك يتطلب "رمز أمان API". إذا كنت تستخدم حماية الشهادة، فلا تمرر هذه المتغير. يمكنك قراءة المزيد عن أمان مشروعك هنا.

  • 'langCode' - قم بتعيين "langCode" لتحديد اللغة الافتراضية. من خلال تحديد هذه المعلمة مرة واحدة، لن تحتاج إلى تمرير langCode إلى طرق واجهة برمجة تطبيقات ONEENTRY. إذا لم تحدد لغة افتراضية، فستكون القيمة الافتراضية "en_US".

  • 'traficLimit' - تستخدم بعض الطرق أكثر من طلب واحد إلى CMS لضمان أن البيانات التي تتلقاها كاملة وسهلة الاستخدام. قم بتعيين هذه المعلمة إلى "true" لتوفير حركة المرور وقرر بنفسك ما هي البيانات التي تحتاجها. القيمة الافتراضية هي "false".

  • 'auth' - كائن يحتوي على إعدادات التفويض. بشكل افتراضي، يتم تكوين SDK للعمل مع الرموز المخزنة في جلسة المستخدم ولا يتطلب أي عمل إضافي منك. ومع ذلك، لا يحتفظ SDK بحالة الجلسة بين الجلسات. إذا كنت راضيًا عن هذه الإعدادات، فلا تحتاج إلى تمرير متغير 'auth' على الإطلاق.

يحتوي كائن 'auth' على الإعدادات التالية:

  • 'refreshToken' - رمز التحديث الخاص بالمستخدم. قم بتمريره هنا من المستودع لاستعادة جلسة المستخدم أثناء التهيئة.

  • 'saveFunction' - دالة تتعامل مع تحديث رمز التحديث. إذا كنت ترغب في تخزين الرمز بين الجلسات، على سبيل المثال في التخزين المحلي، قدم دالة هنا تقوم بذلك. يجب أن تقبل الدالة معلمة سيتم تمرير السلسلة التي تحتوي على الرمز إليها.

  • 'customAuth' - إذا كنت ترغب في تكوين التفويض وإدارة الرموز بنفسك، قم بتعيين هذه العلامة إلى true. إذا كنت تفضل استخدام إعدادات SDK الافتراضية، قم بتعيينها إلى false أو تجاهلها تمامًا.

مثال على تكوين مع حماية الرمز والمصادقة التلقائية التي تحافظ على الحالة بين الجلسات:

const tokenFunction = (token) => {
localStorage.setItem('refreshToken', token)
}

const api = defineOneEntry('https://my-project.oneentry.cloud', {
token: 'my-token',
langCode: 'en_US',
auth: {
refreshToken: localStorage.getItem('refreshToken'),
saveFunction: tokenFunction,
},
})

مثال على تكوين محمي بشهادة يسمح لك بتكوين نظام التفويض بنفسك ويحفظ البيانات على الطلبات:

const api = defineOneEntry('https://my-project.oneentry.cloud', {
langCode: 'en_US',
traficLimit: true,
auth: {
customAuth: true,
refreshToken: localStorage.getItem('refreshToken'),
},
})

إذا اخترت إدارة الرموز بنفسك، يمكنك تمرير الرمز إلى الطريقة كما يلي. تتيح لك الطريقة الوسيطة تمرير رمز الوصول إلى الطلب. ثم استدعِ الطريقة المطلوبة. يجب عدم استدعاء هذه الطريقة (setAccessToken) إذا كانت الطريقة لا تتطلب تفويض المستخدم.

const user = api.Users.setAccessToken('my.access.token').getUser()

إذا اخترت حماية الرمز لضمان أمان الاتصال، ما عليك سوى تمرير الرمز الخاص بك إلى الدالة كمعلمة اختيارية.

يمكنك الحصول على رمز كما يلي:

  1. قم بتسجيل الدخول إلى حسابك الشخصي.
  2. انتقل إلى علامة التبويب "المشاريع" واختر مشروعًا.
  3. انتقل إلى علامة التبويب "الوصول".
  4. قم بتبديل المفتاح إلى "رمز أمان API".
  5. قم بتسجيل الدخول إلى المشروع، وانتقل إلى قسم الإعدادات، وافتح علامة التبويب الخاصة بالرمز.
  6. استرجع ونسخ رمز مشروعك.

يمكنك أيضًا توصيل شهادة TLS لحماية مشروعك. في هذه الحالة، لا تمرر "token" على الإطلاق. عند استخدام الشهادة، قم بإعداد وكيل في مشروعك. مرر سلسلة فارغة كمعلمة URL. تعرف على المزيد حول الأمان

const saveTokenFromLocalStorage = (token) => {
localStorage.setItem('refreshToken', token)
}

const api = defineOneEntry('your-url', {
token: 'my-token',
langCode: 'my-langCode',
auth: {
customAuth: false,
userToken: 'refresh.token',
saveFunction: saveTokenFromLocalStorage,
},
})

الأخطاء

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

ومع ذلك، إذا كنت تفضل استخدام بناء "try catch(e) ", قم بتعيين خاصية "isShell" إلى "false". في هذه الحالة، ستحتاج إلى التعامل مع الخطأ باستخدام "try catch(e) ".

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

const api = defineOneEntry('your-url', {
token: 'my-token',
langCode: 'my-langCode',
errors: {
isShell: false,
customErrors: {
400: (error) => console.error(error.message),
404: (error) => console.error(error.message),
500: (error) => console.error(error.message),
},
},
})