JSON-манифест приложения (пример)

Манифест (файл manifest.json) описывает свойства приложения и точки его интеграции с Аспро.Cloud . Ниже приведён упрощённый пример структуры манифеста со словами-ключами и пояснениями:

{
  "appId": "com.example.weather",             // Уникальный идентификатор приложения
  "name": "Прогноз Погоды",                  // Название приложения
  "version": "1.0.0",                        // Версия приложения (Major.Minor.Patch)
  "description": "Показывает погоду в выбранном городе.",
  "author": {
    "name": "Example Inc.", 
    "contact": "support@example.com"
  },
  "iconUrl": "https://example.com/icon.png",  // URL иконки приложения
  "categories": ["Утилиты"],                 // Категории/разделы маркетплейса
  "tags": ["weather", "погода"],
  "permissions": [                           // Запрашиваемые права доступа
    "crm.contacts.read", 
    "tasks.create"
  ],
  "integrationPoints": {                     // Точки встраивания приложения:
    "menu": {                                // -> пункт в главном меню
      "section": "CRM", 
      "title": "Прогноз погоды",
      "icon": "https://example.com/menu_icon.png"
    },
    "dashboard": {                           // -> виджет на рабочем столе (дашборде)
      "widgetTitle": "Погода сегодня",
      "size": "small"
    },
    "cards": [                               // -> виджет в карточках объектов (напр., клиент)
      {
        "entity": "client", 
        "widgetTitle": "Погода в регионе клиента"
      }
    ]
  },
  "entrypointURL": "https://app.example.com/",   // URL основного веб-интерфейса приложения
  "webhookURL": "https://app.example.com/webhook", // (опционально) URL для обратных вызовов
  "apiEndpoints": {                             // (опц.) дополнительные методы API приложения
    "getForecast": {
      "url": "https://app.example.com/api/forecast",
      "method": "GET"
    }
  },
  "configuration": {                            // (опц.) схема настроек приложения
    "configSchema": {
      "type": "object",
      "properties": {
        "apiKey": { "type": "string", "title": "API ключ погодного сервиса" }
      },
      "required": ["apiKey"]
    },
    "defaultConfig": {
      "apiKey": ""
    }
  },
  "platformVersion": "1.0"                     // Совместимая версия платформы Аспро.Cloud
}

Ключевые поля манифеста:

• Идентификация приложения: поля appId (уникальный идентификатор или namespace), name (название) и version (версия в формате SemVer). Идентификатор используется для ссылок и внутренних ключей, версия позволяет отслеживать обновления .
• Описание и метаданные: description – краткое описание назначения приложения; categories и tags – категории и теги для классификации в каталоге маркетплейса; author – информация об авторе/разработчике (например, компания и контактные данные) .
• Иконка и графика: поле iconUrl содержит ссылку на иконку приложения (PNG/SVG), которая будет отображаться в списке приложений и, например, в меню при интеграции . Дополнительно могут быть указаны ссылки на скриншоты или превью интерфейса приложения для каталога.
• Права доступа (permissions): список разрешений, необходимых приложению . Здесь указывается, к каким модулям или данным Аспро.Cloud требуется доступ (например, чтение контактов CRM, создание задач или сделок и т.д.). Эти права будут запрошены у администратора при установке приложения; установка возможна только если админ подтвердит все запрошенные permissions . В процессе работы приложения система строго соблюдает указанные права: API-запросы от приложения проверяются, и любые действия вне разрешённых будут отклонены .
• Интеграционные точки (integrationPoints): описывает, где именно приложение встраивается в интерфейс портала . В манифесте это объект с вложенными секциями для каждой точки интеграции. Например:
  • header – интеграция в шапку (верхнюю панель) портала, позволяет добавить иконку/кнопку приложения на верхнюю панель .
  • menu – интеграция в главное меню; приложение может добавить новый пункт навигации (раздел или подменю) .
  • tabs – интеграция в виде вкладки на страницах существующих объектов (например, вкладка на странице сделки CRM) .
  • cards – интеграция виджетом в карточки объектов (например, дополнительный блок информации в профиле клиента) .
  • Кроме того, поддерживаются точки reports (новый тип отчёта), dashboard (виджет на главном рабочем столе пользователя), mobile (элементы в мобильном приложении) и contactCenter(интеграция в модуль контакт-центра). Полный список точек и их описание приведены в следующем разделе.

• URLs внешнего сервиса: для приложений, имеющих внешний веб-сервис, манифест может содержать:
  • entrypointURL – основная ссылка на интерфейс приложения (загружается во встроенном iframe или отдельной вкладке) .
  • webhookURL – опциональный URL, на который платформа будет отправлять события для приложения (например, уведомление об установке/удалении, события CRM и т.д.).
  • apiEndpoints – опциональное описание дополнительных API-методов, которые предоставляет само приложение для взаимодействия. Платформа может вызывать их при необходимости (например, для получения данных от приложения) .

• Настройки конфигурации: секция configuration появляется, если для работы приложения требуются пользовательские настройки при установке. Она может включать:
  • configSchema – JSON Schema, описывающая ожидаемые параметры конфигурации . На основе этой схемы при установке будет автоматически сгенерирована форма ввода настроек (например, чтобы администратор ввёл API-ключ внешнего сервиса).
  • defaultConfig – значения по умолчанию для этих параметров .

    Эти поля позволяют запросить у администратора необходимые данные при установке приложения и безопасно их сохранить.

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