Общая информация

Примечание

Над приложениями ведётся постоянная работа по улучшению и наращиванию функционала

Для сторонних сервисов, которым недостаточно API, мы предоставляем возможность создавать приложения (аналогичные приложениям в социальных сетях).

Приложения могут подписываться на потоки событий и добавлять в наш интерфейс собственные виджеты. Потоки дают возможность не делать регулярные запросы на проверку появления новых сущностей и изменения старых, а получать их на указанный HTTP. А виджеты позволяют отображать стороннюю информацию, прямо в интерфейсе Мегаплана, и инициировать действия для сторонних сервисов.

Добавление и управление приложениями происходит на странице /settings/application.

Типы приложений

В Мегаплане есть два типа приложений: полноценное приложение с доступом по API и приложение-виджет, доступное для установки любому пользователю Мегаплана. Полноценное приложение может быть установлено только пользователем, входящим в роли «Директора» или «Админы». Такое приложение имеет доступ по API с правами того пользователя, который устанавливал приложение. Приложение-виджет используется для того, чтобы подгрузить виджет на странице Мегаплана тем пользователям, которым это необходимо. Такие приложения могут устанавливать и отключать сами пользователи только для себя, а пользователи в ролях «Директора» и «Админы» могут установить для всех сотрудников.

Пункт Меню

У приложения может быть связь с пунктом меню. Когда необходимо в главное меню добавить отдельный пункт, который в iframe или в новой вкладке будет открывать внешний URL. Пример такого приложения «календарь сделок».

Аутентификация в API

Каждому приложению выделяется токен. Узнать его можно на странице редактирования приложения, а также, при подписке на потоки, через событие установки приложения. UUID приложения и токен можно использовать для аутентификации в API. В этом случае UUID используется в качестве AccessId, а токен в качестве SecretKey.

Версии API

Сейчас основные APIv1, описанные в этой документации.

В приложениях используются сущности из APIv3.

Структура приложения

Внешний вид формы редактирования приложения:

../_images/app_settings.png

UUID и API token используются для API запросов в Мегаплан. URL страницы приложения используется, например, для пункта меню - все пользователи смогут попасть на эту страницу.

URL страницы настроек - для групп прав «Директора» и «Админы». Может использоваться, при необходимости, для настройки со стороны стороннего сервиса.

URL принимающий события - обработка потоков событий от Мегаплана по сущностям, отмеченными галочками в настройках потоков событий.

Пункт меню - пункт главного меню Мегаплана, связанный с приложением.

Виджеты - добавляют на страницы Мегаплана в установленных местах (плейсхолдерах) внешний код или контент.

Страница приложения

Если приложению необходима собственная страница в Мегаплане, доступная каждому пользователю, то при создании приложения, можно указать внешний URL в качестве URL страницы приложения. Тогда по адресу /application/page/<UUID приложения>, пользователю будет открываться интерфейс Мегаплана, со встроенным iframe.

Как это работает:

  1. Мы указываем нашему приложению URL собственной страницы.

  2. Пользователь переходит на страницу приложения (например, по ссылке, добавленной в меню c помощью привязанного к приложению пункта меню) /application/page/<UUID приложения>.

  3. Пользователю показывается страница Мегаплана. В теле страницы находится iframe с адресом <URL страницы приложения>&accountId=<хост аккаунта>&applicationUuid=<UUID приложения>&sessionId=<id сессии>&userSign=<подпись пользователя>&uniqueAccountId=<уникальный числовой идентификатор аккаунта>&permanentHost=<уникальный хост аккаунта>.

  4. Чтобы приложение могло идентифицировать пользователя Мегаплана, оно должно сделать api-запрос по адресу /BumsSettingsApiV01/Application/checkUserSign.json?uuid=<UUID-приложения>&userSign=<подпись>. В ответе будет либо 403, если подпись не верна или старше 60 секунд, либо данные о пользователе.

  5. Чтобы не делать этот запрос каждый раз, в iframe передается параметр sessionId, который уникален для текущей сессии пользователя.

  6. Часто у разработчиков приложений возникает необходимость идентифицировать аккаунт Мегаплана, с которого идёт обращение к приложению. Это удобно сделать по значению параметра applicationUuid. Этот id отлично подходит в качестве ключа для хранения настроек аккаунта Мегаплана на стороне разработчика приложения.

  7. Параметр 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 для страницы приложения.

Примеры стилей

Чтобы виджеты и страницы были похожи на «родной» интерфейс Мегаплана, вы можете использовать нашу подборку стилей.