OKSDK.Widgets.suggest

Метод для отправки рекомендации игры пользователю-друга с помощью виджета приглашения/рекомендации.

Рекомендацию можно отослать только пользователям, которые:

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

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

Сигнатура метода

OKSDK.Widgets.suggest(returnUrl, options)

Где:

  • returnUrl - URL, на который будет отправлен пользователь при закрытии окна с виджетом. Необязательный параметр;
  • options - дополнительные параметры виджета:
    • autosel - количество автоматически выбираемых друзей;
    • comment - текст приглашения по умолчанию;
    • custom_args - дополнительные параметры, которые будут переданы в оповещение, а далее в игру в неизменном виде;
    • popup - выполнять ли автоматическое центрирование и подгонку размеров окна;
    • nohead - отображать ли вверху виджета шапку Одноклассников;
    • state - дополнительные параметры, которые в неизмененном виде вернуться в скрипт-обработчик;
    • target - список пользователей, которых следует выбрать по умолчанию в общем списке;
    • target_only - показывать ли только друзей, переданных в параметре target;

Полное описание дополнительных параметров доступно здесь - виджет приглашения/рекомендации

Return URL message

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

Список параметров следующий:

  • code - код результата
    • OK - рекомендация отправлено успешно;
    • CANCELLED - отправка рекомендации отменена пользователем;
    • PARAM_SIGNATURE и др. коды - произошла ошибка отправки. В таком случае смотрите описание ошибки на странице обработка ошибок
  • selected - список ID пользователей, которым было отослано приглашение;
  • result - объект с результатом работы виджета. Содержит в себе все остальные служебные параметры из URL;
  • error_code - код ошибки;
  • error_msg - описание ошибки;
  • sig - подпись запроса для валидации.

Пример при успешной отправке рекомендации

https://return.url/
   ?code=OK
   &result={"code":"OK","selected":"[1234567890]"}
   &selected=[1234567890]
   &sig=297a083bc6a3e15*****c08f8ff52cc3

Пример при отмене отправки

https://return.url/
   ?code=CANCELLED
   &error_code=12
   &error_msg=Operation was cancelled by user
   &message=Operation was cancelled by user
   &result={"error_code":"12","code":"CANCELLED","error_msg":"Operation was cancelled by user","message":"Operation was cancelled by user"}
   &sig=769bab70551*****5551182e5b1e7e22

Пример при ошибке отправки

https://return.url/
   ?code=PARAM_SIGNATURE
   &error_code=104
   &error_msg=Bad signature
   &message=Bad signature
   &result={"error_code":"104","code":"PARAM_SIGNATURE","error_msg":"Bad signature ","message":"Bad signature "}

Window postMessage

Если при вызове виджета не был указан параметр returnUrl, то после выхода пользователя из окна виджета (успешная отправка рекомендации, отмена отправки, ошибка) в родительское окно будет отправлен postMessage с информацией о результате работы виджета.

Параметры сообщения (message.data) аналогичны тем, что передаются в параметре result при указании return URL.

Пример при успешной отправке рекомендации

{
    "code": "OK",
    "selected": "[1234567890]"
}

Пример при отмене отправки

{
    "error_code": "12",
    "code": "CANCELLED",
    "error_msg": "Operation was cancelled by user",
    "message": "Operation was cancelled by user"
}

Пример при ошибке отправки

{
    "error_code": "104",
    "code": "PARAM_SIGNATURE",
    "error_msg": "Bad signature ",
    "message": "Bad signature "
}

Таким образом, можно задать eventListener, который будет каким-то образом обрабатывать это сообщение:

    window.addEventListener('message', function (widgetMessage) {
        console.log(JSON.stringify(widgetMessage.data));
        // обрабатываете сообщение от виджета здесь
    }, false);
    

Пример вызова

OKSDK.Widgets.suggest(
    null,
    {
        "autosel": 3,
        "nohead": false,
        "popup": true
    }
)

В результате вызова метода пользователю будет показано окно с формой отправки рекомендации:

Виджет рекомендации игры