hi5 Viral Channels

hi5 provides multiple viral channels for applications, to make it easier for developers to distribute applications to the hi5 community. Please note that policies on viral distribution are subject to change, so please check this page and the page on Application Guidelines regularly for more information.

The viral channels that we provide are:

  1. Invitations
  2. Notifications
  3. E-mail Messages
  4. Friend Updates

hi5 implements limits for the number of messages sent on each viral channel, to control abusive applications. These limits are subject to change. They are set differently for each application based on how engaged users are with the messages sent by the application via each viral channel and how much negative feedback that application receives from its users.

Invitations

Invitations appear under the “Requests” header, at the top left corner of a user’s homepage. A user of an application has the ability to invite their friends to install the application. There are no limits to how many friends a user can invite. We have built a standard User Interface for selecting friends. Friends who receive an invitation have the option to block an application or report it as spam. A user can only receive an invitation to an application from the same friend once. Any installed application has Invite links on the profile module and the top of the canvas page. An application may also request to forward the user to the invite page at any point via the OpenSocial requestShareApp method. 

opensocial.requestShareApp(recipients, reason, opt_callback)

Notes:

  • The only valid value for recipients is opensocial.DataRequest?.Group.VIEWER_FRIENDS. There is no limit to the number of friends a user may select to invite, but there is no Select All feature in the form.
  • As noted in the spec, containers should either refresh the application or call the requested callback on completion of this request. Since we always refresh the gadget, the callback is ignored.
  • reason should be of type opensocial.Message, and the text should be in the BODY field. If set, the reason will be displayed in the invite form.

Example: 

requestShareApp(opensocial.[wiki:DataRequest].Group.VIEWER_FRIENDS, opensocial.newMessage('Gifts are more fun with friends!'));

Notifications

Notifications appear under the “Requests” header, on the top left corner of a user’s homepage. Here, all notifications are aggregated and displayed as a single number. If an application triggers a notification (e.g. “You have received a gift from John”), this will be sent to the recipient of the action. Notifications can be sent to users who have the application installed and users who don’t have the application installed as yet.

Notification Limits

Notifications will be limited to a certain number per application per recipient per day, and a maximum of 100 recipients will be allowed per request.

Notifications are sent via the OpenSocial requestSendMessage method, with TYPE=NOTIFICATION

Notes:

  • As specified the recipients field may be a user id, an Array of user ids, or any of OWNER, VIEWER, OWNER_FRIENDS, and VIEWER_FRIENDS. However, the notification will only be sent to recipients that either have the app installed or are friends with the viewer.

Example: 

var messageParams = {}; messageParams[opensocial.Message.Field.TYPE] = opensocial.Message.Type.NOTIFICATION; var message = opensocial.newMessage('Notification text', params); opensocial.requestSendMessage(opensocial.[wiki:DataRequest].Group.VIEWER_FRIENDS, message);

E-mail Messages

Applications can send email messages to users as long as the user has the application installed and the user has given the application the permission to do so. Currently, the e-mail limit is 1 email message per app/user/day. The user will have the option to unsubscribe from the email message.

Notifications are sent via the OpenSocial requestSendMessage method, with TYPE=EMAIL

Notes:

  • As specified the recipients field may be a user id, an Array of user ids, or any of OWNER, VIEWER, OWNER_FRIENDS, and VIEWER_FRIENDS. However, the notification will only be sent to recipients that either have the app installed or are friends with the viewer.

Example: 

var messageParams = {}; messageParams[opensocial.Message.Field.TYPE] = opensocial.Message.Type.EMAIL; messageParams[opensocial.Message.Field.TITLE = 'Subject of email'; var message = opensocial.newMessage('Body of email', params); opensocial.requestSendMessage(opensocial.[wiki:DataRequest].[wiki:PersonId].OWNER, message);

Friend Updates

Application developers have direct access to the friend updates on hi5. These friend updates are displayed on the user’s friend’s homepage. Friend Updates are created via the OpenSocial requestCreateActivity method

Notes:

  • hi5 currently supports the following fields: TITLE, BODY, MEDIA_ITEMS, FAVICON_URL
  • USER_ID, APP_ID, and POSTED_TIME are inferred from the request and if set are ignored by hi5
  • Priority, although required by the OpenSocial spec, is currently ignored by hi5
  • FAVICON_URL is used as the icon in the Friend Updates feed if specified. If unspecified, we will use the icon specified in the application's ModulePrefs?. If that is also unspecified, we will use the standard hi5 gear icon.
  • hi5 support an additional MediaItem? field, hi5.ActivityMediaItemField?.LINK. This allows for individual MediaItems? to have links to content.

Example: 

var activityParams = {}; activityParams[opensocial.Activity.Field.TITLE] = title;

var mediaItems = {}; var mediaItem = opensocial.newActivityMediaItem(opensocial.Activity.[wiki:MediaItem].Type.IMAGE, viewer.getField(opensocial.Person.Field.THUMBNAIL_URL)); // Add a media item link if supported if(gadgets.util.hasFeature('hi5') && opensocial.getEnvironment().supportsField(opensocial.Environment.[wiki:ObjectType].ACTIVITY_MEDIA_ITEM, hi5.[wiki:ActivityMediaItemField].LINK)) {
    mediaItem.setField(hi5.[wiki:ActivityMediaItemField].LINK, viewer.getField(opensocial.Person.Field.PROFILE_URL));
  } mediaItems.push(mediaItem); activityParams[opensocial.Activity.Field.MEDIA_ITEMS] = mediaItems;

var activity = opensocial.newActivity(activityParams); opensocial.requestCreateActivity(activity, opensocial.[wiki:CreateActivityPriority].HIGH);

General Notes

  • All viral channels are monitored and may be subject to spam control.
  • All viral requests are limited to the 'canvas' view. Requests from 'profile' or 'preview' views will return an opensocial.ResponseItem? with error code set to to opensocial.ResponseItem?.Error.NOT_IMPLEMENTED.
  • Users have the option of disallowing applications from sending Friend Updates, Notifications, and Emails on their behalf.
  • If an application is blocked by the user, none of the viral channels will reach the user.
  • HTML content in messages is sanitized. Only 'a' tags are currently allowed for linking.
  • Successful requestSendMessage requests will return an opensocial.ResponseItem? whose data field will contain a list of users who received the message. This is not yet available in sanbox but is expected to be ready for launch, details to come.

As mentioned above, these policies are subject to change. If a particular channel isn't working for you, feel free to send us feedback at api-request@… or platform-help@…. You can join us at any time at on our irc channel at irc.freenode.net #hi5dev.

Close