OpenSocial WAP Extension Specification

Keywords such as, "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" used in this document are to be interpreted as described in RFC2119. Domain name examples use RFC2606.

OpenSocial Containers have a standard design that provides JavaScript APIs for enabling rich web applications within a Web browser via an IFrame sandbox. This works well for the typical use case, since most modern web browswers have support JavaScript as well as IFrames. However, when running applications on WAP enabled devices, JavaScript & IFrames are not always available. As it stands today, OpenSocial Gadgets cannot run on most WAP devices. Many people access the Internet via mobile devices. There are even countries where Internet access is more available on mobile devices than PCs. The OpenSocial WAP Extension is defines how to support mobile devices which do not support JavaScript or IFrames. An application Requiring this extension uses OpenSocial RESTful APIs to retrieve OpenSocial Data, such as Social Data from a Social Networking Site (SNS.) This document describes an architecture and common features required to enable an OpenSocial WAP Server via this OpenSocial WAP Extension. An implementation wishing to support WAP devices SHOULD support features described in this document.

To be considered an OpenSocial WAP Container, a site must fulfill all the requirements for a Social API Server and those specified in this document.

The process flow is visualed in a diagram to better understand the interaction.

An OpenSocial Container MUST be able to fetch a gadget spec XML, and MUST be able to retrieve a Start URL written included in the ModulePrefs. A Gadget spec XML SHOULD be retrieved from the URL provided to the Container by the developer. OpenSocial Containers MUST parse the retrieved gadget file, and MUST get the Start URL written in the file. This Start URL is the destination of the first request sent when users launch an application. A view for WAP-enabled devices MUST have content type "wap." This is defined in the Gadget spec XML as a Content element which has an attribute "type" & value "wap." The Start URL is the value of the href attribute in the same Content element.

OpenSocial Containers MUST be able to accept requests from the cell-phone, and MUST be able to verify the content and also add necessary information. All requests from an application running on a mobile device SHOULD be processed by the OpenSocial Container. The content of the request accepted by the Container SHOULD be verified, and the OpenSocial Container SHOULD remove unnecessary information from the request. Requested information about the user MUST conform to section 2.5 of the Social Data specification. The application's unique identifier MUST be added to the request by the OpenSocial Container. There are cases that some information should not be relayed to the application, such a personally-identifable information. In this case, the OpenSocial Container SHOULD remove such information from the request. The OpenSocial Container MAY add additional information about the user to the request so it may leverage their social data.

OpenSocial Containers MUST be able to forward verified requests to an external server. If a request includes a URL parameter, the OpenSocial Container will forward the request to the server specified in the URL parameter. If the request does not include a URL parameter, the OpenSocial Container will default the request to the Start URL. At this point, user information and the application identifiers added from the previous phase are sent to the server. To validate the request, the OpenSocial Container SHOULD have a signature in the request.

An OpenSocial Container MUST be able to receive a response including content generated on a developer's external server. The received contents will be validated and transformed by the OpenSocial Container. For example, the OpenSocial Container MAY add a header and footer to the content. In addition, the OpenSocial Container MAY replace the URL written in the contents, such as an image, and MAY remove invalid codes (JavaScript code and etc). Furthermore, in order to allow usage of functions with a user flow specific codes SHOULD be replaced by the OpenSocial Container during this phase. If an external server has a slow response time, an OpenSocial Container MAY enforce a request timeout. If a response is not received within a reasonable amount of time, the OpenSocial Container will display an error page to the user.

The OpenSocial Container MUST send the staic page to the user's mobile device. The page which was rendered during the previous phase is then sent from the OpenSocial Container to the user's mobile device. The user may create an action on the page. As a result of this action, a new request is then sent to the OpenSocial Container.

This section describes the Gadget Spec XML of applications for mobile devices.

A view type is defined for applications that render on a mobile device. The view type is called "wap". This view is defined using a Content element in the Gadget spec XML, just like a Gadget view for a typical browser. The "wap" is specified as the attribute value of the Content element type. And, the Start URL is specified as the "href" attribute value. The Content element may not contain a body, since the server specified by the Start URL will generate the contents. Since the WAP extension is optional, application developers MUST declare the "wap" feature using a "Require" element. If the "wap" feature is not declared, its gadget will not render properly on WAP-enabled devices using the "wap" view type.

<?xml version="1.0" encoding="UTF-8"?> <Module> <ModulePrefs title="App for Cell-phone"> <Require feature="wap" /> </ModulePrefs> <Content view="any" type="wap" href="http://start.url/" /> </Module>

The view for cell-phones can co-exist with other views. At the same time, multiple Content elements holding other view attributes can be written in the Gadget spec XML.

The following code is an example having two Content elements: <?xml version="1.0" encoding="UTF-8"?> <Module> <ModulePrefs title="App for Cell-phone"> <Require feature="wap" /> </ModulePrefs> <Content view="mobile" type="wap" href="http://start.url/" /> <Content view="canvas" type="html"><[CDATA[ <div>Hello, world!</div> ]]></Content> </Module>

This wap extension supports Data Pipelining and Proxied Context. For instance, the content element which has the "wap" type can Data Pipelining tags to provide the Viewer, Owner and Friend information to an external server. For example:

<?xml version="1.0" encoding="UTF-8"?> <Module> <ModulePrefs title="App for Cell-phone"> <Require feature="wap" /> ... </ModulePrefs> <Content view="any" type="wap" href="http://start.url/"> <os:PeopleRequest key="vf" userid="@viewer" groupid="@friends" /> </Content> </Module> The results of the data pipelining requests will be sent to the URL specified in the href of the <Content> section as POSTed JSON data. This information can be used by an external server to render Social Data.

This section describes the request sent from an OpenSocial Container and the expected response.

The content of the request and the conditions to determine which target server to send requests by the OpenSocial Container are described here.

When the OpenSocial Container receives a request from mobile device, the forwarding target URL will differ depending on certain conditions. The conditions are described in the following: Request URL example Include url parameter? Forwarding target http://application.container/app_id No Start URL written on Gadget Spec XML. http://application.container/gadgets/ifr?url=http%3A%2F%2Fexternal.server%2gadget.xml&st=abcdefg&... No Start URL written on Gadget Spec XML specified by the url parameter included in the query parameters. http://application.container/app_id?url=http%3A%2F%2Fexternal.server%2Fpath1%2Fpath2 Yes http://external.server/path1/path2

The request sent from the mobile device will be forwarded to a developer's external server (Forward Request). The OpenSocial Container will add several parameters to the request while forwarding. Typically the parameters will include Social Data. The parameters typically added are the following: Name Type Description Required opensocial_owner_id Query parameter The ID of the user who owns the application accessed by the viewer. Yes opensocial_app_id Query parameter The ID of the application which the user is currently using. Yes opensocial_viewer_id Query parameter The ID of the user who is currently accessing to the application. Optional User-Agent Request Header The identifier to specify the device of the user. Yes X-Forwarded-For Request Header The IP address of the access origin. Optional The application developer can generate the appropriate content for the device by referencing the User-Agent request header. In addition, the OpenSocial Container MAY remove parameters included in the request sent to the mobile device, such as persoanlly-identifiable information. Such information SHOULD be removed by the OpenSocial Container to protect the user's privacy. If Data pipelining is used in the Content element, social data will be sent with the above parameters as JSON in POST body.

The OpenSocial Container expects to receive XHTML content responses. The format must be parseable by the OpenSocial Container. If the OpenSocial Container cannot parse the contents in XHTML format, the OpenSocial Container will return an error to the external server which generated the contents. The user's profile information retrieved from an OpenSocial RESTful API will be included in the contents of the external server. Also, the contents may change accordingly to the User-Agent parameter included in the request. Parts of the contents will be replaced by the OpenSocial Container. The purpose is to support User Flow functions and to replace the url parameter.

To ensure that the request from the mobile device always honored by the OpenSocial Container, the OpenSocial Container MUST replace URLs written in the content generated by the external server. Suchs URL include links for navigating around pages (i.e. a tag and form tag.) Application developers can write the specific URL they wish to retrieve on the external server as the value of the href or action attribute. For example, the URL is replaced similar to the following. Before:

<a href="http://external.server/path1/path2">Click!</a> <form action="http://external.server/path1/path2"> ... </form> After:

<a href="http://application.container/app_id/?url=http%3A%2F%2Fexternal.server%2Fpath1%2Fpath2">Click!</a> <form action="http://application.container/app_id/?url=http%3A%2F%2Fexternal.server%2Fpath1%2Fpath2"> ... </form>

With user flow functions, the specific URL schema written by the application developer will be replaced automatically to the complete URL by the OpenSocial Container. The purpose is to navigate the user to the page prepared by the OpenSocial Container. For example, when using the function to invite friends to an application, the URI schema will be replaced like the following. Before:

<a href="invite:friend?callback=http%3A%2F%2Fexternal.server%2Fpath1%2Fpath2">Invite!</a> After:

<a href="http://application.container/invite/friend?callback=http%3A%2F%2Fexternal.server%2Fpath1%2Fpath2">Invite!</a>

The OpenSocial Container will send a request to generate the contents to an external server. The external server must validate whether the sender of the request is the actual OpenSocial Container. Several methods to check the validness of the request exist. The most common method is to validate the request is using a signature. The external server can validate the request by checking the signature added by the OpenSocial Container. HMAC-SHA1, RSA-SHA1 etc, can be applied as methods for generating a signature. An example on how to generate a signature with HMAC-SHA1 is introduced in the section, [Generating the signature with OAuth].

The OpenSocial Container can pages which are pre-built by the OpenSocial Container. For example, if users want to invite friends to an application, the OpenSocial Container will navigate users to a page to select who to invite. After users finish selecting their friends, the OpenSocial Container will bring them back to the application's page. Such function is called 'User Flow functions'. Commonly used User Flow functions have been standardized in this specification. In addition, the OpenSocial Container can define a container-specific User Flow function. The URI schema is defined for each User Flow function to navigate users to an already parepared page. The OpenSocial Container MUST replace the URI schema to the page's URL.

The application developer MUST use the User Flow function under the following format:

[URI-schema]?[parameter1=value1]&[parameter2=value2]&... The following format can also be used when using a form tag of HTML:

The required parameters for all User Flow functions are the following: Name Description callback The URL of the redirecting target to go back after completing the User Flow function. This URL MUST be URI-escaped. If the OpenSocial Container wants to return the result of the process to the application, the result value is added as the query parameter to the URL specified by the callback parameter.

This section decribes commonly supported User Flow functions.

URI schema: invite:friends Description: The OpenSocial Container navigates users to the page where they can select friends they want to invite to the application. Parameters: Name Type Description callback String The target URL to return the user to the application after selecting friends by the user. Result values: Name Type Description invite_member User IDs separated by commna. The user's IDs which the user selected to invite. Example:

Request: <a href="invite:friends?callback=http%3A%2F%2Fexternal.server%2Fpath1%2Fpath2">Invite!</a> Redirecting target URL: http://external.server/path1/path2?invite_member=123,456,789