OpenSocial Mobile Extension Specification (draft)

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.

In OpenSocial specification version 1.0, JavaScript APIs for developing applications that run on Web browsers are provided. These APIs are available only if JavaScript codes are supported. However, most Web browsers available on cell-phones based on WAP currently do not support JavaScript and an iframe tag. Many people access the Internet from their cell-phones and use social networking services. There are even countries where access to the Internet is seen more from cell-phones than from PCs. In order for social applications to further develop, we CANNOT ignore support to cell-phones based on WAP. OpenSocial Mobile Extension specification is a profile for cell-phones which do not support JavaScript codes. An application developed by this profile uses an OpenSocial RESTful API to retrieve the social graph of a SNS. This document describes an architecture and features commonly provided in OpenSocial Mobile Extension. SNS that want to provide a social application for cell-phones SHOULD support features described in this profile.

In order to become a compliant Application Container, a server MUST be able to satisfy the requests defined in this section.

For a better understanding this process flow is introduced below.

Application Containers MUST be able to fetch a gadget spec file, and MUST be able to retrieve a Start URL written in the file. Gadget spec file SHOULD be retrieved from the URL provided to the Container by the developer. Application Containers MUST parse the retrieved gadget XML 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. The view for WAP-phone device in this profile has the content type "wap". Application Container finds the Content element which has the "wap" value as the value of the attribute "type". The Start URL is written as the value of the href attribute. Generally, Application Container will download the Gaget spec file when the developer registers the application and Application Container retrieves the Start URL from the Gadget spec file at same time.

Application Containers MUST be able to accept requests from the cell-phone, and MUST be able to verify the content and also add necessary information. Basically, all requests from an application running on a cell-phone SHOULD be processed by the application container. The content of the request accepted by the Container SOULD be verified, and Application Container SHOULD remove unnecessary information from the request. And, information of the user who activated the application and the application's ID MUST be added to the request by the Application Container. For example, there is a case that some IDs or identifiers which can specify the individual and should not send them to the application developer is sent from the cell-phone to the application container. In this case, the application container needs to remove these information from the request. If these information is sent to the application developer, it may be told a information leaking. Application Container MUST add information of the user to the request so that the application has a capability of a social. The application developer can know who do use the application by retrieving the user ID included the request.

Application Containers MUST be able to forward verified requests to an external server of the developer used for building contents. If a request includes a URL parameter, the application container will forward the request to the server specified in the URL parameter. Also, if the request does not include a URL parameter, the application container will forward the request to the Start URL. At this timing, user information and the application ID added during the previous phase are sent to the server. In order for the developer's server to be able to verify whether the request is valid or not, the application container SHOULD have a signature in the request.

Application Container MUST be able to receive a response including content built by the developer's external server. The received contents will be validated and transformed by the application container. For example, the application container MAY add a header and footer to the content. In addition, the application container MAY replace the URL written in the contents, such as of 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 application container during this phase. The response time from the developer's external server may severely delay. Application Container MAY limit the available length of response time. If the response is not received within the valid period of time, the application container will display the error page to the user.

The application container MUST send the fixed page to the user's cellphone. The page which has been fixed during the previous phase is then sent from the application container to the user's cell-phone. The user will take a new action from the displayed page. As a result of this action, a new request is then sent to the application container.

This section describes the specification of Gadget Spec file of social applications for cell-phones.

In this specification, a special view is defined for social applications for the cell-phones. The view type is called "wap". This view is defined using a Content element in the Gadget spec file. Thus, this definition is the same with the definition of Gadgets for PC. 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.

<?xml version="1.0" encoding="UTF-8"?> <Module> <ModulePrefs title="App for Cell-phone"> </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 file.

The following code is the example to have two Content elements: <?xml version="1.0" encoding="UTF-8"?> <Module> <ModulePrefs title="App for Cell-phone"> </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 the Data Pipelining and Proxied Context. For instance, the content element which has the "wap" type can have some tags using Data Pipelining to provide the viewer, owner and the friends information for the external server. The sample code is like following:

<?xml version="1.0" encoding="UTF-8"?> <Module> <ModulePrefs title="App for Cell-phone"> ... </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 href of the <Content> section as POSTed JSON data. These information will be used by the external server to render the social data.

This section describes the request sent from the application container and the expected response.

The content of the request and the conditions to determin which target server to send requests by the application container are described here.

When the application container receives a request from the cell-phone, the target to forward to will differ depending on the condition. In other words, it is decided based on whether a url parameter is included or not in the request. The condition is described in the following: Request URL example Include url parameter? Forwarding target http://application.container/app_id No Start URL written on Gadget Spec file. http://application.container/gadgets/ifr?url=http%3A%2F%2Fexternal.server%2gadget.xml&st=abcdefg&... No Start URL written on Gadget Spec file 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 cell-phone will be forwarded to the external server of the developer (Forward Request). The application container will add several parameters to the request, when forwarding the request. The purpose to add these parameters is to add socialness to the application. The parameters generally often 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 suitable contents for the device the user is using by referencing the User-Agent request header. In addition, the application container MAY remove several parameters included in the request received request from the cell-phone. At times the request may include privacy information in addition to ID used within the SNS to identify an individual. Such information SHOULD be removed by the application container to protect the user's privacy. If the Data pipelining is used in the Content element, the social data will be sent with the above parameters as JSON format included the POST body.

The application container expects to receive XHTML content responses. The format must be parseable by the application container. If the application container cannot parse the contents in XHTML format, the application 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 application container. The purpose is to support User Flow functions and to replace the url parameter.

To assure that the request from the cell-phone always get through the application container, the application container MUST replace URLs written in the content generated by the external server. The tags for navigating pages (i.e. a tag and form tag) are the target tags of such replacement. 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 simillar 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 application container. The purpose is to navigate the user to the page prepared by the application 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 application container will send a request to generate the contents to the external server. The external server must validate whether the sender of the request is the actual application container or not. Several methods to check the validness of the request exist. The most popular adopted method is the method of giving a signature to the request. The external server can validate the request by checking the signature added by the application 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 application container can provide functions with pages which the application container have already prepared. For example, if users want to invite friends to an application, the application container will navigate users to the page to select who to invite. After users finish selecting their friends, the application container will bring back users 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 application 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 application 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 application 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.

In this section, specifications of commonly supported User Flow functions are described.

URI schema: invite:friends Description: The application 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