Перейти к основному содержимому

Начало работы

OneEntry Platform SDK — это SDK, который предоставляет простой способ взаимодействия с API платформы OneEntry.

Официальный сайт​

Посетите официальный сайт OneEntry по адресу https://oneentry.cloud, чтобы узнать больше о платформе OneEntry.

Регистрация​

Чтобы начать работу с OneEntry, зарегистрируйте учетную запись на https://account.oneentry.cloud/authentication/register.

Установка​

Чтобы установить OneEntry Platform SDK в ваш проект, выполните следующую команду:

npm install oneentry

Чтобы использовать OneEntry Platform SDK в вашем проекте, импортируйте функцию defineOneEntry:

import { defineOneEntry } from 'oneentry'

const config = {
    token: 'ваш-токен-приложения',
}
const {
    Admins,
    AttributesSets,
    AuthProvider,
    Blocks,
    Events,
    Forms,
    FormData,
    FileUploading,
    GeneralTypes,
    IntegrationCollections,
    Locales,
    Menus,
    Orders,
    Pages,
    Products,
    ProductStatuses,
    System,
    Templates,
    TemplatePreviews,
    Users,
    WS,
} = defineOneEntry('ваш-url', config)

Или

const config = {
    token: 'ваш-токен-приложения',
}
const api = defineOneEntry('ваш-url', config)

Конфигурация​

Второй параметр конструктора принимает 'config'. Он содержит следующие значения:

  • 'token' - Установите ключ токена, если ваш проект защищен "Security API Token". Если вы используете защиту сертификатом, не передавайте эту переменную. Вы можете узнать больше о безопасности вашего проекта здесь.

  • 'langCode' - Установите "langCode", чтобы задать язык по умолчанию. Указав этот параметр один раз, вам не нужно передавать langCode в методы API 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. Установите переключатель на "Security API Token"
  5. Войдите в проект, перейдите в раздел настроек и откройте вкладку токена
  6. Получите и скопируйте токен вашего проекта

Вы также можете подключить сертификат tls для защиты вашего проекта. В этом случае не передавайте "token" вообще. При использовании сертификата настройте прокси в вашем проекте. Передайте пустую строку в качестве параметра url. Узнайте больше о безопасности

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

const api = defineOneEntry('ваш-url', {
    token: 'my-token',
    langCode: 'my-langCode',
    auth: {
        customAuth: false,
        userToken: 'rerfesh.token',
        saveFunction: saveTokenFromLocalStorage,
    },
})

Ошибки​

Если вы хотите избежать ошибок внутри sc, оставьте свойство "errors" по умолчанию. В этом случае вы получите либо данные сущности, либо объект ошибки. Вам нужно выполнить проверку типа, например, проверив свойство statusCode с помощью ".hasOwnProperty".

Однако, если вы хотите использовать конструкцию "try catch(e) ", установите свойство "isShell" в значение "false". В этом случае вам нужно обработать ошибку с помощью "try catch(e) ".

Также вы можете передать пользовательские функции, которые будут вызываться внутри sdk с соответствующим кодом ошибки. Эти функции принимают объект ошибки в качестве аргумента. Вы можете обработать его самостоятельно.

const api = defineOneEntry('ваш-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),
        },
    },
})