Инструкция по использованию API образовательной платформы NBICS.NET для разработки сторонних приложений и интеграции в сторонние сайты.
1. Регистрация приложения.
Для начала работы с API платформы стороннему разработчику понадобится зарегистрировать своё приложение в платформе.
Для этого необходимо связаться с сотрудником компании по телефону 8(4012)995982. Сотруднику необходимо сообщить адрес сайта (ApplicationSite) предполагаемого приложения и его название (ApplicationName - не превышает 31 символ). После регистрации приложения сторонний разработчик получит ApplicationPassword. Комбинация ApplicationName и ApplicationPassword является именным ключом для доступа приложения к API платформы.
2. Получение Token.
Следующим шагом является получение Token - временного ключа доступа к API платформы.
Для этого необходимо сделать запрос:
/Application/GetToken
Параметры:
ApplicationName - название приложения (макс 31 символ) должно быть уникально в рамках платформы
ApplicationPassword - пароль приложения для доступа к API платформы
Тип запроса:
GET/POST
Пример запроса:
/Application/GetToken?ApplicationName=SomeApplicationName&ApplicationPassword=SomeApplicationPassword
Пример ответа:
{
"Token": "SomeToken" // Значение пароля токена
,"ValidTo": "2019-11-26T16:26:05" // Время, до которого действует токен
,"Success": true
,"Message": null // Заполняется в случае ошибки и Success = false
}
Примечание:
Поле ValidTo указывается для удобства отслеживания разработчиком стороннего приложения периода валидности токена.
Если токен устарел (ValidTo < Текущего времени), то необходимо повторно запросить токен с помощью данного запроса.
Период валидности токена - 2 часа с момента его получения.
Токен для приложения существует в единственном экземпляре.
При повторном запросе предыдущий токен уничтожается и генерируется новый.
3. Регистрация пользователя.
Для фиксации факта прохождения урока необходимо создать пользователя, который будет проходить урок.
Для Этого необходимо сделать запрос:
/Application/RegisterUserПараметры:
Token - временный ключ, полученный на шаге 2.
Login - уникальный идентификатор пользователя в платформе (предпочтительно Email)
Тип запроса:
GET/POST
Пример запроса:
/Application/RegisterUser?Token=SomeToken&Login=SomeLogin
Пример ответа:
{
"User": {
"Login": "SomeLogin"
,"PasswordHash": "SomePasswordHash"
}
,"Success": true
,"Message": null // Заполняется в случае ошибки и Success = false
}Примечание:
После регистрации пользователь сразу привязывается к приложению-владельцу токена.
4. Получение списка пользователей, привязанных к приложению.
Для получения списка всех пользователей, привязанных к приложению, необходимо сделать запрос:
/Application/GetUsers
Параметры:
Token - временный ключ, полученный на шаге 2.
Тип запроса:
GET/POST
Пример запроса:
/Application/GetUsers?Token=SomeToken
Пример ответа:
{
"Users": [{
"Login": "SomeLogin"
,"PasswordHash": "SomePasswordHash"
}]
,"Success": true
,"Message": null // Заполняется в случае ошибки и Success = false
}
5. Удаление пользователя из аккаунта приложения.
Для удаления пользователя из аккаунта приложения необходимо сделать запрос:
/Application/DeleteUser
Параметры:
Token - временный ключ, полученный на шаге 2.
Login - уникальный идентификатор пользователя в платформе, указанный при его регистрации
Тип запроса:
GET/POST
Пример запроса:
/Application/DeleteUser?Token=SomeToken&Login=SomeLogin
Пример ответа:
{
"Success": true
,"Message": null
}
6. Создание урока.
Для создания урока необходимо сделать запрос:
/EducationHome/CreateLessonConfiguration
Параметры:
Token - временный ключ, полученный на шаге 2.
ConfigurationName - название создаваемого урока
Login - уникальный идентификатор пользователя в платформе, указанный при его регистрации
PasswordHash - хеш пароля пользователя, который платформа вернула при его регистрации
Тип запроса:
GET/POST
Пример запроса:
/EducationHome/CreateLessonConfiguration?Token=SomeToken&ConfigurationName=SomeConfigurationName&Login=SomeLogin&PasswordHash=SomePasswordHash
Пример ответа:
{
"ConfigurationMetaData": {
"Id": -2147382881
,"Parent": null
,"Guid": "2250789c-f83e-41c5-aa95-d8bb865ed038"
,"Name": "Новый урок API"
,"Code": "Novyj-urok-API"
,"Children": []
,"Type": "Configuration"
,"Author": null
,"Editor": null
,"CreationTime": null
,"LastModifyTime": null
,"Index": 0
,"ReadOnly": false
,"Editable": false
,"IsTemplateConfiguration": false
,"CreatedFromTemplate": false
,"Settings": {"WidgetContainers":[],"WidgetEventsPermissions":[]}
,"Description":null
}
,"ErrorCode": 0
,"Success": true
,"Message":null
}Примечание:
Созданный урок будет привязан к пользователю с указанными в параметрах Login и PasswordHash.
7. Получение списка уроков
Для получения списка уроков необходимо сделать запрос:
/EducationHome/GetLessonsConfigurationsList
Параметры:
Token - временный ключ, полученный на шаге 2.
Login - уникальный идентификатор пользователя в платформе, к которому привязаны уроки
PasswordHash - хеш пароля пользователя, который платформа вернула при его регистрации
Тип запроса:
GET/POST
Пример запроса:
/EducationHome/GetLessonsConfigurationsList?Token=SomeToken&Login=SomeLogin&PasswordHash=SomePasswordHash
Пример ответа:
[{ "Name": "SomeName" ,"Code": "SomeCode" ,"Guid":"SomeGuid" } ,{ "Name": "SomeName2" ,"Code": "SomeCode2" ,"Guid":"SomeGuid2" }]
8. Удаление урока
Для удаления урока необходимо сделать запрос:
/EducationHome/DeleteLessonConfiguration
Параметры:
ConfigurationCode - код (Code) урока, который необходимо удалить
Token - временный ключ, полученный на шаге 2.
Login - уникальный идентификатор пользователя в платформе, к которому привязан урок
PasswordHash - хеш пароля пользователя, который платформа вернула при его регистрации
Тип запроса:
GET/POST
Пример запроса:
/EducationHome/DeleteLessonConfiguration?Token=SomeToken&Login=SomeLogin&PasswordHash=SomePasswordHash?ConfigurationCode=SomeConfigurationCode
Пример ответа:
{
"Success": true
,"Message": null
}Примечание:
Для удаления урока необходимо указать Login и PasswordHash пользователя, к которому этот урок привязан
9. Встраивание урока в свой сайт.
Для получения урока с целью вставки на свой сайт необходимо сделать запрос:
/Application/GetConfigurationFragment
Параметры:
ConfigurationCode - код (Code) урока
Token - временный ключ, полученный на шаге 2.
Login - уникальный идентификатор пользователя в платформе
PasswordHash - хеш пароля пользователя, который платформа вернула при его регистрации
ColorSchemeName - цветовая схема урока (необязательный параметр, возможные варианты: blue (по умолчанию), green, orange, red, purple)
CurrentLocalizationCode - код языка интерфейса урока (необязательный параметр, возможные варианты: ru (по умолчанию), en)
Тип запроса:
GET/POST
Пример запроса:
/Application/GetConfigurationFragment?Token=SomeToken&Login=SomeLogin&PasswordHash=SomePasswordHash&ConfigurationCode=SomeConfigurationCodeПример ответа:
html-страница
Примечание:
Если Login и PasswordHash принадлежат пользователю-владельцу урока, то урок будет доступен для редактирования, в противном случае - только для прохождения.
10. Статистика прохождения уроков
Для получения статистики прохождения уроков необходимо сделать запрос:
/EducationHome/GetStatistics
Параметры:
Lessons - уроки, по которым необходимо получить статистику (необязательный параметр, если не указан, то будет отобрана статистика по всем урокам)
Users - пользователи, по которым необходимо получить статистику (необязательный параметр, если не указан, то будет отобрана статистика по всем пользователям)
Token - временный ключ, полученный на шаге 2.
LastLoadedDataTime - временная метка последней порции данных статистики, загруженной в предыдущем запросе (необязательный параметр, при указании параметра будет загружена статистика после указанного времени, новая метка возвращается в результате каждого запроса)
Portion - размер порции данных (количество этапов уроков), которое будет выгружено запросом (необязательный параметр, можно указать значение от 1 до 1000, по умолчанию 1000)
Тип запроса:
GET/POST
Пример запроса:
/EducationHome/GetStatistics?Token=SomeToken&Lessons=[{Code:"SomeLessonCode"}]&Users=[{Email:"SomeUserEmail"}]&LastLoadedDataTime=01/27/2020 10:04:42&Portion=10
Пример ответа:
{ "IsDataFull": false, // Если true, то загружены все данные статистики по указанным параметрам, // если нет, то нужно делать ещё запрос, предварительно изменив // параметр LastLoadedDataTime "Data": [{ // идентификатор попытки прохождения урока "LessonTryGuid": "33017099-ecb1-4435-97fd-2a90e921d746" // пользователь, который проходил урока ,"Student": { "ConnectionIds": [], "Id": -2147475976, "Name": null, "Photo": null, "Email": "maitakov@mail.ru", "SharedCount": 0, "IsShared": false, "IsRejected": false, "Type": 0 }, "Configuration": { // урок, который проходил пользователь "Id": -2147375499, "Parent": null, "Guid": "018c016d-6421-49a9-9f4a-6a7cd55544e5", "Name": null, "Code": "NewLessonMaitakov", "Children": [], "Type": "Configuration", "Author": null, "Editor": null, "CreationTime": null, "LastModifyTime": null, "Index": 0, "ReadOnly": false, "Editable": false, "IsTemplateConfiguration": false, "CreatedFromTemplate": false, "Settings": { "WidgetContainers": [], "WidgetEventsPermissions": [] }, "Description": null }, // этап урока, который проходил пользователь "Phase": { // идентификатор этапа "Guid": "2b694061-1712-40da-ba26-246ade18a2fd", // название этапа "Name": "Новый этап", // тип этапа. Возможны варианты: Construction, Process, Classification, // Test, PDFDocument, Iframe "Type": "Test", // результат прохождения этапа: // true - этап пройден успешно, false - этап не пройден "Success": true, // количество баллов, которое пользователь // набрал в данном этапе (возможно дробное значение) "StudentSuccessTestCount": 2.0, // процент успешного прохождения этапа, начиная с которого // этап считается пройденным (устанавливается автором урока) "SuccessPercent": 100, // количество этапов в уроке "LessonPhasesCount": 1, // общее количество баллов, которое можно набрать в данном этапе "TotalTestCount": 2, // порядковый номер этапа в уроке в момент прохождения "PhaseIndexInLesson": 0, // время начала прохождения этапа "StartTime": "2020-01-27T09:14:28", // время окончания прохождения этапа "EndTime": "2020-01-27T09:14:32" } }], // временная метка (самое позднее время окончания этапа в рамках текущего запроса), // необходимо для порционной выгрузки статистики. // этот параметр в таком же формате необходимо // передать в следующем запросе, чтобы выгрузить все этапы, // которые были пройдены после этого времени. "LastLoadedDataTime": "01/27/2020 09:14:32", // Результат запроса "Success": true, // Сообщение, появляется в случае ошибки "Message": null }
Примечание:
Все параметры фактически фильтруют запрашиваемую статистику. Таким образом, можно отбирать данные по конкретному пользователю и уроку, начиная с определенного этапа.
Необходимо отбирать данные порционно и при этом сохранять параметр "LastLoadedDataTime", который необходимо использовать в следующем запросе (это снимает необходимость каждый раз запрашивать всю статистику целиком).
Без указания параметра "LastLoadedDataTime" сервер вернет первые Portion (по умолчанию 1000) этапов. Более 1000 этапов сервер не возвращает.
11. Удаление статистики прохождения уроков.
Для удаления статистики прохождения уроков необходимо сделать запрос:
/EducationHome/DeleteUsersStatistics
Параметры:
Lessons - уроки, по которым необходимо удалить статистику (необязательный параметр, если не указан, то будет удалена статистика по всем урокам)
Users - пользователи, по которым необходимо удалить статистику (необязательный параметр, если не указан, то будет удалена статистика по всем пользователям)
Token - временный ключ, полученный на шаге 2.
TimeFrom - временная метка, начиная с которой будет удаляться статистика (необязательный параметр, если не указан, то будет удалена статистика за всё время)
Тип запроса:
GET/POST
Пример запроса:
/EducationHome/DeleteUsersStatistics?Token=SomeToken&Lessons=[{Code:"SomeLessonCode"}]&Users=[{Email:"SomeUserEmail"}]&TimeFrom=04/06/2020 15:01:00
Пример ответа:
{ "Success": true ,"Message": null ,"ErrorCode": null }
Примечание:
Все параметры фактически фильтруют удаляемую статистику. Таким образом, можно удалять данные по конкретному пользователю и уроку, начиная с определенного времени.
12. Подписка на события урока (встроенного в iframe) родительской страницей (страница, в которой находится iframe)
Урок, встраиваемый с помощью iframe в сторонний сайт, может отправлять некоторые события родительскому для iframe окну.
Чтобы подписаться на какое-либо событие необходимо вставить следующий код (или его модификацию) на языке JavaScript в страницу, в которую встроен iframe:
var eventMethod = window.addEventListener ? "addEventListener" : "attachEvent";
var eventer = window[eventMethod];
var messageEvent = eventMethod === "attachEvent" ? "onmessage" : "message";
eventer(messageEvent, function (e) {
let Event = e.data || e.message;
console.log(Event);
});
Пример структуры параметра Event:
{
Type: "LessonFinished", // тип события
Data: {
Success: true, // успешность прохождения урока
Code: "Novaya-konfiguraciya12345678921", // код урока
Name: "Новая конфигурация", // название урока
Guid: "29904894-0928-4c4d-99c7-339f2bd1bd7c", // guid урока
SuccessPhasesCount: 7, // количество успешно пройденных этапов
TotalPhasesCount: 7, // количество этапов всего
TotalPhasesWithProgressCount: 1, // количество этапов с заданиями
TotalProgressPercent: 100 // общий процент выполнения урока
}
}
Примечание:
При успешном прохождении урока (Success = true) общий процент выполнения урока (TotalProgressPercent) не всегда будет равен 100.