Документация по платформе YouGile

Общее описание

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

Возможности расширений

Базовое расширение

См. также 3-х минутное видео создания расширения

Структура расширения

Пример manifest.json

{
  "name": "Интеграция с Телеграм",
  "description": "Расширение позволяет <b>синхронизировать</b> групповой чат с группой в телеграм. У каждого группового чата можно создать бота, которого потом можно добавить в группу телеграм и он будет передавать сообщения в эту группу и в YouGile также присылать ответы из группы",
  "image": "/extensions/telegram-bot/media/icon.svg",
  "ui": ["index.ui.js", "two.ui.js", "util.js", "some-folder/example.js"],
  "service": "one.service.js"
}

Если расширение включено, то js файлы, которые указаны в ui запускаются в интерфейсе пользователя при входе в компанию, где это расширение включено. На данный момент import/require в ui скриптах не работает (будет пофикшено в ближайших версиях). На сервере (в приложении коробки YouGile) запускаются service скрипты.

service скрипты и ui скрипты

Возможности service скриптов

У service скриптов помимо обычных возможностей и библиотек, которые есть в node есть доступ к библиотеке yougile:

const yougile = require('yougile')

// в yougile.Company – находятся данные о компании, в которой запущено расширение
const {name, companyId} = yougile.Company

// yougile.conf – хранит настройки сервера YouGile, которые указываются в conf.json
const conf = yougile.conf

Библиотека yougile позволяет легко работать с возможностями REST API:

// отправить сообщение от лица системного пользователя
// см. https://yougile.com/api-v2#/operations/ChatMessageController_sendMessage
yougile.Api.post(`/chats/${taskId}/messages`, {
  text: 'Привет!',
  textHtml: '<p>Привет!</p>',
  label: 'Упоминание'
})

Также библиотека yougile позволяет легко подписываться на события в системе (webhooks):

const yougile = require('yougile')

// подписка на событие с установкой обработчика в скрипте
// внешний endpoint, который принимает данные не нужен
yougile.Api.subscribe({
  event: 'task-moved',
  handler: data => {
    // эта функция будет вызываться, когда будет перемещена
    // какая-либо задача в компании, где включено расширение,
    // перемещение должно быть в другую колонку
    // data - содержит информацию о перемещённой задаче
    console.log('Task was moved', data)
  }
})

Описание всех событий в REST API можно найти здесь

Есть определенные нюансы в использовании нативных методов node, некоторые из них отсутствуют (связано это с тем, что не все методы node попадают в бинарник), например, для использования fetch нужно использовать const fetch = require('node-fetch').

Возможности ui скриптов

ui скрипты запускаются в браузере и десктоп-приложении YouGile. В них доступны многие стандартные возможности javascript, но также для работы с интерфейсом системы доступна библиотека yougile-ui.

// при подключении библиотеки
// новые методы добавляются в глобальное пространство имён
require('yougile-ui')

// показать сообщение об ошибке
Notifier.error('Hello!')

Список всех возможностей такой же, как и в конфигураторе YouGile, здесь можно посмотреть небольшую инструкцию https://yougile.com/media/docs/yougile-api-manual.pdf

В интерфейсе YouGile встроен редактор, который позволяет быстро проверить работу небольших ui скриптов – его можно вызвать сочетанием клавиш Ctrl+˜ (ctrl и тильда, на macos тоже ctrl). В правой части этого интерфейса есть список всех методов, которые доступны в ui скриптах и в этом редакторе сразу можно попробовать эти методы.

Взаимодействие между ui и service скриптами

Также у ui скриптов есть механизм взаимодействия с service скриптами -- можно определить функцию в service скрипте, которую можно вызвать из ui скрипта.

На стороне service скрипта:

const yougile = require('yougile')
const Service = yougile.Service

// userId передаётся всегда – это id пользователя
// у которого вызвался метод (в этих примерах userId не используется)
Service.serverTime = ({userId}) => {
  return Date.now()
}

Service.addTwoNumbers = ({userId, args}) => {
  const [a, b] = args
  return a + b
}

На стороне ui скрипта:

require('yougile-ui')

const time = await Service.serverTime()
console.log('Server time is', time)

const sum = await Service.addTwoNumbers(1, 2)
console.log(sum, 'must be equal to', 3)

Хранение публичных данных в ui и service скриптах

Для этого на клиенте используем

const data = await Service.getData()
Service.setData({...})

В сервисе используем так

const yougile = require('yougile')
const data = await yougile.Service.getData()
await yougile.Service.setData({...})

Хранение непубличных данных в service скриптах

На клиенте методы Service.getPrivateData(), Service.setPrivateData() недоступны. В сервисе используем так

const yougile = require('yougile')
// получаем непубличные данные
const data = await yougile.Service.getPrivateData()
// сохраняем непубличные данные
await yougile.Service.setPrivateData({token: '...'})

Расположение данных

Публичные данные хранятся по пути ./database/$companyId/$extension-name.json. Приватные данные хранятся по пути ./database/$companyId/$extension-name-private.json

Путь до базы данных можно получить так

const {DataService} = require('yougile')
DataService.getDatabasePath()

Библиотека yougile

Данная библиотека используется только в серверных скриптах. Из yougile может быть сделан импорт следующего:

Api - необходим для REST Api вызовов, также можно подписаться на вебхуки yougile (метод subscribe) или подписаться на свои кастомные вебхуки (метод subscribeCustomWebhook)

Company - хранит имя компании и companyId

Service - необходим для взаимодействия клиент/сервер и получения/сохранения данных

conf - хранит основной конфиг yougile

extension - имя расширения

mainDir - путь до папки yougile

Прочее

Пример расширения

Для старта разработки расширения Вы можете воспользоваться примером расширения. Находится он по пути ./example-extension.

В примере есть запросы к REST API, подписка на событие перемещения задачи (перемещение не должно быть внутри столбца), обмен данными между сервером и клиентом, пример взаимодействия с публичными и приватными данными.

Для того чтобы пример появился в списке расширений, папку ./example-extension нужно скопировать в папку ./extensions

Установка расширения

Расширение можно установить двумя способами

  1. Установить через архив (поддерживаются zip архивы). Для того чтобы установить - нужно заархивировать папку расширения в zip архив -> перейти в 'Моя компания' -> 'Расширения' -> и внизу нажать на кнопку 'Установить'. Через 5-10 секунд Ваше расширение появится в списке расширений. Расширение установится в папку ./extensions

  2. Поместить папку с расширением в папку ./extensions

О чем нужно знать

  1. На данный момент расширения занимают память, 250 Мб в режиме работы и 450 Мб в момент запуска одного расширения на одну компанию. В ближайшем будущем мы пофиксим это, но нужно учесть, что каждое запущенное расширение даже не в основной компании занимает 450 Мб при запуске сервера и когда память заканчивается, то приложение работает со сбоями. В ближайших релизах пофиксим это.

  2. Расширения запускаются через 15 секунд после старта сервера. Иногда требуется перезагрузить страницу, чтобы клиентский код расширения появился в браузере.

Полезные ссылки

REST API

Администрирование коробки

Примеры скриптов конфигуратора

Документация конфигуратора - можно вызвать сочетанием клавиш Ctrl+˜ (ctrl и тильда, на macos тоже ctrl). В правой части этого интерфейса есть список всех методов, которые доступны в ui скриптах и в этом редакторе сразу можно попробовать эти методы. (На данный момент в библиотеке yougile-ui более полное описание некоторых сигнатур методов для конфигуратора)

Библиотека yougile-ui - декларации типов для конфигуратора

Библиотека yougile - библиотека для работы серверных скриптов