Общая информация¶
Примечание
Над приложениями ведётся постоянная работа по улучшению и наращиванию функционала
Для сторонних сервисов, которым недостаточно API, мы предоставляем возможность создавать приложения (аналогичные приложениям в социальных сетях).
Приложения могут подписываться на потоки событий и добавлять в наш интерфейс собственные виджеты. Потоки дают возможность не делать регулярные запросы на проверку появления новых сущностей и изменения старых, а получать их на указанный HTTP. А виджеты позволяют отображать стороннюю информацию, прямо в интерфейсе Мегаплана, и инициировать действия для сторонних сервисов.
Добавление и управление приложениями происходит на странице /settings/application.
Типы приложений¶
В Мегаплане есть два типа приложений: полноценное приложение с доступом по API и приложение-виджет, доступное для установки любому пользователю Мегаплана. Полноценное приложение может быть установлено только пользователем, входящим в роли «Директора» или «Админы». Такое приложение имеет доступ по API с правами того пользователя, который устанавливал приложение. Приложение-виджет используется для того, чтобы подгрузить виджет на странице Мегаплана тем пользователям, которым это необходимо. Такие приложения могут устанавливать и отключать сами пользователи только для себя, а пользователи в ролях «Директора» и «Админы» могут установить для всех сотрудников.
Пункт Меню¶
У приложения может быть связь с пунктом меню. Когда необходимо в главное меню добавить отдельный пункт, который в iframe или в новой вкладке будет открывать внешний URL. Пример такого приложения «календарь сделок».
Аутентификация в API¶
Каждому приложению выделяется токен. Узнать его можно на странице редактирования приложения, а также, при подписке на потоки, через событие установки приложения. UUID приложения и токен можно использовать для аутентификации в API. В этом случае UUID используется в качестве AccessId, а токен в качестве SecretKey.
Версии API¶
Версия APIv1 больше не развивается, оставленая для обратной совместимости.
Текущая версия APIv3.
Структура приложения¶
Внешний вид формы редактирования приложения:
UUID и API token используются для API запросов в Мегаплан. URL страницы приложения используется, например, для пункта меню - все пользователи смогут попасть на эту страницу.
URL страницы настроек - для групп прав «Директора» и «Админы». Может использоваться, при необходимости, для настройки со стороны стороннего сервиса.
URL принимающий события - обработка потоков событий от Мегаплана по сущностям, отмеченными галочками в настройках потоков событий.
Пункт меню - пункт главного меню Мегаплана, связанный с приложением.
Виджеты - добавляют на страницы Мегаплана в установленных местах (плейсхолдерах) внешний код или контент.
Страница приложения¶
Если приложению необходима собственная страница в Мегаплане, доступная каждому пользователю, то при создании приложения, можно указать внешний URL в качестве URL страницы приложения. Тогда по адресу
/application/page/<UUID приложения>, пользователю будет открываться интерфейс Мегаплана, со встроенным iframe.
Как это работает:
Мы указываем нашему приложению URL собственной страницы.
Пользователь переходит на страницу приложения (например, по ссылке, добавленной в меню c помощью привязанного к приложению пункта меню)
/application/page/<UUID приложения>.Пользователю показывается страница Мегаплана. В теле страницы находится iframe с адресом
<URL страницы приложения>&accountId=<хост аккаунта>&applicationUuid=<UUID приложения>&sessionId=<id сессии>&userSign=<подпись пользователя>&uniqueAccountId=<уникальный числовой идентификатор аккаунта>&permanentHost=<уникальный хост аккаунта>.Чтобы приложение могло идентифицировать пользователя Мегаплана, оно должно сделать api-запрос по адресу
/BumsSettingsApiV01/Application/checkUserSign.json?uuid=<UUID-приложения>&userSign=<подпись>. В ответе будет либо 403, если подпись не верна или старше 60 секунд, либо данные о пользователе.Чтобы не делать этот запрос каждый раз, в iframe передается параметр sessionId, который уникален для текущей сессии пользователя.
Часто у разработчиков приложений возникает необходимость идентифицировать аккаунт Мегаплана, с которого идёт обращение к приложению. Это удобно сделать по значению параметра applicationUuid. Этот id отлично подходит в качестве ключа для хранения настроек аккаунта Мегаплана на стороне разработчика приложения.
Параметр permanentHost имеет значение уникального хоста аккаунта, присваивается при его создании и не меняется, если даже аккаунту изменяют имя.
Пример ответа на запрос идентификации:
{
"status": {
"code": "ok",
"message": null
},
"data": {
"contentType": "Employee",
"id": "1000001",
"name": "User Name",
"firstName": "User",
"lastName": "Name",
"position": "Директор",
"uid": 1000075,
"birthday": {
"contentType": "DateTime",
"value": "2016-09-06T21:00:00+00:00"
},
"age": null,
"contactInfo": [
{
"contentType": "ContactInfo",
"type": "email",
"value": "[email protected]"
},
{
"contentType": "Phone",
"areaCode": "910",
"number": "0000000",
"countryCode": 7,
"type": "mobile",
"comment": ""
}
]
...
}
}
Страница настроек приложения¶
Если приложению необходима собственная страница настроек в Мегаплане, доступная каждому пользователю, то при создании приложения, можно указать внешний URL в качестве URL страницы настроек. Тогда при попытке войти в настройки приложения, пользователю будет открываться интерфейс Мегаплана, со встроенным iframe.
URL для iframe будет формироваться следующим образом:
<URL страницы настроек приложения>&accountId=<хост аккаунта>&applicationUuid=<UUID приложения>&sessionId=<id сессии>&userSign=<подпись пользователя>&uniqueAccountId=<уникальный числовой идентификатор аккаунта>&permanentHost=<уникальный хост аккаунта>.Значения параметров в URL аналогичны значениям в URL для страницы приложения.
Примеры стилей¶
Чтобы виджеты и страницы были похожи на «родной» интерфейс Мегаплана, вы можете использовать нашу
подборку стилей.