Приложения групп

Что такое приложения групп?

Приложения групп — это кроссплатформенные приложения, которые запускаются со страницы групп ОК или из публикаций в ленте.
Пользователь может открыть приложение в полной версии сайта, в мобильной версии m.ok.ru и в мобильных приложениях ОК для iOS и Android.
С технической точки зрения, это HTML приложение, запускаемое в iframe на полной версии сайта, во WebView в мобильных приложениях или в отдельной вкладке мобильного браузера.

В процессе разработки своего приложения для групп вам понадобятся следующие руководства:

  • Создание приложения — перед началом разработки, прочитайте как создать собственное приложение в Одноклассниках. При регистрации приложения нужно указать платформы: Web(HTML), HTML(Mobile) и “Приложение для групп”, и указать размеры приложения.
  • Javascript SDK — руководство по использованию Javascript SDK (рекомендуем использовать beta-версию кроссплатформенной библиотеки из ветки на github-е: github:ok-js-sdk/multi-platform-widgets)
  • FAPI JS — руководство по использованию JS SDK в приложениях, открытых в iframe на полной версии сайта.
  • REST методы — руководство по использованию методов API.
  • Параметры запуска приложения — описание параметров для запуска приложения.
  • Bot API для групп — API для отправки личных сообщений от имени группы.
  • Правила размещения групповых приложений - требования к приложению для попадания в каталог.

Регистрация приложения

Для добавления приложения на сайт ОК необходимо:

  1. Зарегистрироваться на портале ОК и привязать к своему аккаунту email – на этот email будут приходить письма, содержащие регистрационные данные приложений.
  2. Получить права разработчика по ссылке https://ok.ru/devaccess.
  3. После получения прав разработчика откройте раздел Игры и в левом меню выберите “Мои загруженные”. В списке нажмите Добавить приложение: https://ok.ru/dk?st.cmd=appEdit и нажмите кнопку Добавить платфому.
  4. Для регистрация приложения для групп укажите платформы: Web(HTML), HTML(Mobile) и Приложение для групп. Укажите размеры приложения (они будут применяться для открытия на полной версии сайта).
  5. Указать официальную группу приложения и ID топика, в котором подробно рассказывается, как пользоваться и настроить приложение, рассматриваются популярные примеры использования.
  6. Указать специфичные для приложения групп параметры: кнопка запуска по-умолчанию, возможность открывать на отдельной странице, устанавливать по прямой ссылке и ограничить приложение только для модераторов групп.

Подробнее: Создание приложения

Параметры запуска

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

Кроме перечисленных при запуске приложения со страницы группы, будут передаваться дополнительные параметры:

ПараметрТипОписание
group_idLongидентификатор группы
viewer_typeStringроль пользователя в группе
custom_argsStringкастомные параметры запуска, переданные после ?

Параметр viewer_type (роль пользователя в группе) может иметь следующие строковые значения:

ЗначениеОписание
ADMINадминистратор группы
SUPER_MODERATORсупермодератор
MODERATORмодератор
EDITORмодератор-редактор
ANALYSTмодератор-аналитик
ACTIVEучастник группы
MAYBEвозможно, пойдёт (только для мероприятий)
PASSIVEнеучастник

Используя параметр viewer_type вы можете определять роль пользователя, например, чтобы отображать специальный интерфейс для администраторов и модераторов группы.

Дополнительные параметры

Чтобы при запуске передать в приложение произвольные параметры, используйте при генерации ссылки query часть ссылки после символа ?, укажите необходимые параметры.

Например,

https://ok.ru/group/1111111111111/app/77777777777?param1=545435345&param2=HELLO

Данные после ? будут переданы при запуске приложения в параметре custom_args.
Запуск приложения со своим кастомными параметрами может использоваться для запуска приложения из публикаций в ленте на конкретное состояние приложения. Например, на конкретный тест, анкету, услугу и т.д.

Отправка личных сообщений

Приложение может отправлять сообщения от имени сообщества, в котором оно установлено, используя Bot API.
Предлагаем такую схему работы:

  • Когда приложение будет запущено администратором группы (с viewer_type=ADMIN), запросить право на отправку личных сообщений от имени группы. Используя Javascript SDK, вызвать виджет запроса пермиссии. Пример вызова:

OKSDK.Widgets.askGroupAppPermissions(‘GROUP_BOT_API_TOKEN’, return_url);

  • Если администратор нажмет “Разрешить”, в API_callback (см. FAPI JS) или на return_url придет access_token для работы с BotAPI.
    Токен можно получить один раз и запомнить на стороне приложения, но администратор может в любой момент его инвалидировать через Настройки группы.

  • У пользователя запросить разрешение на отправку сообщений от группы, используя Javascript SDK вызвать виджет запроса пермиссии.
    Пример вызова:

OKSDK.Widgets.askGroupAppPermissions(‘MESSAGES_FROM_GROUP’, return_url);

  • Использовать Bot API для отправки сообщений пользователям.
    Для посылки сообщения необходимо отправить POST запрос в формате JSON на url (используя access_token полученный на первом шаге):

https://api.ok.ru/graph/me/messages/chat:C3ecb9d02a600?access_token=TOKEN

  • Отправка текстового сообщения
{
  "recipient": {
    "user_ids": ["user:1111111111111", "user:222222222222", "user:3333333333333"]
  },
  "message": {
    "text": "Привет"
  }
}
  • Отправка сообщения с фото
{
    "recipient": {
        "user_ids": ["user:1111111111111", "user:222222222222", "user:3333333333333"]
    },
    "message": {
        "attachment": {
            "type": "image",
            "payload": {
                "url": "https://st.mycdn.me/res/i/ok_logo.png"
            }
        }
    }
}

В одном запросе можно передать максимум 100 получателей сообщения. В ответ придёт JSON массив true/false, кому получилось отправить сообщение.

Публикация постов в ленты пользователей и группу

Для публикации постов в ленты пользователей и группу (в том числе с блоком ссылки на игру с картинкой), предлагаем использовать виджет публикации из Javascript SDK:

OKSDK.Widgets.post(
    return_url,
    {
        'attachment': {
            'media': [
                {'type': 'text', 'text': 'Hello, world!'},
                {
                    'type': 'link',
                    'url': 'http://ok.ru/group/11111111111/app/22222222222?param1=AAAAAAAAAAA',
                    'imageUrl': 'http//yoursite.com/640x320.png',
                    'buttonKey': 'ANSWER'
                }
            ]
        },
        'groupId': 777777777777
    }
);
  • Для публикации поста в группу, естественно, приложение должно быть запущено от имени админа или модератора группы.
  • Если не передавать groupId, то пост опубликуется в ленту пользователя.
  • Размер картинки должен быть не меньше 640x320. Для лучшего отображения на всех платформах без обрезаний рекомендуем использовать горизонтальные картинки с пропорцией сторон 2:1 (идеально именно 640x320).
  • Для публикации используется аналогичный формат параметра attachment, как и в методе mediatopic.post.
  • Значения для параметра buttonKey: RUN, PLAY, OPEN, LINK, VIEW, READ, CALL, LISTEN, JOIN, WRITE, MORE, BUY, BUY_TICKET, FILL, CONTACT, ANSWER, PASS_TEST, ENROLL

Передача заголовка, описания и картинки при публикации ссылки

Когда пользователь вставляет ссылку на групповое приложение при публикации тем, заметок и комментариев на ОК, либо делает постинг через виджет или метод API, веб-граббер ОК автоматически распознает, что это групповое приложение и пытается автоматически получить заголовок, описание и картинку, делая запрос к сайту приложения.

Заголовок блока ссылки составляется на основе тега: <title>,
описание - на основе тега: <meta name="desсription">,
картинка - на основе тега: <meta property="og:image" content="url"/>, либо из картинок, найденных в коде запрашиваемой страницы.

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

При запросе на сайт приложения за данными для блока ссылки, веб-граббер составит анонимный запрос без данных сессии и пользователя, передавая только следующие параметры:

ПараметрЗначение
grabber1
application_keyидентификатор приложения
group_idидентификатор группы
custom_argsкастомные параметры запуска
sigподпись запроса

При вызове добавляется параметр grabber=1. По этому признаку можно определить, что запрос с веб-граббера и приложению не обязательно выдавать весь html, ограничившись лишь title, description и image в head-е кода страницы.

Установка приложения с внешнего сайта по прямой ссылке

Вы можете разместить на своем сайте кнопку для установки приложения в группы пользователя. Используйте ссылку такого вида:

https://ok.ru/appinstall/APP_ID

, здесь APP_ID — ID приложения.

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

Переход по внешней ссылке из приложения (открытие в браузере из мобильного приложения)

Групповые приложения в наших Android/iOS мобильных приложениях открываются во WebView и визуально выглядят, как часть нашего приложения.
В большинстве приложений вызов каких-то страниц не во WebView, а в браузере - не понадобится.
Но иногда, например, когда приложение использует свой механизм оплаты - мы не разрешаем открывать внутри WebView такие страницы. Пользователь должен четко понимать, что он производит оплату не в Одноклассники, а напрямую в ваш сервис.

Такие страницы должны быть открыты на мобильных приложениях в браузере.
Для этого нужно:

  • При инициализации Javascript SDK передать параметр use_extlinks: true. Например:
var config = {
    app_id: 0,
    app_key: '',
    use_extlinks: true
};
OKSDK.init(config, function () {
    //on success
}, function (error) {
    //on error
});
  • Пометить ссылку классом js-sdk-extlink. Например:
<a href="http://my.payment.page/" class="js-sdk-extlink" target="_blank">Заплатить</a>

Модерация и размещение в каталоге

Список всех приложений, которые доступны для добавления в свои группы, администратор может просмотреть в разделе «Настройки» -> «Приложения».

В этот каталог попадают только одобренные приложения, которые соответствуют Правилам размещения групповых приложений.
Чтобы подать заявку на модерацию и разместить свое приложение в каталоге, создайте заявку на странице модерации с указанием платформы “Приложение групп”.
В заявке должна содержаться вся необходимая информация о приложении.