Games invitations and recommendations widget
For external applications (sites, native or html5 mobile games), there exists a special user attraction mechanism using widgets:
| Name (widget_id) | Purpose | Description |
|---|---|---|
| WidgetInvite | invitation | Invites non-playing friends to the game |
| WidgetSuggest | recommendation | Sends a game recommendation to friends. Can be sent to those who are playing the game as well. |
Widget request
To call it, open a new browser window (or iframe) with a specially formulated URL:
?st.cmd={widget_id}
&st.app={application_id}
&st.signature={signature}
&st.return={return_url}
&st.popup={popup}
&st.nohead={nohead}
Values of all URL arguments must be encoded.
Parameters list
| Parameter | Required | Description |
|---|---|---|
| st.access_token | No | In case of an OAuth-application access_token must be passed |
| st.app | Yes | Application id |
| st.autosel | No | Number of friends that should be selected automatically rather than by the user. 0 by default |
| st.comment | No | Text field value of default invitation |
| st.custom_args | No | Additional parameters that will be passed when the target user opens the application after accepting the invitation |
| st.popup | No | Execute automated centering and adjusting of the window size. Available values: on/off (by default) |
| st.nohead | No | Do not display Odnoklassniki header. Possible values: on/off (default) |
| st.return | No | URL which the execution result will be redirected to. If not indicated, the posting result will be transmitted via HTML5 postMessage. |
| st.signature | Yes | Request signature (see the calculation algorithm below) |
| st.state | No | Additional parameters that will be returned unaltered to the script processor. It is recommended to use this parameter instead of GET parameters in st.return, as the parameter participates in the signature, which rules out its falsification |
| st.target | No | A list of users who should be selected by default in the general list |
| st.target_only | No | If set to a Boolean value, shows only friends that are indicated in the st.target parameter. Available values: on/off (by default) |
Calculating request signature st.signature
When transmitting the st.access_token parameter, session_secret_key is used as a secret key, otherwise the application secret key is used.
No value should be encoded.
When an operative parameter is absent, it’s part is not indicated.
md5("st.returnUrl=" + return_url + "st.state=" + state + secretKey);Result handling
If the request includes the st.return parameter, then after posting the user will be redirected to URL indicated in the parameter.
{st.return}?code={code}&selected=[3154325,435345]&sig={signature}
Otherwise, an HTML5 postMessage with a JSON object will be sent:
{
"code": "OK",
"selected": [521461346,2141352145],
"sig": "f7af00de7381be7c0866085d909a934e"
}If the user clicks the “Cancel” button, the answer will have code = CANCELLED.