Viral Channels Supported on hi5

UPDATE: See Notifications and Emails sections. We have decided not to support VIEWER_FRIENDS and OWNER_FRIENDS as recipients but do continue to support an array of userids of up to 100 users.

On March 31st, a complete set of viral channels will be released, making 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 the wiki page regularly for more information.
 
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.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. Notifications will be limited to 5 per application per recipient per day.
 
Notifications are sent via the OpenSocial requestSendMessage method, with TYPE=NOTIFICATION

Notes:

• The recipients field may be a user id, an Array of user ids, OWNER, or VIEWER. OWNER_FRIENDS and VIEWER_FRIENDS will not be implemented at this time.
  
• The notification will only be sent to recipients that either have the app installed or are friends with the viewer.
• The array of userids passed as recipient may contain at most 100 ids.
• HTML content in notifications is sanitized. Only 'a' and 'br' tags are currently allowed.

Example:
var recipients = new Array();
recipients[0] = 1000;
recipients[1] = 1001;
var messageParams = {};
messageParams[opensocial.Message.Field.TYPE] = opensocial.Message.Type.NOTIFICATION;
var message = opensocial.newMessage('Notification text', messageParams);
opensocial.requestSendMessage(recipients, message, handleNotificationResponse);

 
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 per recipient per 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:

• The recipients field may be a user id, an Array of user ids, OWNER, or VIEWER. OWNER_FRIENDS and VIEWER_FRIENDS will not be implemented at this time.
  
• The notification will only be sent to recipients that either have the app installed or are friends with the viewer.
• The array of userids passed as recipient may contain at most 100 ids.
  
• HTML content in emails is sanitized. Only 'a','br', and 'strong' tags are currently allowed.

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', messageParams);
opensocial.requestSendMessage(opensocial.DataRequest.PersonId.OWNER, message, handleEmailResponse);

 
Friend Updates
 
Application developers have direct access to the friend updates on hi5. When a friend update is generated by a user, that update is displayed both on the generating user's profile page in the Recent Updates section, and on the generating user's friends' homepages in the Friend Updates section. Not all updates are published to all friends, but the publication rate is quite high. Currently we support 1 update at any given time per generating user per application, meaning a user could see at most the same number of updates on their homepage from an application as they have friends. We plan on supporting activity templates in a follow-up release, which will allow for better matching and aggregation and will allow us to change this limit.
 
Friend Updates are created via the OpenSocial requestCreateActivity method

Notes:

• hi5 currently supports the following fields: TITLE, BODY, MEDIA_ITEMS, FAVICON_URL, and 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.
• An update may have up to 5 MediaItems associated with it.
  
• hi5 support an additional MediaItem field, hi5.ActivityMediaItemField.LINK. This allows for individual MediaItems to have links to content.
• If the BODY is set, the URL field is a link attached to it. This URL supports view-params to an app canvas page. If unspecified and the BODY is set, this link defaults to the generating user's canvas page with no view-params.
  
• HTML content is sanitized. Only 'a' tags are currently allowed.

Example:

    var activityParams = {};
    activityParams[opensocial.Activity.Field.TITLE] = title;
   
    var mediaItems = {};
    var mediaItem = opensocial.newActivityMediaItem(opensocial.Activity.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.ObjectType.ACTIVITY_MEDIA_ITEM, hi5.ActivityMediaItemField.LINK)) {
      mediaItem.setField(hi5.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.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.
• 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, and feedback is appreciated at this time. You can find us on our irc channel at irc.freenode.net #hi5dev, and we'll have Feature Request submissions available on our developer site soon as well.