Hi5
From Triangle Wiki
Contents |
Introduction
Viral Actions
Invites
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!'));
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);
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);
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.
