opensocial-and-gadgets-spec@googlegroups.com

This document defines additional APIs to add social capabilities to a Core Gadget container. General OpenSocial social networking REST XML Extensible Markup Language JSON JavaScript Object Notation Atom

Domain name examples use RFC2606.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.

OpenSocial provides three ways for gadgets to access social data. First, the JavaScript API contains methods in the osapi.* namespace which map to the services defined in the Social API Server Specification. Second, Data Pipelining is a declarative syntax for specifying the social data a gadget will need, allowing the container to prefetch data for faster gadget rendering. Third, Templating provides several tags to accomplish common tasks, like displaying the UI for selecting friends from a list.

For an overview of the patterns used in the following reference, see the introduction to the JavaScript API Reference in

Service object with functions that map to the People service.

<static> { osapi.Request } osapi.people.get(params) Builds a request to retrieve information from the People service. When no parameter is specified, the container MUST use the default values, returning the the viewer's information. This method takes a single parameter, which is a JavaScript object representing the parameters defined by the People service's get method. A osapi.Request to retrieve information from the People service. Executing this request MUST return a Person object or a Collection of Person objects.

<static> { osapi.Request } osapi.people.getViewer(params) A convenience over osapi.people.get() that builds a request to retrieve the viewer, as specified in the security token, from the People service. This method takes a single parameter, which is a JavaScript object representing the parameters defined by the People service's get method, except that the value for the userId parameter is set to '@viewer'. A osapi.Request to retrieve information from the People service. Executing this request MUST return a Person object representing the viewer.

<static> { osapi.Request } osapi.people.getViewerFriends(params) A convenience over osapi.people.get() that builds a request to retrieve the viewer's friends, as specified in the security token, from the People service. This method takes a single parameter, which is a JavaScript object representing the parameters defined by the People service's get method, except that the value for the userId parameter is set to '@viewer' and the groupId parameter is set to "@friends". A osapi.Request to retrieve information from the People service. Executing this request MUST return a Collection of Person objects representing the viewer's friends.

<static> { osapi.Request } osapi.people.getOwner(params) A convenience over osapi.people.get() that builds a request to retrieve the owner, as specified in the security token, from the People service. This method takes a single parameter, which is a JavaScript object representing the parameters defined by the People service's get method, except that the value for the userId parameter is set to '@owner'. A osapi.Request to retrieve information from the People service. Executing this request MUST return a Person object representing the owner.

<static> { osapi.Request } osapi.people.getOwnerFriends(params) A convenience over osapi.people.get() that builds a request to retrieve the owner's friends, as specified in the security token, from the People service. This method takes a single parameter, which is a JavaScript object representing the parameters defined by the People service's get method, except that the value for the userId parameter is set to '@owner' and the groupId parameter is set to "@friends". A osapi.Request to retrieve information from the People service. Executing this request MUST return a Collection of Person objects representing the owner's friends.

A Person request, the most basic example: osapi.people.getViewer().execute(function(result) { if (!result.error) { alert('Your name is ' + result.displayName + '!'); } });

A Person request with a JSON request parameter object specifying which fields to retrieve: osapi.people.getViewer({fields: ['displayName', 'birthday']}).execute(function(result) { if (!result.error) { alert('Your name is ' + result.displayName + '!'); alert('Your birthday is ' + result.birthday + '!'); } });

A simple example to request the owner's friends: osapi.people.get({userId: '@owner', groupId: '@friends'}).execute(function(result) { if (!result.error) { alert('You have ' + result.totalResults + ' friends'); } });

An example that illustrates all available request parameters: var params = { userId: "@owner", groupId: "@friends", fields: "@all", count: 10, startIndex: 0, startPage: 0 }; osapi.people.get(params).execute(function(result) { if (!result.error) { alert('You have ' + result.totalResults + ' friends'); } });

Service object with functions that map to the Activities service.

<static> { osapi.Request } osapi.activities.get(params) Builds a request to retrieve information from the Activities service. When no parameter is specified, the container MUST use the default values, returning the viewer's activities. This method takes a single parameter, which is a JavaScript object representing the parameters defined by the Activities service's get method, except that the 'appId' parameter can not be changed from "@app". A osapi.Request to retrieve information from the Activities service. Executing this request MUST return a Activity object or a Collection of Activity objects.

<static> { osapi.Request } osapi.activities.get(params) Builds a request to create a new activity using the Activities service. This method takes a single parameter, which is a JavaScript object representing the parameters defined by the Activities service's create method, except that the 'appId' parameter can not be changed from "@app". This parameter is REQUIRED and MUST contain the 'activity' property. A osapi.Request to retrieve information from the Activities service. Executing this request MUST attempt to create the specified Activity and return the newly-created Activity object if successful.

A simple example to retrieve the activities of the viewer's friends: osapi.activities.get({userId: '@viewer', groupId: '@friends', count: 20}).execute(myCallback);

An example illustrating all available request parameters for osapi.activites.get(): var params = { userId: "@me", groupId: "@self", activityIds = ["YYYYYYY", "ZZZZZZZ"], fields: "@all", count: 10, startIndex: 0, startPage: 0 }; osapi.activities.get(params).execute(myCallback);

A simple example to create an activity for the viewer: osapi.activities.create({userId: '@viewer', activity: {title: 'Hello!', url: 'http://mysite.com'}}).execute(myCallback);

An example illustrating all available request parameters for osapi.activites.create(): var params = { userId: "@viewer", groupId: "@self", activity: {title: 'Hello!', url: 'http://mysite.com'} }; osapi.activities.create(params).execute(myCallback);

Service object with functions that map to the AppData service.

<static> { osapi.Request } osapi.appdata.get(params) Builds a request to retrieve information from the AppData service. This method takes a single parameter, which is a JavaScript object representing the parameters defined by the AppData service's get method, except that the 'appId' parameter can not be changed from "@appId". This parameter is REQUIRED, and MUST include the 'keys' property. A osapi.Request to retrieve information from the AppData service. Executing this request MUST return a JavaScript object where each of the requested keys is a property, and each property is populated with the corresponding value that was persisted using the AppData service.

<static> { osapi.Request } osapi.appdata.update(params) Builds a request to update information stored in the AppData service. This method takes a single parameter, which is a JavaScript object representing the parameters defined by the AppData service's update method, except that the 'appId' parameter can not be changed from "@appId". This parameter is REQUIRED and MUST include the 'data' property. A osapi.Request to retrieve information from the AppData service. Executing this request MUST overwrite the existing AppData on the server, but does not return any values.

<static> { osapi.Request } osapi.appdata.delete(params) Builds a request to delete information stored in the AppData service. This method takes a single parameter, which is a JavaScript object representing the parameters defined by the AppData service's delete method, except that the 'appId' parameter can not be changed from "@appId". This parameter is REQUIRED and MUST include the 'keys' property. A osapi.Request to retrieve information from the AppData service. Executing this request MUST remove the specified key/value pairs from the server and return them as a JavaScript object.

A simple example to retrieve, update, and delete a piece of app data: osapi.appdata.get({userId: '@viewer', groupId: '@friends', keys: ['gifts']}).execute(myGetCallback); osapi.appdata.update({userId: '@viewer', data: {gifts: 'a crazed monkey'}}).execute(myUpdateCallback); osapi.appdata.delete({keys: ['gifts']}).execute(myDeleteCallback)

An example illustrating all available request parameters for osapi.appdata.get(): var getParams = { userId: "@viewer", groupId: "@friends", keys: ['gifts', 'wishlist'] }; osapi.appdata.get(getParams).execute(myGetCallback);

An example illustrating all available request parameters for osapi.appdata.update(): var updateParams = { auth: {"default" : null, "type" : "AuthToken"}, userId: "@viewer", groupId: "@friends", data: {gifts: 'a crazed monkey', wishlist: 'a banana peel'} }; osapi.appdata.update(updateParams).execute(myUpdateCallback);

An example illustrating all available request parameters for osapi.appdata.delete(): var deleteParams = { userId: "@viewer", groupId: "@friends", keys: ['gifts', 'wishlist'] }; osapi.appdata.delete(deleteParams).execute(myDeleteCallback)

Service object with functions that map to the Groups service.

<static> { osapi.Request } osapi.groups.create(params) Builds a request to create a group via the Groups service. This method takes a single parameter, which is a JavaScript object representing the parameters defined by the Groups service's create method, except that the 'userId' property can not be changed from the default value of '@me'. This parameter is REQUIRED, and MUST include the 'group' property. A osapi.Request to create a group via the Groups service. Executing this request MUST create a group and return the newly created group.

<static> { osapi.Request } osapi.groups.get(params) Builds a request to get a group or groups via the Groups service. This method takes one parameter, which is a JavaScript object representing the parameters defined by the Groups service's get method, except that the 'userId' property can not be changed from the default value of '@me'. This parameter is REQUIRED, and MUST include the 'message' property. A osapi.Request to get a group or groups via the Groups service. Executing this request MUST return a Group or a Collection of Groups.

<static> { osapi.Request } osapi.groups.update(params) Builds a request to update a group via the Groups service. This method takes a single parameter, which is a JavaScript object representing the parameters defined by the Groups service's update method, except that the 'userId' property can not be changed from the default value of '@me'. This parameter is REQUIRED, and MUST include the 'group' property. A osapi.Request to update a group via the Groups service. Executing this request MUST update a group, but does not return any information.

<static> { osapi.Request } osapi.groups.delete(params) Builds a request to delete a group via the Groups service. This method takes a single parameter, which is a JavaScript object representing the parameters defined by the Groups service's delete method, except that the 'userId' property can not be changed from the default value of '@me'. This parameter is REQUIRED, and MUST include the 'message' property. A osapi.Request to delete a group via the Groups service. Executing this request MUST delete a group, but does not return any information.

Service object with functions that map to the Messages service.

<static> { osapi.Request } osapi.messages.send(params) Builds a request to send a message via the Messages service. This method takes a single parameter, which is a JavaScript object representing the parameters defined by the Messages service's send method, except that the 'userId' property can not be changed from the default value of '@me'. This parameter is REQUIRED, and MUST include the 'message' property. A osapi.Request to send a message via the Messages service. Executing this request MUST send a message, but does not return any information.

An example illustrating how to send a message using osapi.messages.send(): var params = { message: { "recipients" : ["example.org:AD38B3886625AAF", "example.org:997638BAA6F25AD"], "title" : "You have a message from Joe", "body" : "Some content", "type" : "EMAIL" }, }; osapi.messages.send(params).execute(messageSentCallback);

Service object with functions that map to the Albums service.

<static> { osapi.Request } osapi.albums.get(params) Builds a request to retrieve information from the Albums service. This method takes a single parameter, which is a JavaScript object representing the parameters defined by the Albums service's get method, except that the 'appId' parameter can not be changed from "@appId". A osapi.Request to retrieve information from the Albums service. Executing this request MUST return a Album object or a Collection of Album objects.

<static> { osapi.Request } osapi.albums.get(params) Builds a request to create a new album using the Albums service. This method takes a single parameter, which is a JavaScript object representing the parameters defined by the Albums service's create method, except that the 'appId' parameter can not be changed from "@app". This parameter is REQUIRED and MUST contain the 'data' property. A osapi.Request to retrieve information from the Albums service. Executing this request MUST attempt to create the specified Album and return the newly-created Albums object if successful.

<static> { osapi.Request } osapi.albums.update(params) Builds a request to update information stored in the Activities service. This method takes a single parameter, which is a JavaScript object representing the parameters defined by the Albums service's update method, except that the 'appId' parameter can not be changed from "@appId". This parameter is REQUIRED and MUST include the 'data' property. A osapi.Request to retrieve information from the Albums service. Executing this request MUST overwrite the existing Albums on the server, but does not return any values.

<static> { osapi.Request } osapi.albums.delete(params) Builds a request to delete information stored in the Albums service. This method takes a single parameter, which is a JavaScript object representing the parameters defined by the Albums service's delete method, except that the 'appId' parameter can not be changed from "@appId". This parameter is REQUIRED and MUST include the 'ids' property. A osapi.Request to retrieve information from the Albums service. Executing this request MUST remove the specified Albums from the server and return them as a JavaScript object.

Service object with functions that map to the MediaItems service.

<static> { osapi.Request } osapi.mediaItems.get(params) Builds a request to retrieve information from the MediaItems service. This method takes a single parameter, which is a JavaScript object representing the parameters defined by the MediaItems service's get method, except that the 'appId' parameter can not be changed from "@appId". A osapi.Request to retrieve information from the MediaItems service. Executing this request MUST return a MediaItems object or a Collection of MediaItems objects.

<static> { osapi.Request } osapi.mediaItems.get(params) Builds a request to create a new media item using the MediaItems service. This method takes a single parameter, which is a JavaScript object representing the parameters defined by the MediaItems service's create method, except that the 'appId' parameter can not be changed from "@app". This parameter is REQUIRED and MUST contain the 'data' property. A osapi.Request to retrieve information from the MediaItems service. Executing this request MUST attempt to create the specified MediaItems and return the newly-created MediaItem object if successful.

<static> { osapi.Request } osapi.mediaItems.update(params) Builds a request to update information stored in the MediaItems service. This method takes a single parameter, which is a JavaScript object representing the parameters defined by the MediaItems service's update method, except that the 'appId' parameter can not be changed from "@appId". This parameter is REQUIRED and MUST include the 'data' property. A osapi.Request to retrieve information from the MediaItems service. Executing this request MUST overwrite the existing MediaItems on the server, but does not return any values.

<static> { osapi.Request } osapi.mediaItems.delete(params) Builds a request to delete information stored in the MediaItems service. This method takes a single parameter, which is a JavaScript object representing the parameters defined by the MediaItems service's delete method, except that the 'appId' parameter can not be changed from "@appId". This parameter is REQUIRED and MUST include the 'ids' property. A osapi.Request to retrieve information from the MediaItems service. Executing this request MUST remove the specified MediaItems from the server and return them as a JavaScript object.

Namespace for top-level people functions. There are cases where a gadget may wish to perform an action that needs approval by the user or mediation by the container. OpenSocial supports "request" features that allow the container to decide how to handle the interaction with the user. Functions like opensocial.requestCreateActivity, and opensocial.requestPermission allow the container to inject its own policy decisions into the gadget execution flow and notify the gadget of the result. Under this specification, it is equally valid for a container to defer to the user, always approve, always deny, or use any other method to determine responses to request calls. Additionally, this allows the container to enforce UI flows in a safe and integrated way.

<static> opensocial.Environment opensocial.getEnvironment() Gets the current environment for this gadget. You can use the environment to make queries such as what profile fields and surfaces are supported by this container, what parameters were passed to the current gadget, and so on. None. Type Description opensocial.Environment The current environment.

<static> Boolean opensocial.hasPermission(permission) Returns true if the current gadget has access to the specified permission. If the gadget calls opensocial.requestPermission and permissions are granted then this function must return true on all subsequent calls. Name Type Description permission opensocial.Permission The permission. Type Description Boolean True if the gadget has access for the permission; false if it doesn't.

<static> opensocial.NavigationParameters opensocial.newNavigationParameters(parameters) Creates a NavigationParameters object. See also: requestShareApp(). Name Type Description parameters Map.<opensocial.NavigationParameters.Field|Object> Parameters defining the navigation Type Description opensocial.NavigationParameters The new NavigationParameters object

<static> void opensocial.requestPermission(permissions, reason, opt_callback) Requests the user to grant access to the specified permissions. If the container does not support this method the callback will be called with a opensocial.ResponseItem. The response item will have its error code set to 'notImplemented'. Name Type Description permissions Array.<opensocial.Permission> The permissions to request from the viewer reason String Displayed to the user as the reason why these permissions are needed opt_callback Function The function to call once the request has been processed; either this callback will be called or the gadget will be reloaded from scratch. This function will be passed one parameter, an opensocial.ResponseItem. The error code will be set to reflect whether there were any problems with the request. If there was no error, all permissions were granted. If there was an error, you can use opensocial.hasPermission to check which permissions are still denied. The data on the response item will be set. It will be an array of the opensocial.Permissions that were granted. The callback function will not be called until after the existing callstack has completed execution. None.

<static> void opensocial.requestShareApp(recipients, reason, opt_callback, opt_params) Requests that the container share this gadget with the specified users. The callback function is passed one parameter, an opensocial.ResponseItem. The error code will be set to reflect whether there were any problems with the request. If there was no error, the sharing request was sent. If there was an error, you can use the response item's getErrorCode method to determine how to proceed. The data on the response item will not be set. If the container does not support this method the callback will be called with a opensocial.ResponseItem. The response item will have its error code set to 'notImplemented'. Name Type Description recipients opensocial.IdSpec An IdSpec used to specify which people/groups to send the ShareApp request to. reason opensocial.Message The reason the user wants the gadget to share itself. This reason can be used by the container when prompting the user for permission to share the app. It may also be ignored. opt_callback Function The function to call once the request has been processed; either this callback will be called or the gadget will be reloaded from scratch. The callback function will not be called until after the existing callstack has completed execution. opt_params opensocial.NavigationParameters The optional parameters indicating where to send a user when a request is made, or when a request is accepted; options are of type NavigationParameters.DestinationType. None.

Represents the current environment for a gadget. See also: opensocial.getEnvironment().

String getDomain() Returns the current domain. for example, "orkut.com" or "myspace.com". None. Type Description String The domain

Boolean supportsField(objectType, fieldName) Returns true if the specified field is supported in this container on the given object type, and returns false otherwise. Name Type Description objectType opensocial.Environment.ObjectType The object type to check for the field fieldName String The name of the field to check for Type Description Boolean True if the field is supported on the specified object type

The types of objects in this container. See also: Environment.supportsField() This field may be used interchangeably with the string 'activity'. This field may be used interchangeably with the string 'address'. This field may be used interchangeably with the string 'bodyType'. This field may be used interchangeably with the string 'email'. This field may be used interchangeably with the string 'filterType'. This field may be used interchangeably with the string 'mediaItem'. This field may be used interchangeably with the string 'message'. This field may be used interchangeably with the string 'messageType'. This field may be used interchangeably with the string 'name'. This field may be used interchangeably with the string 'organization'. This field may be used interchangeably with the string 'person'. This field may be used interchangeably with the string 'phone'. This field may be used interchangeably with the string 'sortOrder'. This field may be used interchangeably with the string 'url'.

Parameters used by RequestShareApp to instruct the container on where to go after the request is made. It could be used, for example, to specify where viewers get routed in one of two cases: After a user gets a shareApp invitation or receives a message a gadget developer should be able to send that user to a context sensitive place. After a viewer actually shares an app with someone else the gadget developer should be able to redirect the viewer to a context sensitive place.

String getField(key, opt_params) Gets the data from the NavigationParameters that is associated with the specified key. Name Type Description key String The key to get data for; see opensocial.NavigationParameters.Field class for supported values opt_params Map.<opensocial.DataRequest.DataRequestFields|Object> Additional params to pass to the request. Type Description String The data

void setField(key, data) Sets data for this NavigationParameters associated with the given key. Name Type Description key String The key to set data for data Object The data to set None.

The destinations available for navigation in requestShareApp and requestSendMessage. This field may be used interchangeably with the string 'recipientDestination'. This field may be used interchangeably with the string 'viewerDestination'.

All of the fields that NavigationParameters can have. See also: opensocial.NavigationParameters.getField() A string representing the owner id. This field may be used interchangeably with the string 'owner'. An optional list of parameters passed to the gadget once the new view, with the new owner, has been loaded. This field may be used interchangeably with the string 'parameters'. The gadgets.views.View to navigate to. This field may be used interchangeably with the string 'view'.

The permissions an app can ask for. See also: opensocial.hasPermission(), opensocial.requestPermission() Access to the viewer person object This field may be used interchangeably with the string 'viewer'.

The Social Gadget Specification extends the Data Pipelining capabilities of the Core Gadget Specification by adding support for the following tags:

A request to get profile information for a group or list of people. This is equivalent to using <os:DataRequest> with @method of "people.get". The attributes of this tag are equivalent to the parameters defined by the People service's get method. A Person object or a Collection of Person objects.

Example <os:PeopleRequest key="PagedFriends" userId="@owner" groupId="@friends" startIndex="40" count="20"/>

A request to get the viewer's or owner's profile information. This is equivalent to using <os:DataRequest> with @method of "people.get", with @userId of either "@viewer" or "@owner". The attributes of this tag are equivalent to the parameters defined by the People service's get method, except that the 'userId' parameter can not be changed from "@viewer" or "@owner". A Person object.

Example <os:ViewerRequest key="Viewer" fields="name, birthday"/>

A request to get activities. This is equivalent to using <os:DataRequest> with @method of "activities.get". The attributes of this tag are equivalent to the parameters defined by the Activities service's get method, except the 'appId' parameter can not be changed from "@app". A Activity object or a Collection of Activity objects.

Example: <os:ActivitiesRequest key="ViewerActivities" userid="@viewer" startIndex="40" count="20"/>

This specification defines a set of tags, known as OpenSocial Markup Language (OSML) tags, that extend the templating capabilities of the Core Gadget Container specification.

To use OSML tags, you need to add the "osml" feature to your gadget spec:

<Require feature="osml">

OSML tags are a strict subset of OpenSocial Templating, you can also use tags if you use the "opensocial-templates" feature:

<Require feature="opensocial-templates">

The reason for separate require features is that templates may not be supported on all views for all containers, due to processing and/or latency costs. OSML tags must be supported in all views.

An OSML tag is invoked much like an OpenSocial template. It needs to be surrounded by a <script> tag with @type="text/os-template":

Welcome, <script type="text/os-template" xmlns:os="http://ns.opensocial.org/2008/markup"><os:Name person="${Viewer}"/></script>!

An implementing Container MUST support at least the tags listed in this section. A Container MAY support additional tags - an effort will be made to make such support as consistent as possible across different Containers, and tags that are deemed useful may be adopted into this specification in the future.

Inline tag to show a person's name. If a profile URL is available it will be linked to. The tag may display additional container bling (i.e. more information on hover), but must do so without breaking up text flow. Attributes: @person {Object} The person object. (required)

Example <script type="text/os-template" xmlns:os="http://ns.opensocial.org/2008/markup">Welcome, <os:Name person="${Viewer}"/></script>

Tag to show a UI that chooses from a list of people, and set a form field with the associated value. Attributes: @group {Object} An array of person objects. @inputName {string} Name of the form input element that will contain selected id(s). Containers can provide a default here. (optional) @multiple {boolean} Allow multiple selections? (optional) @max {number} Maximum number of people that can be selected. (optional) @var{string} Name of the top level DataContext variable that is set with the selected person object (or array of objects). (optional) @onselect {string|function} Client side script function to invoke when a selection is made. The function will get the selected person object (or array of objects) as a parameter. (optional)

Example <form action="/top_friends.php" method="POST"> Select your top 8 friends: <script type="text/os-template" xmlns:os="http://ns.opensocial.org/2008/markup"> <os:PeopleSelector group="${ViewerFriends}" multiple="true" max="8" inputName="top8"/> </script> </form>

Block level tag to show information about a person in the style of the container, usually with an image. Attributes: @person {string|Object} The person object or DataContext key referring to a person object. (required)

Example My best friend is:<br/> <script type="text/os-template" xmlns:os="http://ns.opensocial.org/2008/markup"><os:Badge person="${TopFriend}"/></script>

There are a number of potential tags that can be better supported using templating, for reasons outlined below. Note that most of these capabilities will require using the "opensocial-templates" feature.

For generating text content, expressions are used instead of tags. Example: ${Viewer.name} or ${Owner.jobs[0].Title} instead of <os:Name> (note that <os:Name> is for showing a linked name, not for inserting text only). Reasoning: Extends to all OpenSocial fields (see the Person object for a list). Can be used in attributes, such as <input type="submit" value="Share with ${Name}">.

For conditional content, a conditional statement in OpenSocial templating is used along with an expression. Example: <div if="${!viewer.hasApp}"><a href="...">Click here to install!</a></div> or <div if="${jobs[0].Title}">${name}'s job is ${jobs[0].Title}"</div> instead of <os:HasApp> etc. Reasoning: Extends well to a large number of conditional constructs (no need for one tag per condition). Equivalently simple to use.

For pronouns, conditional HTML blocks based on gender are used. Example: <span if="${person.gender == 'MALE'}">He said "boo"</span> <span if="${person.gender == 'FEMALE'}">She said "boo"</span> instead of <span><os:Pronoun> said "boo"</span> Reasoning: You need full sentences to localize properly.

Inlining of remote HTML markup is possible via a combination of Data Pipelining's <os:HttpRequest> tag and OpenSocial Templates variable inlining via the ${data} syntax. Thus a dedicated <os:Get> tag is not needed. Example: <os:HttpRequest key="Data" href="http://example.com/data.html" format="text"> Then use <os:Html code="${Data}"/> in your template. Reasoning: Re-using existing capabilities avoids doing the same thing in two different ways.

The combination of tags, templates, and proxied content leads to a number of combinations for developer to use. Here are a few common use cases and how developers might handle them. This is for informational purposes only - it doesn't extend the proposal, but hopefully clarifies a few use cases.

OpenSocial data will be posted on the developer server and flow control will be handled on the developers own server, in PHP, JSP, ASP, or the language of the developer's choice.

Example Gadget XML <Content href="http://developer.com/canvas" xmlns:os="http://ns.opensocial.org/2008/markup"> <os:PeopleRequest userId="@viewer" groupId="@friends" fields="name,birthday" key="ViewerFriends"> </Content>

Example PHP <?php // Some code that pulls POST param into $ViewerFriends here foreach ($ViewerFriends as $friend) { if ($friend['birthday']) { echo "<div>".$friend['name']."'s birthday is".$friend['birthday']"</div>"; } } ?>

Tags can be inserted into the output and will be processed by the container or JavaScript on the client side.

Example Gadget XML <Content href="http://developer.com/canvas" xmlns:os="http://ns.opensocial.org/2008/markup"> <os:PersonRequest userId="@owner" key="Owner"/> </Content>

Example PHP <?php // Let the Container know that the Owner object is needed for post-processing ?> <script type="text/os-data" xmlns:os="http://ns.opensocial.org/2008/markup"> <os:PersonRequest userId="@owner" key="Owner"/> </script> <?php // Some code that pulls POST param into $Owner echo "High score for <script type=\"text/os-template\" xmlns:os=\"http://ns.opensocial.org/2008/markup\">" . "<os:Name person=\"${Owner}\"></script> is " . getHighScore($Owner['id']); ?>

PHP Output <script type="text/os-data" xmlns:os="http://ns.opensocial.org/2008/markup"> <os:PersonRequest userId="@owner" key="Owner"/> </script> High score for <script type="text/os-template" xmlns:os="http://ns.opensocial.org/2008/markup"><os:Name person="${Owner}"></script> is 100

Final Container output after OSML is processed High score for John Doe is 100

Harvard University IBM

Namespace for top-level people functions.

Deprecated. Use osapi.cache.invalidate() instead. <static> opensocial.invalidateCache() Description: Invalidates all resources cached for the current viewer.

Deprecated. Use the definition of Activity objects introduced in OpenSocial v1.0 instead. <static> Type: { opensocial.Activity } opensocial.newActivity(params) Description: Creates an activity object, which represents an activity on the server. See also: requestCreateActivity(), It is only required to set one of TITLE_ID or TITLE. In addition, if you are using any variables in your title or title template, you must set TEMPLATE_PARAMS. Other possible fields to set are: URL, MEDIA_ITEMS, BODY_ID, BODY, EXTERNAL_ID, PRIORITY, STREAM_TITLE, STREAM_URL, STREAM_SOURCE_URL, and STREAM_FAVICON_URL. Containers are only required to use TITLE_ID or TITLE, and may choose to ignore additional parameters. See Field for more details. Parameters: Name Type Description params Map.<opensocial.Activity.Field|Object> Parameters defining the activity Returns: Type Description opensocial.Activity The new activity object

Deprecated. Use the definition of Album objects introduced in OpenSocial v1.0 instead. <static> Type: { opensocial.MediaItem } opensocial.newAlbum(opt_params) Description: Creates a album. Represents a collection of images, movies, and audio. Used when creating albums on the server. Parameters: Name Type Description opt_params Map.<opensocial.Album.Field|Object> Any other fields that should be set on the Album object; all of the defined Field s are supported Returns: Type Description opensocial.MediaItem The new album object

Deprecated. Use osapi.newBatch() instead. <static> Type: { opensocial.DataRequest } opensocial.newDataRequest() Description: Creates a data request object to use for sending and fetching data from the server. Returns: Type Description opensocial.DataRequest The request object

Deprecated. IdSpec objects are not used in osapi.* calls. Instead, the user ID(s), group ID(s), and network distance values are specified as parameters in the request. <static> Type: {opensocial.IdSpec} opensocial.newIdSpec(parameters) Description: Creates an IdSpec object. Parameters: Name Type Description parameters Map.<opensocial.IdSpec.Field|Object> Parameters defining the id spec. Returns: Type Description opensocial.IdSpec The new IdSpec object

Deprecated. Use the definition of MediaItem objects introduced in OpenSocial v1.0 instead. <static> Type: { opensocial.MediaItem } opensocial.newMediaItem(mimeType, url, opt_params) Description: Creates a media item. Represents images, movies, and audio. Used when creating activities on the server. Parameters: Name Type Description mimeType String MIME type of the media url String Where the media can be found opt_params Map.<opensocial.MediaItem.Field|Object> Any other fields that should be set on the media item object; all of the defined Field s are supported Returns: Type Description opensocial.MediaItem The new media item object

Deprecated. Use the definition of Message objects introduced in OpenSocial v1.0 instead. <static> Type: { opensocial.Message } opensocial.newMessage(body, opt_params) Description: Creates a new message object for use with opensocial.requestSendMessage. Parameters: Name Type Description body String The main text of the message opt_params Map.<opensocial.Message.Field|Object> Any other fields that should be set on the message object; all of the defined Field s are supported Returns: Type Description opensocial.Message The new message object

Deprecated. Use osapi.activities.create() instead. <static> opensocial.requestCreateActivity(activity, priority, opt_callback) Description: Takes an activity and tries to create it, without waiting for the operation to complete. Optionally calls a function when the operation completes. See also: newActivity() Note: If this is the first activity that has been created for the user and the request is marked as HIGH priority then this call may open a user flow and navigate away from your gadget. This callback will either be called or the gadget will be reloaded from scratch. This function will be passed one parameter, an opensocial.ResponseItem. The error code will be set to reflect whether there were any problems with the request. If there was no error, the activity was created. If there was an error, you can use the response item's getErrorCode method to determine how to proceed. The data on the response item will not be set. If the container does not support this method the callback will be called with a opensocial.ResponseItem. The response item will have its error code set to 'notImplemented'. Parameters: Name Type Description activity opensocial.Activity The activity to create priority opensocial.CreateActivityPriority The priority for this request opt_callback Function The function to call once the request has been processed. The callback function will not be called until after the existing callstack has completed execution.

Deprecated. Use osapi.messages.send() instead. <static> opensocial.requestSendMessage(An, message, opt_callback, opt_params) Description: Requests the container to send a specific message to the specified users. The callback function is passed one parameter, an opensocial.ResponseItem. The error code will be set to reflect whether there were any problems with the request. If there was no error, the message was sent. If there was an error, you can use the response item's getErrorCode method to determine how to proceed. The data on the response item will not be set. If the container does not support this method the callback will be called with an opensocial.ResponseItem that has an error code of 'notImplemented'. Parameters: Name Type Description An opensocial.IdSpec IdSpec used to specify which people/groups to send the message to. message opensocial.Message The message to send to the specified users opt_callback Function The function to call once the request has been processed; either this callback will be called or the gadget will be reloaded from scratch.The callback function will not be called until after the existing callstack has completed execution. opt_params opensocial.NavigationParameters The optional parameters indicating where to send a user when a request is made, or when a request is accepted; options are of type NavigationParameters.DestinationType

Deprecated. Use osapi.mediaItems.create() instead. <static> opensocial.requestUploadMediaItem(albumId, opt_callback) Description: Uploads a media item. Allows the container to provide some standard UI and other items to post files to a site. Parameters: Name Type Description albumId string Indicates which album/collection to insert the items into. If not present or set to null|undefined, the items go into the default location for the container. Partial upload is possible, such that if the container allows for multiple items, some items may fail to be added. opt_callback Function Method is called when the upload completes. The callback function is passed one parameter, an opensocial.ResponseItem. The error code will be set to reflect whether there were any problems with the request. If there was no error, the message was sent. If there was an error, you can use the response item's getErrorCode method to determine how to proceed. getErrorMessage will contain a comma separated list of files that failed to upload. The data on the response item will be set to an array of media item objects for successful items.

Deprecated. Use the definition of Activity objects introduced in OpenSocial v1.0 instead. Representation of an activity. Activities are rendered with a title and an optional activity body. You may set the title and body directly as strings when calling opensocial.newActivity. However, it is usually beneficial to create activities using Message Templates for the title and body. Users will have many activities in their activity streams, and containers will not show every activity that is visible to a user. To help display large numbers of activities, containers will summarize a list of activities from a given source to a single entry. You can provide Activity Summaries to customize the text shown when multiple activities are summarized. If no customization is provided, a container may ignore your activities altogether or provide default text such as "Bob changed his status message + 20 other events like this." Activity Summaries will always summarize around a specific key in a key/value pair. This is so that the summary can say something concrete (this is clearer in the example below). Other variables will have synthetic "Count" variables created with the total number of items summarized. Message ID of the summary is the message ID of the main template + ":" + the data key Example summaries:

<messagebundle> <msg name="LISTEN_TO_THIS_SONG:Artist"> ${Subject.Count} of your friends have suggested listening to songs by ${Artist}! </msg> <msg name="LISTEN_TO_THIS_SONG:Song"> ${Subject.Count} of your friends have suggested listening to ${Song} !</msg> <msg name="LISTEN_TO_THIS_SONG:Subject"> ${Subject.DisplayName} has recommended ${Song.Count} songs to you. </msg> </messagebundle>

See also: opensocial.Message, opensocial.newActivity(), opensocial.requestCreateActivity()

Type: {String} getField(key, opt_params) Description: Gets the activity data that's associated with the specified key. Parameters: Name Type Description key String The key to get data for; see the Field class for possible values opt_params Map.<opensocial.DataRequest.DataRequestFields|Object> Additional params to pass to the request. Returns: Type Description String The data

Type: {String} getId() Description: Gets an ID that can be permanently associated with this activity. Returns: Type Description String The ID

setField(key, data) Description: Sets data for this activity associated with the given key. Parameters: Name Type Description key String The key to set data for data String The data to set

Deprecated. Use the definition of Activity objects introduced in OpenSocial v1.0 instead. All of the fields that activities can have. It is only required to set one of TITLE_ID or TITLE. In addition, if you are using any variables in your title or title template, you must set TEMPLATE_PARAMS. See also: opensocial.Activity.getField() Description: A string specifying the application that this activity is associated with. This value can not be set. This field may be used interchangeably with the string 'appId'. Description: A string specifying an optional expanded version of an activity. Bodies may only have the following HTML tags: <b> <i>, <a>, <span>. The container may ignore this formatting when rendering the activity. This field may be used interchangeably with the string 'body'. Description: A string specifying the body template message ID in the gadget spec. The body is an optional expanded version of an activity. Bodies may only have the following HTML tags: <b> <i>, <a>, <span>. The container may ignore this formatting when rendering the activity. This field may be used interchangeably with the string 'bodyId'. Description: An optional string ID generated by the posting application. This field may be used interchangeably with the string 'externalId'. Description: A string ID that is permanently associated with this activity. This value can not be set. This field may be used interchangeably with the string 'id'. Description: Any photos, videos, or images that should be associated with the activity. Higher priority ones are higher in the list. The data has type Array< MediaItem >. This field may be used interchangeably with the string 'mediaItems'. Description: A string specifying the datetime at which this activity took place in milliseconds since the epoch. This value can not be set. This field may be used interchangeably with the string 'postedTime'. Description: A number between 0 and 1 representing the relative priority of this activity in relation to other activities from the same source This field may be used interchangeably with the string 'priority'. Description: A string specifying the URL for the stream's favicon. This field may be used interchangeably with the string 'streamFaviconUrl'. Description: A string specifying the stream's source URL. This field may be used interchangeably with the string 'streamSourceUrl'. Description: A string specifing the title of the stream. This field may be used interchangeably with the string 'streamTitle'. Description: A string specifying the stream's URL. This field may be used interchangeably with the string 'streamUrl'. Description: A map of custom key/value pairs associated with this activity. These will be used for evaluation in templates. The data has type Map<String, Object>. The object may be either a String or an opensocial.Person. When passing in a person with key PersonKey, can use the following replacement variables in the template: PersonKey.DisplayName - Display name for the person PersonKey.ProfileUrl. URL of the person's profile PersonKey.Id - The ID of the person PersonKey - Container may replace with DisplayName, but may also optionally link to the user. This field may be used interchangeably with the string 'templateParams'. Description: A string specifying the primary text of an activity. Titles may only have the following HTML tags: <b> <i>, <a>, <span>. The container may ignore this formatting when rendering the activity. This field may be used interchangeably with the string 'title'. Description: A string specifying the title template message ID in the gadget spec. The title is the primary text of an activity. Titles may only have the following HTML tags: <b> <i>, <a>, <span>. The container may ignore this formatting when rendering the activity. This field may be used interchangeably with the string 'titleId'. Description: A string specifying the URL that represents this activity. This field may be used interchangeably with the string 'url'. Description: The string ID of the user who this activity is for. This value can not be set. This field may be used interchangeably with the string 'userId'.

Deprecated. Use the definition of Address objects introduced in OpenSocial v1.0 instead. Base interface for all address objects.

Type: {String} getField(key, opt_params) Description: Gets data for this body type that is associated with the specified key. Parameters: Name Type Description key String The key to get data for; keys are defined in Address.Field opt_params Map.<opensocial.DataRequest.DataRequestFields|Object> Additional params to pass to the request Returns: Type Description String The data

Deprecated. Use the definition of Address objects introduced in OpenSocial v1.0 instead. All of the fields that an address has. These are the supported keys for the Address.getField() method. Description: The country, specified as a string. This field may be used interchangeably with the string 'country'. Description: The extended street address, specified as a string. This field may be used interchangeably with the string 'extendedAddress'. Description: The latitude, specified as a number. This field may be used interchangeably with the string 'latitude'. Description: The locality, specified as a string. This field may be used interchangeably with the string 'locality'. Description: The longitude, specified as a number. This field may be used interchangeably with the string 'longitude'. Description: The P.O. box of the address, if there is one; specified as a string. This field may be used interchangeably with the string 'poBox'. Description: The postal code, specified as a string. This field may be used interchangeably with the string 'postalCode'. Description: The region, specified as a string. This field may be used interchangeably with the string 'region'. Description: The street address, specified as a string. This field may be used interchangeably with the string 'streetAddress'. Description: The address type or label, specified as a string. Examples: work, my favorite store, my house, etc. This field may be used interchangeably with the string 'type'. Description: If the container does not have structured addresses in its data store, this field contains the unstructured address that the user entered, specified as a string. Use opensocial.getEnvironment().supportsField to see which fields are supported. This field may be used interchangeably with the string 'unstructuredAddress'.

Deprecated. Use the definition of Album objects introduced in OpenSocial v1.0 instead. Class for Album features.

Type: {String} getField(key, opt_params) Description: Gets the album data that's associated with the specified key. Parameters: Name Type Description key String The key to get data for; see the Field class for possible values opt_params Map.<opensocial.DataRequest.DataRequestFields|Object> Additional params to pass to the request. Returns: Type Description String The data

setField(key, data) Description: Sets data for this album associated with the given key. Parameters: Name Type Description key String The key to set data for data String The data to set

Deprecated. Use the definition of Album objects introduced in OpenSocial v1.0 instead. All of the fields that albums can have. It is only required to set ID. Other possible fields to set are: THUMBNAIL_URL, TITLE, DESCRIPTION, LOCATION, OWNER_ID, MEDIA_TYPE, MEDIA_MIME_TYPE, MEDIA_ITEM_COUNT. See also: opensocial.Album.getField() Description: string, description of the album. May be used interchangeably with the string 'description'. Description: string, unique identifier for the album. May be used interchangeably with the string 'id'. Description: opensocial.Address, location corresponding to the album. May be used interchangeably with the string 'location'. Description: integer, number of items in the album. May be used interchangeably with the string 'mediaItemCount'. Description: array of strings identifying the mime-types of media items in the Album. May be used interchangeably with the string 'mediaMimeType'. Description: array of MediaItem.TYPE, types of MediaItems in the Album. May be used interchangeably with the string 'mediaType'. Description: string, ID of the owner of the album. May be used interchangeably with the string 'ownerId'. Description: string, URL to a thumbnail cover of the album. May be used interchangeably with the string 'thumbnailUrl'. Description: string, the title of the album. May be used interchangeably with the string 'title'.

Deprecated. Use the definition of BodyType objects introduced in OpenSocial v1.0 instead. Base interface for all body type objects.

Type: {String} getField(key, opt_params) Description: Gets data for this body type that is associated with the specified key. Parameters: Name Type Description key String The key to get data for; keys are defined in BodyType.Field opt_params Map.<opensocial.DataRequest.DataRequestFields|Object> Additional params to pass to the request. Returns: Type Description String The data

Deprecated. Use the definition of BodyType objects introduced in OpenSocial v1.0 instead. All of the fields that a body type has. These are the supported keys for the BodyType.getField() method. Description: The build of the person's body, specified as a string. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'build'. Description: The eye color of the person, specified as a string. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'eyeColor'. Description: The hair color of the person, specified as a string. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'hairColor'. Description: The height of the person in meters, specified as a number. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'height'. Description: The weight of the person in kilograms, specified as a number. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'weight'.

Deprecated. Use the definition of Collection objects introduced in OpenSocial v1.0 instead. Collection of multiple objects with useful accessors. May also represent subset of a larger collection (for example, page 1 of 10) and contain information about the larger collection.

Type: {Array.<Object>} asArray() Description: Returns an array of all the objects in this collection. Returns: Type Description Array.<Object> The values in this collection

each(fn) Description: Executes the provided function once per member of the collection, with each member in turn as the parameter to the function. Parameters: Name Type Description fn Function The function to call with each collection entry

Type: {Object?} getById(id) Description: Finds the entry with the given ID value, or returns null if none is found. Parameters: Name Type Description id String The ID to look for Returns: Type Description Object? The data

Type: {Number} getOffset() Description: Gets the offset of this collection within a larger result set. Returns: Type Description Number The offset into the total collection

Type: {Number} getTotalSize() Description: Gets the total size of the larger result set that this collection belongs to. Returns: Type Description Number The total size of the result

Type: {Number} size() Description: Gets the size of this collection, which is equal to or less than the total size of the result. Returns: Type Description Number The size of this collection

Deprecated. Activity priorities should be represented by a property field in the Activity JSON object. The priorities a create activity request can have. See also: opensocial.requestCreateActivity() If the activity is of high importance, it will be created even if this requires asking the user for permission. This may cause the container to open a user flow which may navigate away from your gagdet. This field may be used interchangeably with the string 'HIGH'. If the activity is of low importance, it will not be created if the user has not given permission for the current app to create activities. With this priority, the requestCreateActivity call will never open a user flow. This field may be used interchangeably with the string 'LOW'.

Deprecated. Service requests should be represented using the Batch Request JSON object. Used to request social information from the container. This includes data for friends, profiles, app data, and activities. All apps that require access to people information should send a DataRequest. Here's an example of creating, initializing, sending, and handling the results of a data request:

function requestMe() { var req = opensocial.newDataRequest(); req.add(req.newFetchPersonRequest( opensocial.IdSpec.PersonId.VIEWER), "viewer"); req.send(handleRequestMe); }; function handleRequestMe(data) { var viewer = data.get("viewer"); if (viewer.hadError()) { //Handle error using viewer.getError()...return; } //No error. Do something with viewer.getData()... }

See also: opensocial.newDataRequest()

add(request, opt_key) Description: Adds an item to fetch (get) or update (set) data from the server. A single DataRequest object can have multiple items. As a rule, each item is executed in the order it was added, starting with the item that was added first. However, items that can't collide might be executed in parallel. Parameters: Name Type Description request Object Specifies which data to fetch or update opt_key String A key to map the generated response data to

Deprecated. Use osapi.albums.create() instead. Type: {Object} newCreateAlbumRequest(An, album) Description: Creates a new album and returns the ID of the album created. Containers implement restrictions - like allowing a viewer to create albums for only him/herself. Parameters: Name Type Description An opensocial.IdSpec IdSpec used to specify which people/groups to create an album for. album opensocail.Album The album to create. Returns: Type Description Object A request object

Deprecated. Use osapi.mediaItems.create() instead. Type: {Object} newCreateMediaItemRequest(An, albumId, mediaItem) Description: Creates a new media item in the album and returns the ID of the album created. Containers implement restrictions. Parameters: Name Type Description An opensocial.IdSpec IdSpec used to specify which people/groups own the album. albumId string The album to add the media item to. mediaItem opensocial.MediaItem The MediaItem to add to the album. Returns: Type Description Object A request object

Deprecated. Use osapi.albums.delete() instead. Type: {Object} newDeleteAlbumRequest(An, albumId) Description: Deletes the album specified. Containers implement restriction. Parameters: Name Type Description An opensocial.IdSpec IdSpec used to specify which people/groups own the album. albumId string The album to delete. Returns: Type Description Object A request object

Deprecated. Use osapi.activities.get() instead. Type: {Object} newFetchActivitiesRequest(idSpec, opt_params) Description: Creates an item to request an activity stream from the server. When processed, returns a Collection<Activity>. Parameters: Name Type Description idSpec opensocial.IdSpec An IdSpec used to specify which people to fetch. See also IdSpec. opt_params Map.<opensocial.DataRequest.ActivityRequestFields|Object> Additional parameters to pass to the request; not currently used Returns: Type Description Object A request object

Deprecated. Use osapi.albums.get() instead. Type: {Object} newFetchAlbumsRequest(An, opt_params) Description: The newFetchAlbumsRequest() creates an object for DataRequest to request albums. Parameters: Name Type Description An opensocial.IdSpec IdSpec used to specify which people/groups to fetch albums from. opt_params Map.<string|string> opt_params can specify the following: opensocial.Album.Field.ID - an array of album Ids to fetch (fetch all albums if empty, subject to pagination) opensocial.Album.Field.MEDIA_TYPE - an array of MediaItem.TYPE values to specify the kind of Albums to fetch. opensocial.DataRequest.AlbumRequestFields.FIRST - The first item to fetch. opensocial.DataRequest.AlbumRequestFields.MAX - The maximum number of items to fetch. Returns: Type Description Object A request object

Deprecated. Use osapi.mediaItems.get() instead. Type: {Object} newFetchMediaItemsRequest(An, albumId, opt_params) Description: The newFetchMediaItemsRequest() creates an object for DataRequest to request mediaItems. Parameters: Name Type Description An opensocial.IdSpec IdSpec used to specify which people/groups to fetch media items from. albumId string The id of the album to fetch MediaItems from. opt_params Map.<string|string> opt_params can specify the following: opensocial.MediaItem.Field.ID - an array of media item ids to selectively fetch (fetch all items if empty, subject to pagination) opensocial.MediaItem.Field.MEDIA_TYPE - an array of MediaItem.TYPE values to specify the types of MediaItems to fetch opensocial.DataRequest.MediaItemRequestFields.FIRST - The first item to fetch. opensocial.DataRequest.MediaItemRequestFields.MAX - The maximum number of items to fetch. Returns: Type Description Object A request object

Deprecated. Use osapi.people.get() instead. Type: {Object} newFetchPeopleRequest(idSpec, opt_params) Description: Creates an item to request friends from the server. When processed, returns a Collection < Person > object. Parameters: Name Type Description idSpec opensocial.IdSpec An IdSpec used to specify which people to fetch. See also IdSpec. opt_params Map.<opensocial.DataRequest.PeopleRequestFields|Object> Additional params to pass to the request Returns: Type Description Object A request object

Deprecated. Use osapi.appdata.get() instead. Type: {Object} newFetchPersonAppDataRequest(idSpec, keys, opt_params) Description: Creates an item to request app data for the given people. When processed, returns a Map< PersonId, Map<String, Object>> object. All of the data values returned will be valid json. Parameters: Name Type Description idSpec opensocial.IdSpec An IdSpec used to specify which people to fetch. See also IdSpec. keys Array.<String> | String The keys you want data for; this can be an array of key names, a single key name, or "*" to mean "all keys" opt_params Map.<opensocial.DataRequest.DataRequestFields|Object> Additional params to pass to the request Returns: Type Description Object A request object

Deprecated. Use osapi.people.get() instead. Type: {Object} newFetchPersonRequest(id, opt_params) Description: Creates an item to request a profile for the specified person ID. When processed, returns a Person object. Parameters: Name Type Description id String The ID of the person to fetch; can be the standard person ID of VIEWER or OWNER opt_params Map.<opensocial.DataRequest.PeopleRequestFields|Object> Additional parameters to pass to the request; this request supports PROFILE_DETAILS Returns: Type Description Object A request object

Deprecated. Use osapi.appdata.delete() instead. Type: {Object} newRemovePersonAppDataRequest(keys) Description: Deletes the given keys from the datastore for the current VIEWER. When processed, does not return any data. Parameters: Name Type Description keys Array.<String> | String The keys you want to delete from the datastore; this can be an array of key names, a single key name, or "*" to mean "all keys" Returns: Type Description Object A request object

Deprecated. Use osapi.albums.update() instead. Type: {Object} newUpdateAlbumRequest(An, albumId, fields) Description: Updates the fields specified in the params.The following fields cannot be set: MEDIA_ITEM_COUNT, OWNER_ID, ID. Containers implement restrictions. Parameters: Name Type Description An opensocial.IdSpec IdSpec used to specify which people/groups to own the album. albumId string The album to update. fields Map<opensocial.Album.Field|object> The Album Fields to update.The following fields cannot be set: MEDIA_ITEM_COUNT, OWNER_ID, ID. Containers implement restrictions. Returns: Type Description Object A request object

Deprecated. Use osapi.mediaItems.update() instead. Type: {Object} newUpdateMediaItemRequest(An, albumId, mediaItemId, fields) Description: Updates the fields specified in the params.The following fields cannot be set: ID, CREATED, ALBUM_ID, FILE_SIZE, NUM_COMMENTS. Containers implement restrictions. Parameters: Name Type Description An opensocial.IdSpec IdSpec used to specify which people/groups own the album/media item. albumId string The album containing the media item to update. mediaItemId string The media item to update. fields Map<opensocial.MediaItem.Field|object> The Album Fields to update.The following fields cannot be set: ID, CREATED, ALBUM_ID, FILE_SIZE, NUM_COMMENTS. Containers implement restrictions. Returns: Type Description Object A request object

Deprecated. Use osapi.appdata.update() instead. Type: {Object} newUpdatePersonAppDataRequest(key, value) Description: Creates an item to request an update of an app field for the current VIEWER. When processed, does not return any data. App Data is stored as a series of key value pairs of strings, scoped per person, per application. Parameters: Name Type Description key String The name of the key. This may only contain alphanumeric (A-Za-z0-9) characters, underscore(_), dot(.) or dash(-). value Object The value, must be valid JSON Returns: Type Description Object A request object

Deprecated. Use osapi.Request.execute() or osapi.BatchRequest.execute()instead. send(opt_callback) Description: Sends a data request to the server in order to get a data response. Although the server may optimize these requests, they will always be executed as though they were serial. Parameters: Name Type Description opt_callback Function The function to call with the data response generated by the server. The callback function will not be called until after the existing callstack has completed execution.

Deprecated. Use osapi.activities.get() with the startIndex, startPage, and count parameters to handle paging. The values needed to handle activity paging. When paginating, the index of the first item to fetch; specified as a number. The maximum number of items to fetch, specified as a number; defaults to 20.

Deprecated. Use osapi.albums.get() with the startIndex, startPage, and count parameters to handle paging. The values needed to handle activity paging. When paginating, the index of the first item to fetch; specified as a number. The maximum number of items to fetch, specified as a number; defaults to 20.

Deprecated. Values are escaped by default. How to escape person data returned from the server; defaults to HTML_ESCAPE. Possible values are defined by EscapeType. This field may be used interchangeably with the string 'escapeType'. Use of this function is deprecated in favor of us using the ESCAPE_TYPE request field.

Deprecated. Use osapi.people.get() with the filterBy, filterOp, and filterValue parameters to filter the people objects returned. The filters available for limiting person requests. Retrieves all friends. This field may be used interchangeably with the string 'all'. Retrieves all friends that use this application. Note: Containers may define "use" in any manner they deem appropriate for their functionality, and it is not expected that this field will have the exact same semantics across containers. This field may be used interchangeably with the string 'hasApp'. Will filter the people requested by checking if they are friends with the given idSpec. Expects a filterOptions parameter to be passed with the following fields defined: - idSpec The idSpec that each person must be friends with. This field may be used interchangeably with the string 'isFriendsWith'. Retrieves only the user's top friends as defined by the container. Container support for this filter type is OPTIONAL. This field may be used interchangeably with the string 'topFriends'.

Deprecated. Use osapi.mediaItems.get() with the startIndex, startPage, and count parameters to handle paging. The values needed to handle activity paging. When paginating, the index of the first item to fetch; specified as a number. The maximum number of items to fetch, specified as a number; defaults to 20.

Deprecated. Use osapi.people.get() with the fields parameter, and prefix the app data keys with the string "appdata.". For example, '"fields": ["gender", "appdata.favoriteColor"]' would return the value for gender as well as the value of the appdata entry where "favoriteColor" is the key. An array of strings, specifying the app data keys to fetch for each of the Person objects. This field may be used interchangeably with the string 'appData'. Deprecated. Values are escaped by default. How to escape Person fields and app data returned from the server; defaults to HTML_ESCAPE. Possible values are defined by EscapeType. This field may be used interchangeably with the string 'escapeType'. Deprecated. Use osapi.people.get() with the filterBy, filterOp, and filterValue parameters to filter the people objects returned. How to filter the people objects; defaults to ALL. Possible values are defined by FilterType. This field may be used interchangeably with the string 'filter'. Deprecated. Use osapi.people.get() with the filterBy, filterOp, and filterValue parameters to filter the people objects returned. Additional options to be passed into the filter, specified as a Map<String, Object>. This field may be used interchangeably with the string 'filterOptions'. Deprecated. Use osapi.people.get() with the startIndex, startPage, and count parameters to handle paging. When paginating, the index of the first item to fetch; specified as a number. This field may be used interchangeably with the string 'first'. Deprecated. Use osapi.people.get() with the startIndex, startPage, and count parameters to handle paging. The maximum number of items to fetch, specified as a number; defaults to 20. If set to a larger number, a container may honor the request, or may limit the number to a container-specified limit of at least 20. This field may be used interchangeably with the string 'max'. Deprecated. Use osapi.people.get() with the fields parameter to specify what profile data to fetch. An array of opensocial.Person.Field specifying what profile data to fetch for each of the person objects. The server will always include ID, NAME, and THUMBNAIL_URL. This field may be used interchangeably with the string 'profileDetail'. anchor="opensocial.DataRequest.PeopleRequestFields.SORT_ORDER"> Deprecated. Use osapi.people.get() with the sortOrder parameter to specify the sort order. A sort order for the people objects; defaults to TOP_FRIENDS. Possible values are defined by SortOrder. This field may be used interchangeably with the string 'sortOrder'.

Deprecated. Use osapi.people.get() with the sortOrder parameter to specify the sort order. The sort orders available for ordering person objects. When used will sort people alphabetically by the name field. This field may be used interchangeably with the string 'name'. When used will sort people by the container's definition of top friends. This field may be used interchangeably with the string 'topFriends'.

Deprecated. Callback methods receive Response objects. This object contains the requested server data mapped to the requested keys. See also: DataRequest

Type: { opensocial.ResponseItem } get(key) Description: Gets the ResponseItem for the requested field. Parameters: Name Type Description key Returns: Type Description opensocial.ResponseItem The requested response calculated by the server

Type: {String} getErrorMessage() Description: If the entire request had a batch level error, returns the error message. Returns: Type Description String A human-readable description of the error that occurred.

Type: {Boolean} hadError() Description: Returns true if there was an error in fetching this data from the server. Returns: Type Description Boolean True if there was an error; otherwise, false

Deprecated. Use the definition of Email objects introduced in OpenSocial v1.0 instead. Base interface for all email objects.

Type: {String} getField(key, opt_params) Description: Gets data for this body type that is associated with the specified key. Parameters: Name Type Description key String The key to get data for; keys are defined in Email.Field opt_params Map.<opensocial.DataRequest.DataRequestFields|Object> Additional params to pass to the request. Returns: Type Description String The data

Deprecated. Use the definition of Email objects introduced in OpenSocial v1.0 instead. All of the fields that an email has. These are the supported keys for the Email.getField() method. The email address, specified as a string. This field may be used interchangeably with the string 'address'. The email type or label, specified as a string. Examples: work, my favorite store, my house, etc. This field may be used interchangeably with the string 'type'.

Deprecated. Use the fields of the Person object instead. Base interface for all enum objects. This class allows containers to use constants for fields that are usually have a common set of values. There are two main ways to use this class. If your gadget just wants to display how much of a smoker someone is, it can simply use:

html = "This person smokes: " + person.getField('smoker').getValue();

This value field will be correctly set up by the container. This is a place where the container can even localize the value for the gadget so that it always shows the right thing. If your gadget wants to have some logic around the smoker field it can use:

if (person.getField('smoker').getKey() != "NO") { //gadget logic here }

Note: The key may be null if the person's smoker field cannot be coerced into one of the standard enum types. The value, on the other hand, is never null.

Type: {String} getDisplayValue() Description: The value of this enum. This will be a user displayable string. If the container supports localization, the string will be localized. Returns: Type Description String The enum's value.

Type: {String} getKey() Description: Use this for logic within your gadget. If they key is null then the value does not fit in the defined enums. Returns: Type Description String The enum's key. This should be one of the defined enums below.

Deprecated. Use the drinker field of the Person object instead. The enum keys used by the drinker field. See also: opensocial.Person.Field.Drinker This field may be used interchangeably with the string 'HEAVILY'. This field may be used interchangeably with the string 'NO'. This field may be used interchangeably with the string 'OCCASIONALLY'. This field may be used interchangeably with the string 'QUIT'. This field may be used interchangeably with the string 'QUITTING'. This field may be used interchangeably with the string 'REGULARLY'. This field may be used interchangeably with the string 'SOCIALLY'. This field may be used interchangeably with the string 'YES'.

Deprecated. Use the gender field of the Person object instead. The enum keys used by the gender field. See also: opensocial.Person.Field.Gender This field may be used interchangeably with the string 'FEMALE'. This field may be used interchangeably with the string 'MALE'.

Deprecated. Use the lookingFor field of the Person object instead. The enum keys used by the lookingFor field. See also: opensocial.Person.Field.LookingFor This field may be used interchangeably with the string 'ACTIVITY_PARTNERS'. This field may be used interchangeably with the string 'DATING'. This field may be used interchangeably with the string 'FRIENDS'. This field may be used interchangeably with the string 'NETWORKING'. This field may be used interchangeably with the string 'RANDOM'. This field may be used interchangeably with the string 'RELATIONSHIP'.

Deprecated. Use the presence field of the Person object instead. The enum keys used by the networkPresence field. See also: opensocial.Person.Field.NetworkPresence The entity or resource is temporarily away. This field may be used interchangeably with the string 'AWAY'. The entity or resource is actively interested in chatting. This field may be used interchangeably with the string 'CHAT'. The entity or resource is busy (dnd = "Do Not Disturb"). This field may be used interchangeably with the string 'DND'. The entity or resource is off line. This field may be used interchangeably with the string 'OFFLINE'. The entity or resource is on line. This field may be used interchangeably with the string 'ONLINE'. The entity or resource is away for an extended period (xa = "eXtended Away"). This field may be used interchangeably with the string 'XA'.

Deprecated. Use the smoker field of the Person object instead. The enum keys used by the smoker field. See also: opensocial.Person.Field.Smoker This field may be used interchangeably with the string 'HEAVILY'. This field may be used interchangeably with the string 'NO'. This field may be used interchangeably with the string 'OCCASIONALLY'. This field may be used interchangeably with the string 'QUIT'. This field may be used interchangeably with the string 'QUITTING'. This field may be used interchangeably with the string 'REGULARLY'. This field may be used interchangeably with the string 'SOCIALLY'. This field may be used interchangeably with the string 'YES'.

Deprecated. All values are escaped automatically. The types of escaping that can be applied to person data or fields. When used will HTML-escape the data. This field may be used interchangeably with the string 'htmlEscape'. When used will not escape the data. This field may be used interchangeably with the string 'none'.

Deprecated. IdSpec objects are not used in osapi.* calls. Instead, the user ID(s), group ID(s), and network distance values are specified as parameters in the request. Base interface for all id spec objects.

Type: {String} getField(key, opt_params) Description: Gets the id spec's data that's associated with the specified key. Parameters: Name Type Description key String The key to get data for; see the Field class for possible values opt_params Map.<opensocial.DataRequest.DataRequestFields|Object> Additional params to pass to the request. Returns: Type Description String The data

setField(key, data) Description: Sets data for this id spec associated with the given key. Parameters: Name Type Description key String The key to set data for data String The data to set

Deprecated. IdSpec objects are not used in osapi.* calls. Instead, the user ID(s), group ID(s), and network distance values are specified as parameters in the request. All of the fields that id specs can have. See also: opensocial.IdSpec.getField() A string representing the group id or one of the opensocial.IdSpec.GroupId values. Defaults to SELF. This field may be used interchangeably with the string 'groupId'. An optional numeric parameter, used to specify how many "hops" are allowed between two people still considered part of the same group. This is 0 based, for example: A value of 0 means that the people are the same person. 1 would mean that the people were friends. And 2 would mean that there was a friend of a friend relationship. Defaults to 1 (they are both friends or directly in the same group). Not all containers will support networkDistances greater than 1. This field may be used interchangeably with the string 'networkDistance'. A string or an array of strings representing the user id. Can be one of the opensocial.IdSpec.PersonId values. This field may be used interchangeably with the string 'userId'.

Deprecated. IdSpec objects are not used in osapi.* calls. Instead, the user ID(s), group ID(s), and network distance values are specified as parameters in the request. Constant group IDs available when fetching collections of people. This field may be used interchangeably with the string 'ALL'. This field may be used interchangeably with the string 'FRIENDS'. This field may be used interchangeably with the string 'SELF'.

Deprecated. IdSpec objects are not used in osapi.* calls. Instead, the user ID(s), group ID(s), and network distance values are specified as parameters in the request. Constant person IDs available when fetching person information. This field may be used interchangeably with the string 'OWNER'. This field may be used interchangeably with the string 'VIEWER'.

Deprecated. Use the definition of MediaItem objects introduced in OpenSocial v1.0 instead. Represents images, movies, and audio. Create a MediaItem object using the opensocial.newMediaItem() method.

Type: {String} getField(key, opt_params) Description: Gets the media item data that's associated with the specified key. Parameters: Name Type Description key String The key to get data for; see the Field class for possible values opt_params Map.<opensocial.DataRequest.DataRequestFields|Object> Additional params to pass to the request. Returns: Type Description String The data

setField(key, data) Description: Sets data for this media item associated with the given key. Parameters: Name Type Description key String The key to set data for data String The data to set

Deprecated. Use the definition of MediaItem objects introduced in OpenSocial v1.0 instead. All of the fields that media items have. See also: opensocial.MediaItem.getField() string, album to which the media item belongs This field may be used interchangeably with the string 'albumId'. string, creation datetime associated with the media item - assigned by container in UTC This field may be used interchangeably with the string 'created'. string, description of the media item This field may be used interchangeably with the string 'description'. integer, for audio/video clips - playtime length in seconds. set to -1/not defined if unknown This field may be used interchangeably with the string 'duration'. long, number of bytes (set to -1/undefined if unknown). This field may be used interchangeably with the string 'fileSize'. string, id Associated with the media item This field may be used interchangeably with the string 'id'. string, language associated with the media item in ISO 639-3 format This field may be used interchangeably with the string 'language'. string, update datetime associated with the media item - assigned by container in UTC This field may be used interchangeably with the string 'lastUpdated'. opensocial.Address, location corresponding to the media item This field may be used interchangeably with the string 'location'. The MIME type of media, specified as a string. This field may be used interchangeably with the string 'mimeType'. integer, number of comments on the media item. This field may be used interchangeably with the string 'numComments'. integer, number of views for the media item. This field may be used interchangeably with the string 'numViews'. integer, number of votes received for voting. This field may be used interchangeably with the string 'numVotes'. integer, average rating of the media item on a scale of 0-10. This field may be used interchangeably with the string 'rating'. string, for streaming/live content, datetime when the content is available. This field may be used interchangeably with the string 'startTime'. array of strings, array of string (IDs) of people tagged in the media item This field may be used interchangeably with the string 'taggedPeople'. array of strings, tags associated with this media item. This field may be used interchangeably with the string 'tags'. string, URL to a thumbnail image of the media item This field may be used interchangeably with the string 'thumbnailUrl'. string describing the media item This field may be used interchangeably with the string 'title'. The type of media, specified as a MediaItem.Type object. This field may be used interchangeably with the string 'type'. A string specifying the URL where the media can be found. This field may be used interchangeably with the string 'url'.

Deprecated. Use the definition of MediaItem objects introduced in OpenSocial v1.0 instead. The possible types of media items. See also: opensocial.MediaItem.Field This field may be used interchangeably with the string 'audio'. This field may be used interchangeably with the string 'image'. This field may be used interchangeably with the string 'video'.

Deprecated. Use the definition of Message objects introduced in OpenSocial v1.0 instead. Base interface for all message objects. * See also: opensocial.newMessage(), opensocial.requestSendMessage()

Type: {String} getField(key, opt_params) Description: Gets the message data that's associated with the specified key. Parameters: Name Type Description key String The key to get data for; see the Field class for possible values opt_params Map.<opensocial.DataRequest.DataRequestFields|Object> Additional params to pass to the request. Returns: Type Description String The data

setField(key, data) Description: Sets data for this message associated with the given key. Parameters: Name Type Description key String The key to set data for data String The data to set

Deprecated. Use the definition of Message objects introduced in OpenSocial v1.0 instead. All of the fields that messages can have. See also: opensocial.Message.getField() Identifies the application that generated this message. This field may be used interchangeably with the string 'appUrl'. The main text of the message. HTML attributes are allowed and are sanitized by the container. This field may be used interchangeably with the string 'body'. The main text of the message as a message template. Specifies the message ID to use in the gadget xml. This field may be used interchangeably with the string 'bodyId'. Identifies the messages collection IDs this message is contained in. This field may be used interchangeably with the string 'collectionIds'. unique ID for this message. This field may be used interchangeably with the string 'id'. Message ID, use for threaded comments/messages. Reference the sematics of the Atom Threading model defined in rfc4685. URLs should be mapped to Atom <link rel="type" .../> This field may be used interchangeably with the string 'inReplyTo'. Array of person IDs. This field may be used interchangeably with the string 'recipients'. array of message ids. Reference the sematics of the Atom Threading model defined in rfc4685. URLs should be mapped to Atom <link rel="type" .../> This field may be used interchangeably with the string 'replies'. id of person who sent the message. This field may be used interchangeably with the string 'senderId'. Status of the message. (NEW, READ, DELETED). This field may be used interchangeably with the string 'status'. UTC datetime the message was sent. This field may be used interchangeably with the string 'timeSent'. The title of the message. HTML attributes are allowed and are sanitized by the container. This field may be used interchangeably with the string 'title'. The title id of the message as a message template. Specifies the message ID to use in the gadget xml. This field may be used interchangeably with the string 'titleId'. The type of the message, specified as an opensocial.Message.Type. This field may be used interchangeably with the string 'type'. last update for this message . This field may be used interchangeably with the string 'updated'. List of related URLs for this message. Supported URL types include 'alternate', alternate for for this mailbox (text/html being the most common). This field may be used interchangeably with the string 'urls'.

Deprecated. Use the definition of Message objects introduced in OpenSocial v1.0 instead. Class for MessageCollection features.

Type: {String} getField(key, opt_params) Description: Gets the MessageCollection data that's associated with the specified key. Parameters: Name Type Description key String The key to get data for; see the Field class for possible values opt_params Map.<opensocial.DataRequest.DataRequestFields|Object> Additional params to pass to the request. Returns: Type Description String The data

setField(key, data) Description: Sets data for this album associated with the given key. Parameters: Name Type Description key String The key to set data for data String The data to set

Deprecated. Use the definition of Message objects introduced in OpenSocial v1.0 instead. All of the fields that a MessageCollection can have. It is only required to set ID. See also: opensocial.MessageCollection.getField() string, unique ID for this message collection. May be used interchangeably with the string 'id'. string, the title of the MessageCollection. May be used interchangeably with the string 'title'. int, total number of messages in this group. May be used interchangeably with the string 'total'. int, number of unread messages in this group. May be used interchangeably with the string 'unread'. string, last datetime update for this message collection. May be used interchangeably with the string 'updated'. opensocial.Url, List of related URLs for this message collection. Supported URL types include: 1. icon: icon for this mailbox 2. alternate: alternate form for this mailbox (text/html being the most common) May be used interchangeably with the string 'urls'.

Deprecated. Use the definition of Name objects introduced in OpenSocial v1.0 instead. Base interface for all name objects.

Type: {String} getField(key, opt_params) Description: Gets data for this name that is associated with the specified key. Parameters: Name Type Description key String The key to get data for; keys are defined in Name.Field opt_params Map.<opensocial.DataRequest.DataRequestFields|Object> Additional params to pass to the request. Returns: Type Description String The data

Deprecated. Use the definition of Name objects introduced in OpenSocial v1.0 instead. All of the fields that a name has. These are the supported keys for the Name.getField() method. The additional name, specified as a string. This field may be used interchangeably with the string 'additionalName'. The family name, specified as a string. This field may be used interchangeably with the string 'familyName'. The given name, specified as a string. This field may be used interchangeably with the string 'givenName'. The honorific prefix, specified as a string. This field may be used interchangeably with the string 'honorificPrefix'. The honorific suffix, specified as a string. This field may be used interchangeably with the string 'honorificSuffix'. The unstructured name, specified as a string. This field may be used interchangeably with the string 'unstructured'.

Deprecated. Use the definition of Organization objects introduced in OpenSocial v1.0 instead. Base interface for all organization objects.

Type: {String} getField(key, opt_params) Description: Gets data for this body type that is associated with the specified key. Parameters: Name Type Description key String The key to get data for; keys are defined in Organization.Field opt_params Map.<opensocial.DataRequest.DataRequestFields|Object> Additional params to pass to the request Returns: Type Description String The data

Deprecated. Use the definition of Organization objects introduced in OpenSocial v1.0 instead. All of the fields that a organization has. These are the supported keys for the Organization.getField() method. The address of the organization, specified as an opensocial.Address. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'address'. A description or notes about the person's work in the organization, specified as a string. This could be the courses taken by a student, or a more detailed description about a Organization role. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'description'. The date the person stopped at the organization, specified as a Date. A null date indicates that the person is still involved with the organization. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'endDate'. The field the organization is in, specified as a string. This could be the degree pursued if the organization is a school. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'field'. The name of the organization, specified as a string. For example, could be a school name or a job company. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'name'. The salary the person receieves from the organization, specified as a string. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'salary'. The date the person started at the organization, specified as a Date. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'startDate'. The subfield the Organization is in, specified as a string. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'subField'. The title or role the person has in the organization, specified as a string. This could be graduate student, or software engineer. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'title'. A webpage related to the organization, specified as a string. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'webpage'.

Deprecated. Use the definition of Person objects introduced in OpenSocial v1.0 instead. Base interface for all person objects.

Type: {String} getAppData(key) Description: Gets the app data for this person that is associated with the specified key. Parameters: Name Type Description key String The key to get app data for. Returns: Type Description String The corresponding app data.

Type: {String} getDisplayName() Description: Gets a text display name for this person; guaranteed to return a useful string. Returns: Type Description String The display name

Type: {String} getField(key, opt_params) Description: Gets data for this person that is associated with the specified key. Parameters: Name Type Description key String The key to get data for; keys are defined in Person.Field opt_params Map.<opensocial.DataRequest.DataRequestFields|Object> Additional params to pass to the request. Returns: Type Description String The data

Type: {String} getId() Description: Gets an ID that can be permanently associated with this person. Returns: Type Description String The ID

Type: {Boolean} isOwner() Description: Returns true if this person object represents the owner of the current page. Returns: Type Description Boolean True if this is the owner of the page; otherwise, false

Type: {Boolean} isViewer() Description: Returns true if this person object represents the currently logged in user. Returns: Type Description Boolean True if this is the currently logged in user; otherwise, false

Deprecated. Use the definition of Person objects introduced in OpenSocial v1.0 instead. All of the fields that a person has. These are the supported keys for the Person.getField() method. A general statement about the person, specified as a string. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'aboutMe'. Person's favorite activities, specified as an Array of strings. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'activities'. Addresses associated with the person, specified as an Array of Address es. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'addresses'. Person's age, specified as a number. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'age'. Person's body characteristics, specified as an opensocial.BodyType. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'bodyType'. Person's favorite books, specified as an Array of strings. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'books'. Person's favorite cars, specified as an Array of strings. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'cars'. Description of the person's children, specified as a string. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'children'. Person's current location, specified as an Address. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'currentLocation'. Person's date of birth, specified as a Date object. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'dateOfBirth'. Person's drinking status, specified as an opensocial.Enum with the enum's key referencing opensocial.Enum.Drinker. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'drinker'. Emails associated with the person, specified as an Array of Email s. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'emails'. Person's ethnicity, specified as a string. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'ethnicity'. Person's thoughts on fashion, specified as a string. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'fashion'. Person's favorite food, specified as an Array of strings. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'food'. Person's gender, specified as an opensocial.Enum with the enum's key referencing opensocial.Enum.Gender. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'gender'. Describes when the person is happiest, specified as a string. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'happiestWhen'. A boolean indicating whether the person has used the current app. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'hasApp'. Person's favorite heroes, specified as an Array of strings. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'heroes'. Person's thoughts on humor, specified as a string. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'humor'. A string ID that can be permanently associated with this person. This field may be used interchangeably with the string 'id'. For the anonymous VIEWER, this value MUST be -1. Person's interests, hobbies or passions, specified as an Array of strings. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'interests'. Person's favorite jobs, or job interests and skills, specified as an array of strings. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'jobInterests'. Jobs the person has held, specified as an Array of Organization s. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'jobs'. List of the languages that the person speaks as ISO 639-1 codes, specified as an Array of strings. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'languagesSpoken'. Description of the person's living arrangement, specified as a string. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'livingArrangement'. Person's statement about who or what they are looking for, or what they are interested in meeting people for. Specified as an Array of opensocial.Enum with the enum's key referencing opensocial.Enum.LookingFor. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'lookingFor'. Person's favorite movies, specified as an Array of strings. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'movies'. Person's favorite music, specified as an Array of strings. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'music'. A opensocial.Name object containing the person's name. This field may be used interchangeably with the string 'name'. For the anonymous VIEWER, this value may be a user friendly name such as Guest, Anonymous, depending on the browser locale. Person's current network status. Specified as an Enum with the enum's key referencing opensocial.Enum.Presence. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'networkPresence'. A String representing the person's nickname. This represents the casual way to address this person in real life. This field may be used interchangeably with the string 'nickname'. For the anonymous VIEWER, this value may be a user friendly nickname such as Guest, Anonymous, depending on the browser locale. Description of the person's pets, specified as a string. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'pets'. Phone numbers associated with the person, specified as an Array of Phone s. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'phoneNumbers'. Person's political views, specified as a string. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'politicalViews'. Person's profile song, specified as an opensocial.Url. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'profileSong'. Person's profile URL, specified as a string. This URL must be fully qualified. Relative URLs will not work in gadgets. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'profileUrl'. Person's profile video, specified as an opensocial.Url. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'profileVideo'. Person's favorite quotes, specified as an Array of strings. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'quotes'. Person's relationship status, specified as a string. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'relationshipStatus'. Person's relgion or religious views, specified as a string. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'religion'. Person's comments about romance, specified as a string. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'romance'. What the person is scared of, specified as a string. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'scaredOf'. Schools the person has attended, specified as an Array of Organization s. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'schools'. Person's sexual orientation, specified as a string. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'sexualOrientation'. Person's smoking status, specified as an opensocial.Enum with the enum's key referencing opensocial.Enum.Smoker. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'smoker'. Person's favorite sports, specified as an Array of strings. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'sports'. Person's status, headline or shoutout, specified as a string. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'status'. Arbitrary tags about the person, specified as an Array of strings. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'tags'. Person's photo thumbnail URL, specified as a string. This URL must be fully qualified. Relative URLs will not work in gadgets. This field may be used interchangeably with the string 'thumbnailUrl'. For the anonymous VIEWER, this value may be a standard representation of an anonymous user on the site. Person's time zone, specified as the difference in minutes between Greenwich Mean Time (GMT) and the user's local time. See Date.getTimezoneOffset() in javascript for more details on this format. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'timeZone'. Person's turn offs, specified as an Array of strings. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'turnOffs'. Person's turn ons, specified as an Array of strings. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'turnOns'. Person's favorite TV shows, specified as an Array of strings. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'tvShows'. URLs related to the person, their webpages, or feeds. Specified as an Array of opensocial.Url. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'urls'.

Deprecated. Use the definition of Phone objects introduced in OpenSocial v1.0 instead. Base interface for all phone objects.

Type: {String} getField(key, opt_params) Description: Gets data for this phone that is associated with the specified key. Parameters: Name Type Description key String The key to get data for; keys are defined in Phone.Field opt_params Map.<opensocial.DataRequest.DataRequestFields|Object> Additional params to pass to the request. Returns: Type Description String The data

Deprecated. Use the definition of Phone objects introduced in OpenSocial v1.0 instead. All of the fields that a phone has. These are the supported keys for the Phone.getField() method. The phone number, specified as a string. This field may be used interchangeably with the string 'number'. The phone number type or label, specified as a string. Examples: work, my favorite store, my house, etc. This field may be used interchangeably with the string 'type'.

Deprecated. Callback methods receive Response objects. Represents a response that was generated by processing a data request item on the server.

Type: {Object} getData() Description: Gets the response data. Returns: Type Description Object The requested value calculated by the server; the type of this value is defined by the type of request that was made

Type: {String} getErrorCode() Description: If the request had an error, returns the error code. The error code can be container-specific or one of the values defined by Error. Returns: Type Description String The error code, or null if no error occurred

Type: {String} getErrorMessage() Description: If the request had an error, returns the error message. Returns: Type Description String A human-readable description of the error that occurred; can be null, even if an error occurred

Type: {Object} getOriginalDataRequest() Description: Returns the original data request item. Returns: Type Description Object The request item used to fetch this data response

Type: {Boolean} hadError() Description: Returns true if there was an error in fetching this data from the server. Returns: Type Description Boolean True if there was an error; otherwise, false

Deprecated. Callback methods receive Response objects. Error codes that a response item can return. The request was invalid. Example: 'max' was -1. This field may be used interchangeably with the string 'badRequest'. The gadget can never have access to the requested data. This field may be used interchangeably with the string 'forbidden'. The request encountered an unexpected condition that prevented it from fulfilling the request. This field may be used interchangeably with the string 'internalError'. The gadget exceeded a quota on the request. Example quotas include a max number of calls per day, calls per user per day, calls within a certain time period and so forth. This field may be used interchangeably with the string 'limitExceeded'. This container does not support the request that was made. This field may be used interchangeably with the string 'notImplemented'. The gadget does not have access to the requested data. To get access, use opensocial.requestPermission(). This field may be used interchangeably with the string 'unauthorized'.

Deprecated. Use the definition of Url objects introduced in OpenSocial v1.0 instead. Base interface for all URL objects.

Type: {String} getField(key, opt_params) Description: Gets data for this URL that is associated with the specified key. Parameters: Name Type Description key String The key to get data for; keys are defined in Url.Field opt_params Map.<opensocial.DataRequest.DataRequestFields|Object> Additional params to pass to the request. Returns: Type Description String The data

Deprecated. Use the definition of Url objects introduced in OpenSocial v1.0 instead. All of the fields that a URL has. These are the supported keys for the Url.getField() method. The address the URL points to, specified as a string. This field may be used interchangeably with the string 'address'. The text of the link, specified as a string. This field may be used interchangeably with the string 'linkText'. The URL number type or label, specified as a string. Examples: work, blog feed, website, etc. This field may be used interchangeably with the string 'type'.