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)PurposeDescription
WidgetInviteinvitationInvites non-playing friends to the game
WidgetSuggestrecommendationSends a game recommendation to friends. Can be sent to those who are playing the game as well.

To call it, open a new browser window (or iframe) with a specially formulated URL:

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

Values of all URL arguments must be encoded.

ParameterRequiredDescription
st.access_tokenNoIn case of an OAuth application access_token must be passed
st.appYesApplication id
st.autoselNoNumber of friends that should be selected automatically rather than by the user. 0 by default.
st.commentNoValues of the text field of default invitation
st.custom_argsNoAdditional parameters that will be passed when the target user opens the application after accepting the invitation
st.popupNoExecute automated centering and adjusting of the window size.
Available values: on/off (by default)
st.returnNoURL which the execution result will be redirected to. If not indicated, the posting result will be transmitted via HTML5 postMessage.
st.signatureYesReuquest signature (see the calculation algorithm below)
st.stateNoAdditional 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.targetNoA list of users who should be selected by default in the general list
st.target_onlyNoIf 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, its part is not indicated.

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

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.