Lesson 13: Promote your Gadget with Invite and Suggest

From VZ Developer Wiki
Jump to: navigation, search

General Guidelines | XML Specification | Features | Views | JavaScript API | REST API | Tutorials | OAuth

Lesson 12: Using the OpenSocial REST API Back to overview Lesson 14: Tracking of user interaction

To make your app successful it is important that your users are able to invite their friends to install it.

For historical reasons there are three methods available, which basically do the some, but defer only in the parameters they support:


An invitation can be send either through the messaging service to individual users or to the users feed, so that all of the user's friends will receive the invitation. When you call one of the methods above the user will se a dialog, which offers him both options and lets him personalize his invitation.

The invitation will contain your app's icon, title and description automatically (see Gadgets_XML#ModulePrefs).

Additionally you have the possibility to add:

  • a custom message
  • a custom icon
  • predefined recipients
  • a unique token

If you registered your gadget to the invite event (see Gadgets_XML#ModulePrefs.2FLink for details) you will get a callback to your backend with the OpenSocial IDs of the invited users and the token you created. There you can match token and users and wait for the users to accept the invitation.

vz.invite.getUniqueToken(function(token) {
      vz.invite.create(token, 'Install this app and get a present', 'http://test/present.png');

Once the invitation dialog has been successfully completed by the user on the container side, VZ will send a callback request to the endpoint at your backend specified in the corresponding ModulePrefs Link element. The request to this endpoint is signed with an OAuth signature. You should verify this signature in your backend:

//require the php OAuth library
require_once "oauth.php";

$request = OAuthRequest::from_request();
$server = new OAuthSignatureMethod_HMAC_SHA1();
$consumer = new OAuthConsumer('key', 'secret');
$return = $server->check_signature($request, $consumer, null, $_GET['oauth_signature']);

if (! $return) {
  die('invalid signature');

$body = file_get_contents('php://input');

$event = json_decode($body, true));

echo $event['from_id'];
echo $event['token'];

foreach ($event['users'] as $user) {
  echo $user['id'];
  echo $user['has_installed'];

  • Lesson 13: Promote your Gadget with Invite and Suggest