Виджет приглашения и рекомендации игр

Для внешних приложений (сайтов, нативных или же html5 мобильных игр) существует особый механизм привлечения в игру с помощью виджетов:

Название (widget_id)НазначениеОписание
WidgetInviteприглашениеПриглашает не играющих на данный момент друзей в игру
WidgetSuggestрекомендацияОтсылает рекомендацию игры друзьям. Может быть отослано в том числе играющим в игру.

Для вызова необходимо открыть новое окно браузера (или iframe) со специально сформированным URL:

https://connect.ok.ru/dk?st.cmd={widget_id}&st.app={application_id}&st.signature={signature}&st.return={return_url}&st.popup={popup}

Значения всех аргументов URL должны быть закодированы.

ПараметрОбязательныйОписание
st.access_tokenНетВ случае OAuth приложения - требуется указать access_token
st.appДаИдентификатор приложения (application id)
st.autoselНетКоличество друзей, которых следует выбрать автоматически за пользователя. По умолчанию - 0.
st.commentНетЗначения поля ввода текста приглашения по умолчанию
st.custom_argsНетДополнительные параметры которые будут переданы при открытии приложения когда целевой пользователь примет приглашение
st.popupНетВыполнять автоматическое центрирование и подгонку размеров окна.
Возможные значения: on/off (по умолчанию)
st.returnНетURL на который будет совершён редирект с результатом выполнения. Если не указан, то результат публикации будет передан через HTML5 postMessage.
st.signatureДаЦифровая подпись запроса (см. алгоритм подсчета ниже)
st.stateНетДополнительные параметры, которые в неизмененном виде вернуться в скрипт-обработчик. Рекомендуется использовать этот параметр вместо GET параметров в st.return так как параметр участвует в подписи что исключает его подделку
st.targetНетСписок пользователей, которых следует выбрать по умолчанию в общем списке
st.target_onlyНетЕсли установлен в булевское значение - то покажет только друзей, переданных в параметре st.target.
Возможные значения: on/off (по умолчанию)

Рассчет подписи запроса st.signature

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

md5("st.returnUrl=" + return_url + "st.state=" + state + secretKey);

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

{st.return}?code={code}&selected=[3154325,435345]&sig={signature}

В противном случае будет отправлено HTML5 postMessage-сообщение c JSON объектом:

{
	"code": "OK",
	"selected": [521461346,2141352145],
	"sig": "f7af00de7381be7c0866085d909a934e"
}

Если пользователь нажимает кнопку “Отмена”, то в ответе будут code = CANCELLED.