Документация

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

• Создание приложения — перед началом разработки, прочитайте как создать собственное приложение в Одноклассниках. При регистрации приложения нужно указать платформы: 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/app/setup и нажмите кнопку Добавить платформу.
4. Для регистрация приложения для групп укажите платформы: Web(HTML), HTML(Mobile) и «Групповое» и/или «Пользовательское» приложение. Укажите размеры приложения (они будут применяться для открытия на полной версии сайта).
5. Указать официальную группу приложения и ID топика, в котором подробно рассказывается, как пользоваться и настроить приложение, рассматриваются популярные примеры использования.
6. Указать специфичные для приложения параметры: кнопка запуска по-умолчанию, возможность открывать на отдельной странице, устанавливать по прямой ссылке.

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

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

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

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

В заявке должна содержаться вся необходимая информация о приложении.

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

Требования к иконкам приложения

Если вам необходимо сменить иконку вашего приложения, то будет недостаточно просто переложить .jpg или .png на вашем сервере. Чтобы изменения были видны на портале, в настройках вашего приложения также должна быть изменена ссылка (например, добавлен/изменен GET-параметр).

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

• в формате JPEG или PNG
• не на белом фоне
• без теней, закруглений по углам или обводок
• без эмблем “New”, “Exclusive” и подобных
• Иконка вашего приложения не должна быть визуально похожа на иконку уже запущенного приложения. Степень похожести определяет Администрация сайта.

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

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

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

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

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

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

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

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

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

Например,

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

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

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

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

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

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

• Использовать Bot API для отправки сообщений пользователям.
  Для посылки сообщения необходимо отправить POST запрос в формате JSON на url (используя access_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"/>, либо из картинок, найденных в коде запрашиваемой страницы.

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

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

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

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

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

, здесь 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>