Привет! Я Егор Стеблин, фронтенд-разработчик в юните спецпроектов KTS.

В этой статье я расскажу о том, каким образом в Discord можно встроить свой миниапп (a.k.a. «активность»). Для тех, кто еще не сталкивался с этим понятием: активности — это интерактивные приложения, которые можно запустить в Discord. Они могут интегрироваться со следующей функциональностью Discord:

получение информации о пользователе;
голосовой и текстовый чаты;
данные профиля и встроенная монетизация.

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

Ниже я опишу процесс создания Discord-активностей от инициализации приложения на портале Discord до написания кода и его тестирования.

Оглавление

Создание приложения в Discord Developer Portal
Разработка
Запуск и тестирование приложения
- Запуск приложения
- Использование DevTools
Публикация и ограничения
Заключение

Создание приложения в Discord Developer Portal

Перейдите на Discord Developer Portal.
Нажмите New Application и дайте название вашему приложению.

После создания приложения перейдите на вкладку OAuth2. Она располагается в главном меню управления проектом (1).

В этой вкладке есть несколько секций, первая из которых (Client Information) содержит ID вашего приложения и секретный ключ для OAuth-авторизации.

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

ID приложения (2) советую заранее сохранить в надежном месте, так как он понадобится в дальнейшем для запуска приложения на клиенте.

Также если вы планируете использовать авторизацию (ниже расскажу о том, для каких методов она необходима),то добавьте ссылку для переадресации (3) при успешной авторизации через OAuth. Подробнее про OAuth-авторизацию вы можете почитать здесь.

Далее перейдите в раздел меню Activities, в котором нужно будет создать саму активность a.k.a. миниапп. Для этого нажмите Getting Started (1) → Enable (2).

После принятия соглашения о создании миниаппа появится меню с его настройками.

Описание настроек:

Age Gate — возрастное ограничение 18+ для пользователей приложения;
Maximum Participants — максимально возможное количество пользователей, одновременно пользующихся вашим приложением на сервере. Если ваше приложение не опубликовано, то задавать значение выше 25 не имеет смысла в силу ограничений самого Discord (подробнее см. главу Публикация и ограничения);
Phone default orientation lock state — доступная ориентация приложения на мобильных устройствах (портретная/книжная/обе);
Tablet default orientation lock state — доступная ориентация приложения на планшетах (портретная/книжная/обе);
Supported Platforms — поддерживаемые приложением платформы.

Разработка

Активности — это веб-приложения, которые запускаются в iframe в десктопном и мобильном приложениях Discord, а также в браузерной версии. Для этого используется интерфейс postMessage, чтобы обеспечить связь между приложением и Discord.

Embedded App SDK упрощает этот процесс, управляя интерфейсом postMessage. По сути, любой метод экземпляра библиотеки является оберткой над отправкой соответствующего сообщения через интерфейс.

Жизненный цикл приложения

Инициализация. Когда ваш iframe загружается в Discord, он будет включать уникальные параметры запроса в своем URL. Эти параметры могут быть идентифицированы вашим приложением с помощью SDK Discord. Подключение библиотеки будет рассмотрено в главе Написание кода.
Процесс рукопожатия. Создание экземпляра SDK начинает процесс рукопожатия с клиентом Discord. После установления соединения iframe получает сообщение [FRAME, {evt: 'READY', ...}]. Метод ready() экземпляра SDK разрешается после успешного установления соединения. В случае неудачного установления соединения приложение не запустится, а на экране Discord в нашем случае будет бесконечно висеть лоадер.
Авторизация и аутентификация. После успешного завершения метода ready() ваше приложение должно выполнить авторизацию и аутентификацию для получения необходимых разрешений. Этот шаг важен для использования определенных функций или областей, таких как rpc.activities.write. Ниже представлена диаграмма взаимодействия различных сущностей внутри приложения от первоначальной установки соединения до авторизации:

Пример кода для авторизации со стороны клиентского приложения можно посмотреть в официальной документации.

Примечание
Данный шаг не является обязательным, если ваше приложение не планирует использовать информацию или команды, требующие определенных скоупов доступа.
Взаимодействие с клиентом Discord. После аутентификации ваше приложение может подписываться на события и отправлять команды клиенту Discord. Обратите внимание, что попытка использовать команды или подписаться на события вне предоставленной области приведет к ошибкам. Добавление новых областей может вызвать модальное окно OAuth для повторного подтверждения разрешения пользователем.
Отключение и ошибки. Получение сообщения [CLOSE, {message: string, code: number}] указывает на ошибку или необходимость перезапуска процесса подключения.
Отправка ошибок или запросов на закрытие: Чтобы сообщить об пользователю ошибке в виде модального окна или запросить закрытие от клиента Discord, отправьте [CLOSE, {message?: string, code: number}]. Код, отличный от CLOSE_NORMAL, отобразит сообщение пользователю, в то время как CLOSE_NORMAL приведет к тихому закрытию.

Возможности Embedded SDK

Рассмотрим ряд команд SDK и их возможности в рамках клиента Discord. В данный список не попали методы, связанные с монетизацией, и ряд менее используемых методов для определенных платформ. Полный список можно посмотреть по ссылке.

Название	Описание	Доступность
captureLog	Отправка сообщение во встроенный логировщик Discord. О взаимодействии с ним можно почитать здесь.	Все платформы.
encourageHardwareAcceleration	Вызов модального окна для доступа приложения к аппаратному ускорению. Подробнее.	Только десктоп
getChannel	Получение информации о канале по заданному ID. Подробнее.	Требуется авторизация. Все платформы
getChannelPermissions	Получение разрешений для текущего пользователя в текущем канале.	Требуется авторизация. Все платформы
getInstanceConnectedParticipants	Получение списка пользователей, присоединенных к приложению в текущем канале.	Все платформы
initiateImageUpload	Запуск модуля загрузки файла.	Все платформы
openExternalLink	Открытие модалки с переходом на внешнюю ссылку. Подробнее.	Все платформы
openInviteDialog	Открытие модалки для генерации приглашения в текущий канал. Подробнее.	Все платформы
openShareMomentDialog	Открытие модалки для шеринга медиа в канал или личные сообщения. Подробнее.	Все платформы
setActivity	Модифицирует краткую информацию о текущей активности пользователя внутри вашего приложения. Подробнее.	Требуется авторизация. Все платформы
userSettingsGetLocale	Получение информации о локали пользователя.	Требуется авторизация. Все платформы

Также рассмотрим ряд событий, на которые вы можете подписаться с помощью метода subscribe() для обработки соответствующим коллбэком или отписаться от которых вы можете с помощью метода unsubscribe(). В качестве примера подпишемся на ивент, реагирующий на появление голоса пользователя:

 const userStartedSpeakingListener = React.useCallback(
    ({ channel_id, user_id }: { channel_id?: string; user_id: string }) => {
      console.log('user started speaking', channel_id, user_id);
    },
    []
  );
  discordSdk.subscribe('SPEAKING_START', userStartedSpeakingListener, {});

  // если нужно отписаться
  discordSdk.unsubscribe('SPEAKING_START', userStartedSpeakingListener, {});

Полный список событий можно также найти по ссылке.

Название	Описание
VOICE_STATE_UPDATE	Отправляется при изменении состояния голоса пользователя в канале (громкость, заглушение и тд). Подробнее.
SPEAKING_START	Отправляется, когда пользователь начинает говорить. Подробнее.
SPEAKING_STOP	Отправляется, когда пользователь перестает говорить. Подробнее.
CURRENT_USER_UPDATE	Отправляется при изменении информации о текущем пользователе. Подробнее.
ORIENTATION_UPDATE	Отправляется при изменении ориентации устройства. Подробнее.
ACTIVITY_INSTANCE_PARTICIPANTS_UPDATE	Отправляется при изменении текущего количества пользователей в приложении. Подробнее.

Настройка проекта

Для сетапа приложения можно использовать любое коробочное решение как, например, create-vite. Поскольку у нас в KTS есть похожая утилита, для создания демонстрационного проекта я использовал именно ее. Что нам важно, так это добавить переменную окружения с ID приложения из первого пункта. В данном случае была создана переменная VITE_CLIENT_ID .

Также для локального тестирования Discord советует использовать технологию туннелей. Сама по себе технология позволяет сделать локальный порт доступным из интернета без настройки NAT, роутера, DDNS и других протоколов. Утилиты, предоставляющие подобную функциональность, создают туннель между вашим компьютером и удаленным сервером и предоставляют доступ к нему с уникального домена.

В документации Discord можно встретить упоминание подобного сервиса от Cloudflare. Поскольку мы находимся в России и часто делаем мини-аппы для VK, привычнее всего нам будет использовать утилиту vk-tunnel, работающую по тому же принципу. Для удобства использования утилиты можно добавить следующую команду в package.json:

"vk-tunnel": "vk-tunnel --insecure=1 --http-protocol=https --ws-protocol=wss --host=0.0.0.0 --port=8080"

Полученную ссылку вы сможете разместить как в URLMappings, так и в меню замещения ссылки, но об этом позже.

Написание кода

В рамках данного раздела мы напишем базовую реализацию модуля взаимодействия с Discord, способную запуститься в клиенте без дополнительной функциональности, активируемой с помощью авторизации.

Для работы с приложением Discord добавьте в проект SDK:

yarn add @discord/embedded-app-sdk

После добавления SDK создайте сервис для взаимодействия с ней. В частности, требуется создать экземпляр SDK, используя ID приложения из панели управления. Для инициализации приложения используйте метод ready(). Если вы планируете взаимодействовать с данными пользователя, далее вам потребуется авторизоваться через OAuth.

import { DiscordSDK } from '@discord/embedded-app-sdk';

export default class Discord {
  discordSdk: DiscordSDK | null = null;
  
  constructor() {}
  
  private _setupDiscordSdk = async(): Promise<{ isSuccess: boolean }> => {
    if (!process.env.VITE_CLIENT_ID) {
      console.error('No client id provided');
      return { isSuccess: false };
    }
    
    this.discordSdk = new DiscordSDK(process.env.VITE_CLIENT_ID);
    
    await this.discordSdk.ready();
    
    return { isSuccess: true };
  }

  init = async (): Promise<boolean> => {
    const res = await this._setupDiscordSdk();
    
    if (!res.isSuccess) {
      return false;
    }
    
    return true;
  };
}

Таким образом, остается только вызвать метод инициализации сервиса при старте приложения.

Запуск и тестирование приложения

Главным параметром при запуске приложения является ссылка, по которой Discord будет обращаться для открытия iframe. Для ее изменения требуется зайти в раздел URL Mappings и проставить ссылку на ваш деплой в соответствии с рутом.

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

Тестировать приложение можно как локально, так и удаленно.

Запуск приложения

Если вы являетесь владельцем приложения, вам достаточно зайти на сервер, открыть панель запуска приложений и выбрать ваше приложение.

Далее вы можете использовать адрес, прописанный в URL Mappings, либо использовать замещенный и вписать в поле нужный вам (например, если вы хотите протестировать локальный код).

Если же вы не являетесь владельцем приложения, вы можете добавить приложение на свой аккаунт с помощью ссылки-приглашения, которую владелец должен скопировать на экране управления приложением и отправить вам.

Помимо этого, вам следует обратиться к создателю приложения для добавления вас в список тестеров. Приглашение высылается на почту, привязанную к аккаунту Discord.

После выполнения вышеперечисленных действий вы сможете так же запустить приложение, зайдя на сервер.

Если все было сделано правильно, то приложение успешно запустится. Выглядеть это будет примерно следующим образом:

Использование DevTools

Для расширенного тестирования приложений можно воспользоваться альтернативной версией Discord, а именно — их публичной тестовой сборкой. Скачать ее можно с официального сайта на странице загрузки. В конце страницы будет немного неприметный селектор с возможностью выбора сборки для вашей платформы.

Главным отличием тестового клиента от обычного является наличие возможности включить инструменты разработчика соответствующим вашей системе сочетанием клавиш.

Таким образом, у вас откроется привычная консоль с общепринятыми инструментами для отладки веб-приложений.

Публикация и ограничения

Изначально ваше приложение доступно только для внутреннего использования, а именно для запуска владельцем и тестировщиками. Для получения возможности публикации приложения и предоставления доступа к нему всем пользователям Discord нужно пройти валидацию. Для начала разберем ограничения, накладывающиеся на ваше приложение при его создании:

возможность запускать приложение только на серверах с количеством пользователей меньше 25;
отсутствие видимости приложения для обычных пользователей.

Для получения возможности пройти верификацию приложения командой Discord вы должны выполнить ряд условий:

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

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

Заключение

Спасибо, что дочитали статью до конца. Надеюсь, что эта инструкция будет для вас полезной. Если вам известны важные нюансы интеграции миниаппов в Discord, которые я упустил, или у вас возникнут сложности на каком-либо из этапов, то приходите обсудить их в комментарии.

Также рекомендую почитать другие материалы для фронтендеров в нашем блоге:

И главное — успехов в работе над вашими проектами!

Как интегрировать миниапп (активность) в Discord