OpenSocial Specification v0.9

The JavaScript API reference is a complete listing of the methods and fields that OpenSocial requires, but some conventions are not immediately understandable. This section will explain some of the assumptions used in generating the API reference.

JavaScript is not strongly typed, but in order to make the developer experience consistent, the APIs are defined as if JavaScript supported strongly typed data. Cases where a parameter or return value are defined as a certain type in the documentation indicate that this is the only type that can be provided or accepted for OpenSocial compatibility. Any exceptions to this rule will be directly documented in the reference. As an example, the getErrorCode method is defined in the JavaScript API reference as returning a value of the type opensocial.ResponseItem.Error, although in practice this value will be a normal JavaScript string. However, developers can be assured that in a compliant container, the string returned is one of the opensocial.ResponseItem.Error fields. Enumerations figure heavily into the OpenSocial API. Developers are permitted to reference an enum or use the enum's value directly. To avoid collisions related to extensibility, containers must ensure that the names and values for an enum match the ones defined in the spec and that custom values are namespaced appropriately. For example, an Orkut custom field named MY_PERSON_FIELD could have a name of Orkut.PersonField.MY_PERSON_FIELD and a value of "Orkut.myPersonField". See the Compliance and Capabilities discovery sections for more information.

Many of the OpenSocial methods have a large number of optional parameters. JavaScript's lack of strong typing makes overloading difficult at best, and having functions with a large amount of parameters can be difficult to manage (especially for developers not using a nice IDE). OpenSocial uses the "object bag" approach to optional parameters: many methods take an additional opt_params parameter that takes the form of a map of parameter names to their corresponding values. For each method which uses an opt_params map the spec defines all of the valid fields that will be read out of the map by the container. These fields have defined types as discussed in the Virtual typing section. If a developer adds an invalid value for a field in the map the container should return the BAD_REQUEST error code.

The Lightweight Javascript API, or OS Lite, is more natural to JavaScript developers and more succinct for creating OpenSocial gadgets than the existing JS APIs. It relies on the existing JSON-RPC protocol handlers, and is marked by the use of simple JSON objects as input and output. Note: this implementation follows the JSON-RPC spec 1:1, but could also be implemented over REST. For compatibility purposes, the existing JS APIs are still in place, and we may consider deprecating them in the 1.0 timeframe if developers move to these new APIs.

Introduces standard method signature for data requests - JSON in, JSON out Input and output parameters match JSON-RPC calls 1:1 and share documentation Data requests look like functions on "service" objects, e.g., osapi.people.get(), instead of opensocial.DataRequest.newXXXRequest() Data requests can be called individually or as part of a batch Batch calls are designed for call chaining. The newBatch() call returns the batch, as does add, so that you can succinctly add more requests to the batch and execute it. Located in the osapi namespace

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

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

Batch request to retrieve a Person and Activities: var batch = osapi.newBatch(). add("viewer", osapi.people.getViewer()). add('activities', osapi.activities.get({ userId : '@viewer', groupId : '@self'})). batch.execute(function(result) { if (!result.error) { alert('Hi, ' + result.viewer.name + '!'); alert('You have ' + result.activities.length + ' activities.'); } });

A container MUST emit the OS Lite JavaScript libraries and data files required by the libraries if an application includes <Require feature="osapi"/> in the ModulePrefs section of the gadget XML file. The container SHOULD emit the OS Lite JavaScript libraries and data files required by the libraries if an application optionally requests the feature by including <Optional feature="osapi"/> in the ModulePrefs of the gadget XML file. The services available on the client are determined by the server from which the JavaScript is delivered. The server SHOULD generate service methods for all available services. Developers wanting to write gadgets safely can test for the existence of a service and method before making their call.

Example: if (osapi.people && osapi.people.getViewer) { osapi.people.getViewer().execute(function(result) { if (!result.error) { alert('Your name is ' + result.name + '!'); } }); }

Service object with functions that map to the JSON-RPC people endpoint.

<static> Type: { osapi.Request } osapi.people.get(params) Description: Builds a request to retrieve information from the JSON-RPC People service. When no parameter is specified, the server defaults, { userId : @me, groupId : @self}, will be used and the viewer's information will be returned. Parameters: Name Type Description params { AuthToken auth = HttpRequest.Authorization, String or Array.<String> userId = "@me", String groupId = "@self", Array.<String> fields, int count, int startIndex, int startPage } An optional JSON object containing request parameters. See the get operation of the JSON-RPC people endpoint for more details. Returns: Type Description osapi.Request A request to retrieve information from the JSON-RPC People service.

<static> Type: { osapi.Request } osapi.people.getViewer(params) Description: A convenience over osapi.people.get() that builds a request to retrieve the viewer, as specified in the security token, from the people JSON-RPC service. Parameters: Name Type Description params { AuthToken auth = HttpRequest.Authorization, Array.<String> fields, } An optional JSON object containing request parameters. See the get operation of the JSON-RPC people endpoint for more details. Returns: Type Description osapi.Request A request to retrieve information from the JSON-RPC People service.

<static> Type: { osapi.Request } osapi.people.getViewerFriends(params) Description: 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 JSON-RPC service. Parameters: Name Type Description params { AuthToken auth = HttpRequest.Authorization, Array.<String> fields, int count, int startIndex, int startPage } An optional JSON object containing request parameters. See the get operation of the JSON-RPC people endpoint for more details. Returns: Type Description osapi.Request A request to retrieve information from the JSON-RPC People service.

<static> Type: { osapi.Request } osapi.people.get(params) Description: A convenience over osapi.people.get() that builds a request to retrieve the owner, as specified in the security token, from the people JSON-RPC service. Parameters: Name Type Description params { AuthToken auth = HttpRequest.Authorization, Array.<String> fields, } An optional JSON object containing request parameters. See the get operation of the JSON-RPC people endpoint for more details. Returns: Type Description osapi.Request A request to retrieve information from the JSON-RPC People service.

<static> Type: { osapi.Request } osapi.people.get(params) Description: 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 JSON-RPC service. Parameters: Name Type Description params { AuthToken auth = HttpRequest.Authorization, Array.<String> fields, int count, int startIndex, int startPage } An optional JSON object containing request parameters. See the get operation of the JSON-RPC people endpoint for more details. Returns: Type Description osapi.Request A request to retrieve information from the JSON-RPC People service.

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

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

Service object with functions that map to the JSON-RPC activities endpoint.

<static> Type: { osapi.Request } osapi.activities.get(params) Description: Builds a request to retrieve activities from the Activities JSON-RPC service. Parameters: Name Type Description params { AuthToken auth = HttpRequest.Authorization, String or Array.<String> userId = "@me", String groupId = "@self", String appId = auth.AppId, Array.<String> activityIds = [], Array.<String> fields, int count, int startIndex, int startPage } An optional JSON object containing request parameters. See the get operation of the JSON-RPC Activities service for more details. Returns: Type Description osapi.Request A request to retrieve information from the JSON-RPC Activities service.

<static> Type: { osapi.Request } osapi.activities.get(params) Description: Builds a request to create an activity using the Activities JSON-RPC service. Parameters: Name Type Description params { AuthToken auth = HttpRequest.Authorization, String or Array.<String> userId = "@me", String groupId = "@self", String appId = auth.AppId, opensocial.Activity activity, } An optional JSON object containing request parameters. See the create operation of the JSON-RPC Activities service for more details. Returns: Type Description osapi.Request A request to retrieve information from the JSON-RPC Activities service.

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 = { auth: {"default" : null, "type" : "AuthToken"}, userId: "@me", groupId: "@self", appId: "XXXXXXX", 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 = { auth: {"default" : null, "type" : "AuthToken"}, userId: "@viewer", groupId: "@self", appId: "XXXXXXX", activity: {title: 'Hello!', url: 'http://mysite.com'} }; osapi.activities.create(params).execute(myCallback);

Service object with functions that map to the JSON-RPC app data endpoint.

<static> Type: { osapi.Request } osapi.appdata.get(params) Description: Builds a request to retrieve data from the AppData JSON-RPC service. Parameters: Name Type Description params { AuthToken auth = HttpRequest.Authorization, String or Array.<String> userId = "@me", String groupId = "@self", String appId = auth.AppId, Array.<String> keys, } An optional JSON object containing request parameters. See the get operation of the JSON-RPC AppData service for more details. Returns: Type Description osapi.Request A request to retrieve information from the JSON-RPC AppData service.

<static> Type: { osapi.Request } osapi.appdata.update(params) Description: Builds a request to create or update data from the AppData JSON-RPC service. Parameters: Name Type Description params { AuthToken auth = HttpRequest.Authorization, String or Array.<String> userId = "@me", String groupId = "@self", String appId = auth.AppId, Map.<String, String> data, } An optional JSON object containing request parameters. See the update operation of the JSON-RPC AppData service for more details. Returns: Type Description osapi.Request A request to retrieve information from the JSON-RPC AppData service.

<static> Type: { osapi.Request } osapi.appdata.delete(params) Description: Builds a request to delete data from the AppData JSON-RPC service. Parameters: Name Type Description params { AuthToken auth = HttpRequest.Authorization, String or Array.<String> userId = "@me", String groupId = "@self", String appId = auth.AppId, Array.<String> keys, } An optional JSON object containing request parameters. See the delete operation of the JSON-RPC AppData service for more details. Returns: Type Description osapi.Request A request to retrieve information from the JSON-RPC AppData service.

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 = { auth: {"default" : null, "type" : "AuthToken"}, userId: "@viewer", groupId: "@friends", appId: "XXXXXXX", 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", appId: "XXXXXXX", 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 = { auth: {"default" : null, "type" : "AuthToken"}, userId: "@viewer", groupId: "@friends", appId: "XXXXXXX", keys: ['gifts', 'wishlist'] }; osapi.appdata.delete(deleteParams).execute(myDeleteCallback)

Service object with functions that map to the JSON-RPC Messages endpoint.

<static> Type: { osapi.Request } osapi.messages.send(params) Description: Builds a request to send a message from the Messages JSON-RPC service. Parameters: Name Type Description params { AuthToken auth = HttpRequest.Authorization, String userId = "@me", opensocial.Message message } An optional JSON object containing request parameters. See the send operation of the JSON-RPC Messages service for more details. Returns: Type Description osapi.Request A request to retrieve information from the JSON-RPC Messages service.

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

Service object for making HTTP requests to third party servers. This is not a JSON-RPC endpoint, but a third party web service.

<static> Type: { osapi.Request } osapi.http.head(params) Description: Creates a HEAD request to an arbitrary URL. Parameters: Name Type Description url String The URL where the content is located params { Map.<String, Array.<String>> headers, String format = "json", int refreshInterval, String authz = "none", Boolean sign_viewer = true, Boolean sign_owner = true, String oauth_service_name = "", String oauth_token_name = "", String oauth_request_token, String oauth_request_token_secret, String oauth_use_token, } Takes an optional parameter that is a JSON object containing parameters and values similar to the attributes of the <os:HttpRequest> tag. Returns: Type Description osapi.Request A request to retrieve information an arbitrary URL.

<static> Type: { osapi.Request } osapi.http.get(params) Description: Creates a GET request to an arbitrary URL. Parameters: Name Type Description url String The URL where the content is located params { Map.<String, Array.<String>> headers, String format = "json", int refreshInterval, String authz = "none", Boolean sign_viewer = true, Boolean sign_owner = true, String oauth_service_name = "", String oauth_token_name = "", String oauth_request_token, String oauth_request_token_secret, String oauth_use_token, } Takes an optional parameter that is a JSON object containing parameters and values similar to the attributes of the <os:HttpRequest> tag. Returns: Type Description osapi.Request A request to retrieve information an arbitrary URL.

<static> Type: { osapi.Request } osapi.http.put(params) Description: Creates a PUT request to an arbitrary URL. Parameters: Name Type Description url String The URL where the content is located params { Map.<String, Array.<String>> headers, String body, String format = "json", int refreshInterval, String authz = "none", Boolean sign_viewer = true, Boolean sign_owner = true, String oauth_service_name = "", String oauth_token_name = "", String oauth_request_token, String oauth_request_token_secret, String oauth_use_token, } Takes an optional parameter that is a JSON object containing parameters and values similar to the attributes of the <os:HttpRequest> tag. Returns: Type Description osapi.Request A request to retrieve information an arbitrary URL.

<static> Type: { osapi.Request } osapi.http.post(params) Description: Creates a POST request to an arbitrary URL. Parameters: Name Type Description url String The URL where the content is located params { Map.<String, Array.<String>> headers, String body, String format = "json", int refreshInterval, String authz = "none", Boolean sign_viewer = true, Boolean sign_owner = true, String oauth_service_name = "", String oauth_token_name = "", String oauth_request_token, String oauth_request_token_secret, String oauth_use_token, } Takes an optional parameter that is a JSON object containing parameters and values similar to the attributes of the <os:HttpRequest> tag. Returns: Type Description osapi.Request A request to retrieve information an arbitrary URL.

<static> Type: { osapi.Request } osapi.http.delete(params) Description: Creates a DELETE request to an arbitrary URL. Parameters: Name Type Description url String The URL where the content is located params { Map.<String, Array.<String>> headers, String format = "json", int refreshInterval, String authz = "none", Boolean sign_viewer = true, Boolean sign_owner = true, String oauth_service_name = "", String oauth_token_name = "", String oauth_request_token, String oauth_request_token_secret, String oauth_use_token, } Takes an optional parameter that is a JSON object containing parameters and values similar to the attributes of the <os:HttpRequest> tag. Returns: Type Description osapi.Request A request to retrieve information an arbitrary URL.

Suppose a request to http://www.somephotosite.com/latest returns the following JSON: { photos : [ "http://www.somephotosite.com/photos/1.jpg", "http://www.somephotosite.com/photos/2.jpg", "http://www.somephotosite.com/photos/3.jpg", ], lastUpdate : "Mon, 13 Apr 2009 23:17:04 GMT" }

The data can be retrieved and accessed as follows: osapi.http.get('http://www.somephotosite.com/latest').execute(function(result) { if (!result.error) { alert('There are ' + result.content.photos.length + ' new photos'); } });

An example illustrating some available request parameters: var params = { 'format': 'json', 'headers': {'Content-Type': ['application/json;charset=utf-8'], "Accept-Language": ["en-us"]}, 'body': {'numResults': 100, theme: 'beach'}, 'authz': 'SIGNED', }; osapi.http.post('http://www.somephotosite.com/prefs?uid=1234', params).execute(function(result) { if (!result.error) { alert('Request to update user preferences was successful'); } });

All methods of OS Lite service objects (e.g. osapi.people.get()) return a JavaScript object representing the request. These objects MUST support the following method(s):

<static> osapi.Request.execute(callback) Description: Executes the service request. Takes a callback for response processing. Parameters: Name Type Description callback Function A callback function to handle the response.

Service requests can be combined into a single batch request using the following methods:

<static> Type: { osapi.BatchRequest } osapi.newBatch() Description: Creates a new batch request. Returns: Type Description osapi.BatchRequest A new batch request.

<static> Type: { osapi.BatchRequest } osapi.add(key, request) Description: Adds a service request to the batch associated with the specified key. A single batch request can contain both JSON-RPC calls (e.g. osapi.people.get()) and HTTP calls to third parties (e.g. osapi.http.get()). Parameters: Name Type Description key String A key to access the result of the given request from the parameter sent to the callback function. request osapi.Request A request to add to the batch. Returns: Type Description osapi.BatchRequest A batch request containing the given request (and any previously added requests).

<static> osapi.Request.execute(callback) Description: Executes all of the requests in the batch. Takes a callback for response processing, which is passed a JSON object mapping each request key to a JSON response object. Parameters: Name Type Description callback Function A callback function to handle the response.

An example illustrating two requests batched together: var batch = osapi.newBatch(). add("viewer", osapi.people.getViewer()). add('activities', osapi.activities.get({ userId : '@viewer', groupId : '@self'})). batch.execute(function(result) { if (!result.error) { alert('Hi, ' + result.viewer.name + '!'); alert('You have ' + result.activities.length + ' activities.'); } });

The error handling works exactly as it does for the JSON-RPC interface, since this api is based on that protocol. The JSON object returned reflects any errors that occurred in the request. This breaks down into 3 types of errors: Network error, these return a top level error. For example, in the callback, the object passed will have an error object.

Example: osapi.people.get({userId: '@owner', groupId: '@friends'}).execute(function(ownerFriends) { if (ownerFriends.error) { alert('Error occurred: ' + error.message); } else { alert('You have ' + ownerFriends.length + ' friends'); } }); Application Error for a Batched Request. In this case, a top-level error is set, but results are still returned for all individual requests that succeeded, if any. The individual request that failed has an error set. Note that 'error' is reserved and may not be used as a key to batch.add() as a property of a JSON RPC batch response item.

Example: Bailing out if there is any error in the batch: var batch = osapi.newBatch(). add("viewer", osapi.people.getViewer()). add('activities', osapi.activities.get({ userId : '@viewer', groupId : '@self'})). batch.execute(function(result) { if (result.error) { alert("This batch had an error: " + error.message); } else {alert('Hi, ' + result.viewer.name + '!'); alert('You have ' + result.activities.length + ' activities.'); } });

Example: Processing any sub requests in the batch that succeeded: var batch = osapi.newBatch(). add('v', osapi.people.getViewer()). add('vf', osapi.people.getViewerFriends()); batch.execute(function(result) { for (var name in result) { if (result.hasOwnProperty(name)) { if (result[name].error) { gadgets.log("Found an error: ", result[name].error.message); } else { gadgets.log("Got some data: ", result[name]); } } } });

Namespace for top-level people functions.

opensocial

<static> Type: { opensocial.Environment } opensocial.getEnvironment() Description: 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. Returns: Type Description opensocial.Environment The current environment

<static> Type: {Boolean} opensocial.hasPermission(permission) Description: 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. Parameters: Name Type Description permission opensocial.Permission The permission Returns: Type Description Boolean True if the gadget has access for the permission; false if it doesn't

<static> opensocial.invalidateCache() Description: Invalidates all resources cached for the current viewer.

<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

<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

<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

<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

<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

<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

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

<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 NOT_IMPLEMENTED. 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.

<static> opensocial.requestPermission(permissions, reason, opt_callback) Description: 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 NOT_IMPLEMENTED. Parameters: 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.

<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 NOT_IMPLEMENTED. 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

<static> opensocial.requestShareApp(recipients, reason, opt_callback, opt_params) Description: Requests the container to 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 NOT_IMPLEMENTED. Parameters: 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

<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.

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()

opensocial.Activity()

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

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. 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, they may ignore additional parameters. See also: opensocial.Activity.getField()

opensocial.Activity.Field

<static> Member of: opensocial.Activity.Field.APP_ID 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'.

<static> Member of: opensocial.Activity.Field.BODY Description: A string specifying an optional expanded version of an activity. Bodies may only have the following HTML tags: , <a>, . The container may ignore this formatting when rendering the activity. This field may be used interchangeably with the string 'body'.

<static> Member of: opensocial.Activity.Field.BODY_ID 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: , <a>, . The container may ignore this formatting when rendering the activity. This field may be used interchangeably with the string 'bodyId'.

<static> Member of: opensocial.Activity.Field.EXTERNAL_ID Description: An optional string ID generated by the posting application. This field may be used interchangeably with the string 'externalId'.

<static> Member of: opensocial.Activity.Field.ID 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'.

<static> Member of: opensocial.Activity.Field.MEDIA_ITEMS 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'.

<static> Member of: opensocial.Activity.Field.POSTED_TIME Description: A string specifying the time 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'.

<static> Member of: opensocial.Activity.Field.PRIORITY 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'.

<static> Member of: opensocial.Activity.Field.STREAM_FAVICON_URL Description: A string specifying the URL for the stream's favicon. This field may be used interchangeably with the string 'streamFaviconUrl'.

<static> Member of: opensocial.Activity.Field.STREAM_SOURCE_URL Description: A string specifying the stream's source URL. This field may be used interchangeably with the string 'streamSourceUrl'.

<static> Member of: opensocial.Activity.Field.STREAM_TITLE Description: A string specifing the title of the stream. This field may be used interchangeably with the string 'streamTitle'.

<static> Member of: opensocial.Activity.Field.STREAM_URL Description: A string specifying the stream's URL. This field may be used interchangeably with the string 'streamUrl'.

<static> Member of: opensocial.Activity.Field.TEMPLATE_PARAMS 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'.

<static> Member of: opensocial.Activity.Field.TITLE Description: A string specifying the primary text of an activity. Titles may only have the following HTML tags: , <a>, . The container may ignore this formatting when rendering the activity. This field may be used interchangeably with the string 'title'.

<static> Member of: opensocial.Activity.Field.TITLE_ID 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: , <a>, . The container may ignore this formatting when rendering the activity. This field may be used interchangeably with the string 'titleId'.

<static> Member of: opensocial.Activity.Field.URL Description: A string specifying the URL that represents this activity. This field may be used interchangeably with the string 'url'.

<static> Member of: opensocial.Activity.Field.USER_ID 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'.

Base interface for all address objects.

opensocial.Address()

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

All of the fields that an address has. These are the supported keys for the Address.getField() method.

opensocial.Address.Field

<static> Member of: opensocial.Address.Field.COUNTRY Description: The country, specified as a string. This field may be used interchangeably with the string 'country'.

<static> Member of: opensocial.Address.Field.EXTENDED_ADDRESS Description: The extended street address, specified as a string. This field may be used interchangeably with the string 'extendedAddress'.

<static> Member of: opensocial.Address.Field.LATITUDE Description: The latitude, specified as a number. This field may be used interchangeably with the string 'latitude'.

<static> Member of: opensocial.Address.Field.LOCALITY Description: The locality, specified as a string. This field may be used interchangeably with the string 'locality'.

<static> Member of: opensocial.Address.Field.LONGITUDE Description: The longitude, specified as a number. This field may be used interchangeably with the string 'longitude'.

<static> Member of: opensocial.Address.Field.PO_BOX 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'.

<static> Member of: opensocial.Address.Field.POSTAL_CODE Description: The postal code, specified as a string. This field may be used interchangeably with the string 'postalCode'.

<static> Member of: opensocial.Address.Field.REGION Description: The region, specified as a string. This field may be used interchangeably with the string 'region'.

<static> Member of: opensocial.Address.Field.STREET_ADDRESS Description: The street address, specified as a string. This field may be used interchangeably with the string 'streetAddress'.

<static> Member of: opensocial.Address.Field.TYPE 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'.

<static> Member of: opensocial.Address.Field.UNSTRUCTURED_ADDRESS 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'.

Class for Album features.

opensocial.Album

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

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()

opensocial.Album.Field

<static> Member of: opensocial.Album.Field.DESCRIPTION Description: string, description of the album. May be used interchangeably with the string 'description'.

<static> Member of: opensocial.Album.Field.ID Description: string, unique identifier for the album. May be used interchangeably with the string 'id'.

<static> Member of: opensocial.Album.Field.LOCATION Description: opensocial.Address, location corresponding to the album. May be used interchangeably with the string 'location'.

<static> Member of: opensocial.Album.Field.MEDIA_ITEM_COUNT Description: integer, number of items in the album. May be used interchangeably with the string 'mediaItemCount'.

<static> Member of: opensocial.Album.Field.MEDIA_MIME_TYPE Description: array of strings identifying the mime-types of media items in the Album. May be used interchangeably with the string 'mediaMimeType'.

<static> Member of: opensocial.Album.Field.MEDIA_TYPE Description: array of MediaItem.TYPE, types of MediaItems in the Album. May be used interchangeably with the string 'mediaType'.

<static> Member of: opensocial.Album.Field.OWNER_ID Description: string, ID of the owner of the album. May be used interchangeably with the string 'ownerId'.

<static> Member of: opensocial.Album.Field.THUMBNAIL_URL Description: string, URL to a thumbnail cover of the album. May be used interchangeably with the string 'thumbnailUrl'.

<static> Member of: opensocial.Album.Field.TITLE Description: string, the title of the album. May be used interchangeably with the string 'title'.

Base interface for all body type objects.

opensocial.BodyType()

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

All of the fields that a body type has. These are the supported keys for the BodyType.getField() method.

opensocial.BodyType.Field

<static> Member of: opensocial.BodyType.Field.BUILD 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'.

<static> Member of: opensocial.BodyType.Field.EYE_COLOR 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'.

<static> Member of: opensocial.BodyType.Field.HAIR_COLOR 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'.

<static> Member of: opensocial.BodyType.Field.HEIGHT 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'.

<static> Member of: opensocial.BodyType.Field.WEIGHT 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'.

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.

opensocial.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

The priorities a create activity request can have. See also: opensocial.requestCreateActivity()

opensocial.CreateActivityPriority

<static> Member of: opensocial.CreateActivityPriority.HIGH Description: 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'.

<static> Member of: opensocial.CreateActivityPriority.LOW Description: 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'.

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:

opensocial.DataRequest()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

The values needed to handle activity paging.

opensocial.DataRequest.ActivityRequestFields

<static> Member of: opensocial.DataRequest.ActivityRequestFields.FIRST Description: When paginating, the index of the first item to fetch; specified as a number.

<static> Member of: opensocial.DataRequest.ActivityRequestFields.MAX Description: The maximum number of items to fetch, specified as a number; defaults to 20.

The values needed to handle activity paging.

opensocial.DataRequest.AlbumRequestFields

<static> Member of: opensocial.DataRequest.AlbumRequestFields.FIRST Description: When paginating, the index of the first item to fetch; specified as a number.

<static> Member of: opensocial.DataRequest.AlbumRequestFields.MAX Description: The maximum number of items to fetch, specified as a number; defaults to 20.

opensocial.DataRequest.DataRequestFields

<static> Member of: opensocial.DataRequest.DataRequestFields.ESCAPE_TYPE Description: 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.

The filters available for limiting person requests.

opensocial.DataRequest.FilterType

<static> Member of: opensocial.DataRequest.FilterType.ALL Description: Retrieves all friends. This field may be used interchangeably with the string 'all'.

<static> Member of: opensocial.DataRequest.FilterType.HAS_APP Description: 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'.

<static> Member of: opensocial.DataRequest.FilterType.IS_FRIENDS_WITH Description: 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'.

<static> Member of: opensocial.DataRequest.FilterType.TOP_FRIENDS Description: 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'.

The values needed to handle activity paging.

opensocial.DataRequest.MediaItemRequestFields

<static> Member of: opensocial.DataRequest.MediaItemRequestFields.FIRST Description: When paginating, the index of the first item to fetch; specified as a number.

<static> Member of: opensocial.DataRequest.MediaItemRequestFields.MAX Description: The maximum number of items to fetch, specified as a number; defaults to 20.

opensocial.DataRequest.PeopleRequestFields

<static> Member of: opensocial.DataRequest.PeopleRequestFields.APP_DATA Description: 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'.

<static> Member of: opensocial.DataRequest.PeopleRequestFields.ESCAPE_TYPE Description: 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'.

<static> Member of: opensocial.DataRequest.PeopleRequestFields.FILTER Description: 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'.

<static> Member of: opensocial.DataRequest.PeopleRequestFields.FILTER_OPTIONS Description: Additional options to be passed into the filter, specified as a Map<String, Object>. This field may be used interchangeably with the string 'filterOptions'.

<static> Member of: opensocial.DataRequest.PeopleRequestFields.FIRST Description: When paginating, the index of the first item to fetch; specified as a number. This field may be used interchangeably with the string 'first'.

<static> Member of: opensocial.DataRequest.PeopleRequestFields.MAX Description: 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'.

<static> Member of: opensocial.DataRequest.PeopleRequestFields.PROFILE_DETAILS Description: 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'.

<static> Member of: opensocial.DataRequest.PeopleRequestFields.SORT_ORDER Description: 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'.

The sort orders available for ordering person objects.

opensocial.DataRequest.SortOrder

<static> Member of: opensocial.DataRequest.SortOrder.NAME Description: When used will sort people alphabetically by the name field. This field may be used interchangeably with the string 'name'.

<static> Member of: opensocial.DataRequest.SortOrder.TOP_FRIENDS Description: When used will sort people by the container's definition of top friends. This field may be used interchangeably with the string 'topFriends'.

This object contains the requested server data mapped to the requested keys. See also: DataRequest

opensocial.DataResponse()

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

Base interface for all email objects.

opensocial.Email()

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

All of the fields that an email has. These are the supported keys for the Email.getField() method.

opensocial.Email.Field

<static> Member of: opensocial.Email.Field.ADDRESS Description: The email address, specified as a string. This field may be used interchangeably with the string 'address'.

<static> Member of: opensocial.Email.Field.TYPE Description: 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'.

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.

opensocial.Enum()

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.

The enum keys used by the drinker field. See also: opensocial.Person.Field.Drinker

opensocial.Enum.Drinker

<static> Member of: opensocial.Enum.Drinker.HEAVILY Description: This field may be used interchangeably with the string 'HEAVILY'.

<static> Member of: opensocial.Enum.Drinker.NO Description: This field may be used interchangeably with the string 'NO'.

<static> Member of: opensocial.Enum.Drinker.OCCASIONALLY Description: This field may be used interchangeably with the string 'OCCASIONALLY'.

<static> Member of: opensocial.Enum.Drinker.QUIT Description: This field may be used interchangeably with the string 'QUIT'.

<static> Member of: opensocial.Enum.Drinker.QUITTING Description: This field may be used interchangeably with the string 'QUITTING'.

<static> Member of: opensocial.Enum.Drinker.REGULARLY Description: This field may be used interchangeably with the string 'REGULARLY'.

<static> Member of: opensocial.Enum.Drinker.SOCIALLY Description: This field may be used interchangeably with the string 'SOCIALLY'.

<static> Member of: opensocial.Enum.Drinker.YES Description: This field may be used interchangeably with the string 'YES'.

The enum keys used by the gender field. See also: opensocial.Person.Field.Gender

opensocial.Enum.Gender

<static> Member of: opensocial.Enum.Gender.FEMALE Description: This field may be used interchangeably with the string 'FEMALE'.

<static> Member of: opensocial.Enum.Gender.MALE Description: This field may be used interchangeably with the string 'MALE'.

The enum keys used by the lookingFor field. See also: opensocial.Person.Field.LookingFor

opensocial.Enum.LookingFor

<static> Member of: opensocial.Enum.LookingFor.ACTIVITY_PARTNERS Description: This field may be used interchangeably with the string 'ACTIVITY_PARTNERS'.

<static> Member of: opensocial.Enum.LookingFor.DATING Description: This field may be used interchangeably with the string 'DATING'.

<static> Member of: opensocial.Enum.LookingFor.FRIENDS Description: This field may be used interchangeably with the string 'FRIENDS'.

<static> Member of: opensocial.Enum.LookingFor.NETWORKING Description: This field may be used interchangeably with the string 'NETWORKING'.

<static> Member of: opensocial.Enum.LookingFor.RANDOM Description: This field may be used interchangeably with the string 'RANDOM'.

<static> Member of: opensocial.Enum.LookingFor.RELATIONSHIP Description: This field may be used interchangeably with the string 'RELATIONSHIP'.

The enum keys used by the networkPresence field. See also: opensocial.Person.Field.NetworkPresence

opensocial.Enum.Presence

<static> Member of: opensocial.Enum.Presence.AWAY Description: The entity or resource is temporarily away. This field may be used interchangeably with the string 'AWAY'.

<static> Member of: opensocial.Enum.Presence.CHAT Description: The entity or resource is actively interested in chatting. This field may be used interchangeably with the string 'CHAT'.

<static> Member of: opensocial.Enum.Presence.DND Description: The entity or resource is busy (dnd = "Do Not Disturb"). This field may be used interchangeably with the string 'DND'.

<static> Member of: opensocial.Enum.Presence.OFFLINE Description: The entity or resource is off line. This field may be used interchangeably with the string 'OFFLINE'.

<static> Member of: opensocial.Enum.Presence.ONLINE Description: The entity or resource is on line. This field may be used interchangeably with the string 'ONLINE'.

<static> Member of: opensocial.Enum.Presence.XA Description: The entity or resource is away for an extended period (xa = "eXtended Away"). This field may be used interchangeably with the string 'XA'.

The enum keys used by the smoker field. See also: opensocial.Person.Field.Smoker

opensocial.Enum.Smoker

<static> Member of: opensocial.Enum.Smoker.HEAVILY Description: This field may be used interchangeably with the string 'HEAVILY'.

<static> Member of: opensocial.Enum.Smoker.NO Description: This field may be used interchangeably with the string 'NO'.

<static> Member of: opensocial.Enum.Smoker.OCCASIONALLY Description: This field may be used interchangeably with the string 'OCCASIONALLY'.

<static> Member of: opensocial.Enum.Smoker.QUIT Description: This field may be used interchangeably with the string 'QUIT'.

<static> Member of: opensocial.Enum.Smoker.QUITTING Description: This field may be used interchangeably with the string 'QUITTING'.

<static> Member of: opensocial.Enum.Smoker.REGULARLY Description: This field may be used interchangeably with the string 'REGULARLY'.

<static> Member of: opensocial.Enum.Smoker.SOCIALLY Description: This field may be used interchangeably with the string 'SOCIALLY'.

<static> Member of: opensocial.Enum.Smoker.YES Description: This field may be used interchangeably with the string 'YES'.

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

opensocial.Environment()

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

Type: {Boolean} supportsField(objectType, fieldName) Description: Returns true if the specified field is supported in this container on the given object type, and returns false otherwise. Parameters: 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 Returns: 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()

opensocial.Environment.ObjectType

<static> Member of: opensocial.Environment.ObjectType.ACTIVITY Description: This field may be used interchangeably with the string 'activity'.

<static> Member of: opensocial.Environment.ObjectType.ADDRESS Description: This field may be used interchangeably with the string 'address'.

<static> Member of: opensocial.Environment.ObjectType.BODY_TYPE Description: This field may be used interchangeably with the string 'bodyType'.

<static> Member of: opensocial.Environment.ObjectType.EMAIL Description: This field may be used interchangeably with the string 'email'.

<static> Member of: opensocial.Environment.ObjectType.FILTER_TYPE Description: This field may be used interchangeably with the string 'filterType'.

<static> Member of: opensocial.Environment.ObjectType.MEDIA_ITEM Description: This field may be used interchangeably with the string 'mediaItem'.

<static> Member of: opensocial.Environment.ObjectType.MESSAGE Description: This field may be used interchangeably with the string 'message'.

<static> Member of: opensocial.Environment.ObjectType.MESSAGE_TYPE Description: This field may be used interchangeably with the string 'messageType'.

<static> Member of: opensocial.Environment.ObjectType.NAME Description: This field may be used interchangeably with the string 'name'.

<static> Member of: opensocial.Environment.ObjectType.ORGANIZATION Description: This field may be used interchangeably with the string 'organization'.

<static> Member of: opensocial.Environment.ObjectType.PERSON Description: This field may be used interchangeably with the string 'person'.

<static> Member of: opensocial.Environment.ObjectType.PHONE Description: This field may be used interchangeably with the string 'phone'.

<static> Member of: opensocial.Environment.ObjectType.SORT_ORDER Description: This field may be used interchangeably with the string 'sortOrder'.

<static> Member of: opensocial.Environment.ObjectType.URL Description: This field may be used interchangeably with the string 'url'.

The types of escaping that can be applied to person data or fields.

opensocial.EscapeType

<static> Member of: opensocial.EscapeType.HTML_ESCAPE Description: When used will HTML-escape the data. This field may be used interchangeably with the string 'htmlEscape'.

<static> Member of: opensocial.EscapeType.NONE Description: When used will not escape the data. This field may be used interchangeably with the string 'none'.

Base interface for all id spec objects.

opensocial.IdSpec()

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

All of the fields that id specs can have. See also: opensocial.IdSpec.getField()

opensocial.IdSpec.Field

<static> Member of: opensocial.IdSpec.Field.GROUP_ID Description: 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'.

<static> Member of: opensocial.IdSpec.Field.NETWORK_DISTANCE Description: 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'.

<static> Member of: opensocial.IdSpec.Field.USER_ID Description: 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'.

Constant group IDs available when fetching collections of people.

opensocial.IdSpec.GroupId

<static> Member of: opensocial.IdSpec.GroupId.ALL Description: This field may be used interchangeably with the string 'ALL'.

<static> Member of: opensocial.IdSpec.GroupId.FRIENDS Description: This field may be used interchangeably with the string 'FRIENDS'.

<static> Member of: opensocial.IdSpec.GroupId.SELF Description: This field may be used interchangeably with the string 'SELF'.

Constant person IDs available when fetching person information.

opensocial.IdSpec.PersonId

<static> Member of: opensocial.IdSpec.PersonId.OWNER Description: This field may be used interchangeably with the string 'OWNER'.

<static> Member of: opensocial.IdSpec.PersonId.VIEWER Description: This field may be used interchangeably with the string 'VIEWER'.

Represents images, movies, and audio. Create a MediaItem object using the opensocial.newMediaItem() method.

opensocial.MediaItem()

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

All of the fields that media items have. See also: opensocial.MediaItem.getField()

opensocial.MediaItem.Field

<static> Member of: opensocial.MediaItem.Field.ALBUM_ID Description: string, album to which the media item belongs This field may be used interchangeably with the string 'albumId'.

<static> Member of: opensocial.MediaItem.Field.CREATED Description: string, creation time associated with the media item - assigned by container in UTC This field may be used interchangeably with the string 'created'.

<static> Member of: opensocial.MediaItem.Field.DESCRIPTION Description: string, description of the media item This field may be used interchangeably with the string 'description'.

<static> Member of: opensocial.MediaItem.Field.DURATION 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'.

<static> Member of: opensocial.MediaItem.Field.FILE_SIZE Description: long, number of bytes (set to -1/undefined if unknown). This field may be used interchangeably with the string 'fileSize'.

<static> Member of: opensocial.MediaItem.Field.ID Description: string, id Associated with the media item This field may be used interchangeably with the string 'id'.

<static> Member of: opensocial.MediaItem.Field.LANGUAGE Description: string, language associated with the media item in ISO 639-3 format This field may be used interchangeably with the string 'language'.

<static> Member of: opensocial.MediaItem.Field.LAST_UPDATED Description: string, update time associated with the media item - assigned by container in UTC This field may be used interchangeably with the string 'lastUpdated'.

<static> Member of: opensocial.MediaItem.Field.LOCATION Description: opensocial.Address, location corresponding to the media item This field may be used interchangeably with the string 'location'.

<static> Member of: opensocial.MediaItem.Field.MIME_TYPE Description: The MIME type of media, specified as a string. This field may be used interchangeably with the string 'mimeType'.

<static> Member of: opensocial.MediaItem.Field.NUM_COMMENTS Description: integer, number of comments on the photo. This field may be used interchangeably with the string 'numComments'.

<static> Member of: opensocial.MediaItem.Field.NUM_VIEWS Description: integer, number of views for the media item. This field may be used interchangeably with the string 'numViews'.

<static> Member of: opensocial.MediaItem.Field.NUM_VOTES Description: integer, number of votes received for voting. This field may be used interchangeably with the string 'numVotes'.

<static> Member of: opensocial.MediaItem.Field.RATING Description: integer, average rating of the media item on a scale of 0-10. This field may be used interchangeably with the string 'rating'.

<static> Member of: opensocial.MediaItem.Field.START_TIME Description: string, for streaming/live content, time when the content is available. This field may be used interchangeably with the string 'startTime'.

<static> Member of: opensocial.MediaItem.Field.TAGGED_PEOPLE Description: array of strings, array of string (IDs) of people tagged in the media item This field may be used interchangeably with the string 'taggedPeople'.

<static> Member of: opensocial.MediaItem.Field.TAGS Description: array of strings, tags associated with this media item. This field may be used interchangeably with the string 'tags'.

<static> Member of: opensocial.MediaItem.Field.THUMBNAIL_URL Description: string, URL to a thumbnail image of the media item This field may be used interchangeably with the string 'thumbnailUrl'.

<static> Member of: opensocial.MediaItem.Field.TITLE Description: string describing the media item This field may be used interchangeably with the string 'title'.

<static> Member of: opensocial.MediaItem.Field.TYPE Description: The type of media, specified as a MediaItem.Type object. This field may be used interchangeably with the string 'type'.

<static> Member of: opensocial.MediaItem.Field.URL Description: A string specifying the URL where the media can be found. This field may be used interchangeably with the string 'url'.

The possible types of media items. See also: opensocial.MediaItem.Field

opensocial.MediaItem.Type

<static> Member of: opensocial.MediaItem.Type.AUDIO Description: This field may be used interchangeably with the string 'audio'.

<static> Member of: opensocial.MediaItem.Type.IMAGE Description: This field may be used interchangeably with the string 'image'.

<static> Member of: opensocial.MediaItem.Type.VIDEO Description: This field may be used interchangeably with the string 'video'.

Base interface for all message objects. * See also: opensocial.newMessage(), opensocial.requestSendMessage()

opensocial.Message()

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

All of the fields that messages can have. See also: opensocial.Message.getField()

opensocial.Message.Field

<static> Member of: opensocial.Message.Field.APP_URL Description: Identifies the application that generated this message. This field may be used interchangeably with the string 'appUrl'.

<static> Member of: opensocial.Message.Field.BODY Description: 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'.

<static> Member of: opensocial.Message.Field.BODY_ID Description: 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'.

<static> Member of: opensocial.Message.Field.COLLECTION_IDS Description: Identifies the messages collection IDs this message is contained in. This field may be used interchangeably with the string 'collectionIds'.

<static> Member of: opensocial.Message.Field.ID Description: unique ID for this message. This field may be used interchangeably with the string 'id'.

<static> Member of: opensocial.Message.Field.IN_REPLY_TO Description: 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'.

<static> Member of: opensocial.Message.Field.RECIPIENTS Description: Array of person IDs. This field may be used interchangeably with the string 'recipients'.

<static> Member of: opensocial.Message.Field.REPLIES Description: 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'.

<static> Member of: opensocial.Message.Field.SENDER_ID Description: id of person who sent the message. This field may be used interchangeably with the string 'senderId'.

<static> Member of: opensocial.Message.Field.STATUS Description: Status of the message. (NEW, READ, DELETED). This field may be used interchangeably with the string 'status'.

<static> Member of: opensocial.Message.Field.TIME_SENT Description: UTC time message was sent. This field may be used interchangeably with the string 'timeSent'.

<static> Member of: opensocial.Message.Field.TITLE Description: 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'.

<static> Member of: opensocial.Message.Field.TITLE_ID Description: The title 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'.

<static> Member of: opensocial.Message.Field.TYPE Description: The title of the message, specified as an opensocial.Message.Type. This field may be used interchangeably with the string 'type'.

<static> Member of: opensocial.Message.Field.UPDATED Description: last update for this message . This field may be used interchangeably with the string 'updated'.

<static> Member of: opensocial.Message.Field.URLS Description: 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'.

Class for MessageCollection features.

opensocial.MessageCollection

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

All of the fields that a MessageCollection can have. It is only required to set ID. See also: opensocial.MessageCollection.getField()

opensocial.MessageCollection.Field

<static> Member of: opensocial.MessageCollection.Field.ID Description: string, unique ID for this message collection. May be used interchangeably with the string 'id'.

<static> Member of: opensocial.MessageCollection.Field.TITLE Description: string, the title of the MessageCollection. May be used interchangeably with the string 'title'.

<static> Member of: opensocial.MessageCollection.Field.TOTAL Description: int, total number of messages in this group. May be used interchangeably with the string 'total'.

<static> Member of: opensocial.MessageCollection.Field.UNREAD Description: int, number of unread messages in this group. May be used interchangeably with the string 'unread'.

<static> Member of: opensocial.MessageCollection.Field.UPDATED Description: string, last datetime update for this message collection. May be used interchangeably with the string 'updated'.

<static> Member of: opensocial.MessageCollection.Field.URLS Description: 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'.

Base interface for all name objects.

opensocial.Name()

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

All of the fields that a name has. These are the supported keys for the Name.getField() method.

opensocial.Name.Field

<static> Member of: opensocial.Name.Field.ADDITIONAL_NAME Description: The additional name, specified as a string. This field may be used interchangeably with the string 'additionalName'.

<static> Member of: opensocial.Name.Field.FAMILY_NAME Description: The family name, specified as a string. This field may be used interchangeably with the string 'familyName'.

<static> Member of: opensocial.Name.Field.GIVEN_NAME Description: The given name, specified as a string. This field may be used interchangeably with the string 'givenName'.

<static> Member of: opensocial.Name.Field.HONORIFIC_PREFIX Description: The honorific prefix, specified as a string. This field may be used interchangeably with the string 'honorificPrefix'.

<static> Member of: opensocial.Name.Field.HONORIFIC_SUFFIX Description: The honorific suffix, specified as a string. This field may be used interchangeably with the string 'honorificSuffix'.

<static> Member of: opensocial.Name.Field.UNSTRUCTURED Description: The unstructured name, specified as a string. This field may be used interchangeably with the string 'unstructured'.

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.

opensocial.NavigationParameters()

Type: {String} getField(key, opt_params) Description: Gets the NavigationParameters' 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 NavigationParameters associated with the given key. Parameters: Name Type Description key String The key to set data for data Object The data to set

The destinations available for navigation in requestShareApp and requestSendMessage.

opensocial.NavigationParameters.DestinationType

<static> Member of: opensocial.NavigationParameters.DestinationType.RECIPIENT_DESTINATION Description: This field may be used interchangeably with the string 'recipientDestination'.

<static> Member of: opensocial.NavigationParameters.DestinationType.VIEWER_DESTINATION Description: This field may be used interchangeably with the string 'viewerDestination'.

All of the fields that NavigationParameters can have. See also: opensocial.NavigationParameters.getField()

opensocial.NavigationParameters.Field

<static> Member of: opensocial.NavigationParameters.Field.OWNER Description: A string representing the owner id. This field may be used interchangeably with the string 'owner'.

<static> Member of: opensocial.NavigationParameters.Field.PARAMETERS Description: 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'.

<static> Member of: opensocial.NavigationParameters.Field.VIEW Description: The gadgets.views.View to navigate to. This field may be used interchangeably with the string 'view'.

Base interface for all organization objects.

opensocial.Organization()

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

All of the fields that a organization has. These are the supported keys for the Organization.getField() method.

opensocial.Organization.Field

<static> Member of: opensocial.Organization.Field.ADDRESS Description: 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'.

<static> Member of: opensocial.Organization.Field.DESCRIPTION Description: 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'.

<static> Member of: opensocial.Organization.Field.END_DATE 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'.

<static> Member of: opensocial.Organization.Field.FIELD Description: 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'.

<static> Member of: opensocial.Organization.Field.NAME Description: 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'.

<static> Member of: opensocial.Organization.Field.SALARY Description: 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'.

<static> Member of: opensocial.Organization.Field.START_DATE Description: 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'.

<static> Member of: opensocial.Organization.Field.SUB_FIELD Description: 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'.

<static> Member of: opensocial.Organization.Field.TITLE Description: 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'.

<static> Member of: opensocial.Organization.Field.WEBPAGE Description: 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'.

The permissions an app can ask for. See also: opensocial.hasPermission(), opensocial.requestPermission()

opensocial.Permission

<static> Member of: opensocial.Permission.VIEWER Description: Access to the viewer person object This field may be used interchangeably with the string 'viewer'.

Base interface for all person objects.

opensocial.Person()

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

All of the fields that a person has. These are the supported keys for the Person.getField() method.

opensocial.Person.Field

<static> Member of: opensocial.Person.Field.ABOUT_ME Description: 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'.

<static> Member of: opensocial.Person.Field.ACTIVITIES Description: 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'.

<static> Member of: opensocial.Person.Field.ADDRESSES Description: 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'.

<static> Member of: opensocial.Person.Field.AGE Description: Person's age, specified as a number. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'age'.

<static> Member of: opensocial.Person.Field.BODY_TYPE Description: 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'.

<static> Member of: opensocial.Person.Field.BOOKS Description: 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'.

<static> Member of: opensocial.Person.Field.CARS Description: 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'.

<static> Member of: opensocial.Person.Field.CHILDREN Description: 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'.

<static> Member of: opensocial.Person.Field.CURRENT_LOCATION Description: 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'.

<static> Member of: opensocial.Person.Field.DATE_OF_BIRTH Description: 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'.

<static> Member of: opensocial.Person.Field.DRINKER Description: 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'.

<static> Member of: opensocial.Person.Field.EMAILS Description: 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'.

<static> Member of: opensocial.Person.Field.ETHNICITY Description: Person's ethnicity, specified as a string. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'ethnicity'.

<static> Member of: opensocial.Person.Field.FASHION Description: 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'.

<static> Member of: opensocial.Person.Field.FOOD Description: 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'.

<static> Member of: opensocial.Person.Field.GENDER Description: 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'.

<static> Member of: opensocial.Person.Field.HAPPIEST_WHEN Description: 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'.

<static> Member of: opensocial.Person.Field.HAS_APP Description: 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'.

<static> Member of: opensocial.Person.Field.HEROES Description: 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'.

<static> Member of: opensocial.Person.Field.HUMOR Description: 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'.

<static> Member of: opensocial.Person.Field.ID Description: 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.

<static> Member of: opensocial.Person.Field.INTERESTS Description: 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'.

<static> Member of: opensocial.Person.Field.JOB_INTERESTS Description: Person's favorite jobs, or job interests and skills, specified as a string. Container support for this field is OPTIONAL. This field may be used interchangeably with the string 'jobInterests'.

<static> Member of: opensocial.Person.Field.JOBS Description: 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'.

<static> Member of: opensocial.Person.Field.LANGUAGES_SPOKEN Description: 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'.

<static> Member of: opensocial.Person.Field.LIVING_ARRANGEMENT Description: 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'.

<static> Member of: opensocial.Person.Field.LOOKING_FOR Description: 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'.

<static> Member of: opensocial.Person.Field.MOVIES Description: 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'.

<static> Member of: opensocial.Person.Field.MUSIC Description: 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'.

<static> Member of: opensocial.Person.Field.NAME Description: 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.

<static> Member of: opensocial.Person.Field.NETWORK_PRESENCE Description: 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'.

<static> Member of: opensocial.Person.Field.NICKNAME Description: 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.

<static> Member of: opensocial.Person.Field.PETS Description: 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'.

<static> Member of: opensocial.Person.Field.PHONE_NUMBERS Description: 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'.

<static> Member of: opensocial.Person.Field.POLITICAL_VIEWS Description: 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'.

<static> Member of: opensocial.Person.Field.PROFILE_SONG Description: 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'.

<static> Member of: opensocial.Person.Field.PROFILE_URL Description: 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'.

<static> Member of: opensocial.Person.Field.PROFILE_VIDEO Description: 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'.

<static> Member of: opensocial.Person.Field.QUOTES Description: 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'.

<static> Member of: opensocial.Person.Field.RELATIONSHIP_STATUS Description: 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'.

<static> Member of: opensocial.Person.Field.RELIGION Description: 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'.

<static> Member of: opensocial.Person.Field.ROMANCE Description: 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'.

<static> Member of: opensocial.Person.Field.SCARED_OF Description: 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'.

<static> Member of: opensocial.Person.Field.SCHOOLS Description: 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'.

<static> Member of: opensocial.Person.Field.SEXUAL_ORIENTATION Description: 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'.

<static> Member of: opensocial.Person.Field.SMOKER Description: 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'.

<static> Member of: opensocial.Person.Field.SPORTS Description: 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'.

<static> Member of: opensocial.Person.Field.STATUS Description: 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'.

<static> Member of: opensocial.Person.Field.TAGS Description: 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'.

<static> Member of: opensocial.Person.Field.THUMBNAIL_URL Description: 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.

<static> Member of: opensocial.Person.Field.TIME_ZONE Description: 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'.

<static> Member of: opensocial.Person.Field.TURN_OFFS Description: 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'.

<static> Member of: opensocial.Person.Field.TURN_ONS Description: 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'.

<static> Member of: opensocial.Person.Field.TV_SHOWS Description: 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'.

<static> Member of: opensocial.Person.Field.URLS Description: 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'.

Base interface for all phone objects.

opensocial.Phone()

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

All of the fields that a phone has. These are the supported keys for the Phone.getField() method.

opensocial.Phone.Field

<static> Member of: opensocial.Phone.Field.NUMBER Description: The phone number, specified as a string. This field may be used interchangeably with the string 'number'.

<static> Member of: opensocial.Phone.Field.TYPE Description: 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'.

Represents a response that was generated by processing a data request item on the server.

opensocial.ResponseItem()

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

Error codes that a response item can return.

opensocial.ResponseItem.Error

<static> Member of: opensocial.ResponseItem.Error.BAD_REQUEST Description: The request was invalid. Example: 'max' was -1. This field may be used interchangeably with the string 'badRequest'.

<static> Member of: opensocial.ResponseItem.Error.FORBIDDEN Description: The gadget can never have access to the requested data. This field may be used interchangeably with the string 'forbidden'.

<static> Member of: opensocial.ResponseItem.Error.INTERNAL_ERROR Description: The request encountered an unexpected condition that prevented it from fulfilling the request. This field may be used interchangeably with the string 'internalError'.

<static> Member of: opensocial.ResponseItem.Error.LIMIT_EXCEEDED Description: 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'.

<static> Member of: opensocial.ResponseItem.Error.NOT_IMPLEMENTED Description: This container does not support the request that was made. This field may be used interchangeably with the string 'notImplemented'.

<static> Member of: opensocial.ResponseItem.Error.UNAUTHORIZED Description: 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'.

Base interface for all URL objects.

opensocial.Url()

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

All of the fields that a URL has. These are the supported keys for the Url.getField() method.

opensocial.Url.Field

<static> Member of: opensocial.Url.Field.ADDRESS Description: The address the URL points to, specified as a string. This field may be used interchangeably with the string 'address'.

<static> Member of: opensocial.Url.Field.LINK_TEXT Description: The text of the link, specified as a string. This field may be used interchangeably with the string 'linkText'.

<static> Member of: opensocial.Url.Field.TYPE Description: 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'.