My favorites | English | Sign in

OpenSocial API Reference

(OpenSocial API v0.8.1)

The OpenSocial JavaScript API includes two namespaces: opensocial.* and gadgets.*. This page covers the opensocial.* namespace. The gadgets.* namespace is covered in the Gadgets API Reference.

Contents

Back to top

Type Conventions

This document uses the following conventions for types:

Array<T> or Array.<T>
An Array filled with only objects of type T. This convention is similar to Java generics.
Map<K, V> or Map.<K, V>
A JavaScript object with keys of type K that map to values of type V. Again, this convention is similar to Java generics. It's often used for opt_params variables.
static
A type marked with static class has no public or private constructor. In other words, the type is a namespace, not a class that can be instantiated to create objects. The fields and functions in such a type are also marked as static.
Boolean
A boolean value (not a Boolean object).
String
A string value (not a String object).

Back to top

Static Class opensocial

 SUMMARY     DETAIL

Namespace for top-level people functions.

Method Summary

<static>  opensocial.Environment getEnvironment()
Gets the current environment for this gadget.
<static>  Boolean hasPermission(permission)
Returns true if the current gadget has access to the specified permission.
<static>  opensocial.Activity newActivity(params)
Creates an activity object, which represents an activity on the server.
<static>  opensocial.DataRequest newDataRequest()
Creates a data request object to use for sending and fetching data from the server.
<static>  opensocial.IdSpec newIdSpec(parameters)
Creates an IdSpec object.
<static>  opensocial.MediaItem newMediaItem(mimeType, url, opt_params)
Creates a media item.
<static>  opensocial.Message newMessage(body, opt_params)
Creates a media item associated with an activity.
<static>  opensocial.NavigationParameters newNavigationParameters(parameters)
Creates a NavigationParameters object.
<static> requestCreateActivity(activity, priority, opt_callback)
Takes an activity and tries to create it, without waiting for the operation to complete.
<static> requestPermission(permissions, reason, opt_callback)
Requests the user to grant access to the specified permissions.
<static> requestSendMessage(recipients, message, opt_callback, opt_params)
Requests the container to send a specific message to the specified users.
<static> requestShareApp(recipients, reason, opt_callback, opt_params)
Requests the container to share this gadget with the specified users.
 

Method Detail

getEnvironment

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

hasPermission

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

newActivity

<static> opensocial.Activity newActivity(params)
    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:
      Map.<opensocial.Activity.Field, Object> params - Parameters defining the activity
    Returns:
      opensocial.Activity  The new activity object

newDataRequest

<static> opensocial.DataRequest newDataRequest()
    Creates a data request object to use for sending and fetching data from the server.
    Returns:
      opensocial.DataRequest  The request object

newIdSpec

<static> opensocial.IdSpec newIdSpec(parameters)
    Creates an IdSpec object.
    Parameters:
      Map.<opensocial.IdSpec.Field, Object> parameters - Parameters defining the id spec
    Returns:
      opensocial.IdSpec  The new IdSpec object

newMediaItem

<static> opensocial.MediaItem newMediaItem(mimeType, url, opt_params)
    Creates a media item. Represents images, movies, and audio. Used when creating activities on the server.
    Parameters:
      String url - Where the media can be found
      Map.<opensocial.MediaItem.Field, Object> opt_params - Any other fields that should be set on the media item object; all of the defined Fields are supported
    Returns:
      opensocial.MediaItem  The new media item object

newMessage

<static> opensocial.Message newMessage(body, opt_params)
    Creates a media item associated with an activity. Represents images, movies, and audio. Used when creating activities on the server.
    Parameters:
      String body - The main text of the message
      Map.<opensocial.Message.Field, Object> opt_params - Any other fields that should be set on the message object; all of the defined Fields are supported
    Returns:
      opensocial.Message  The new message object

newNavigationParameters

<static> opensocial.NavigationParameters newNavigationParameters(parameters)
    Parameters:
      Map.<opensocial.NavigationParameters.Field, Object> parameters - Parameters defining the navigation

requestCreateActivity

<static> requestCreateActivity(activity, priority, opt_callback)
    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:
      opensocial.Activity activity - The activity to create
      opensocial.CreateActivityPriority priority - The priority for this request
      Function opt_callback - The function to call once the request has been processed.

requestPermission

<static> requestPermission(permissions, reason, opt_callback)
    Requests the user to grant access to the specified permissions. If the container does not support this method the callback will be called with a opensocial.ResponseItem. The response item will have its error code set to NOT_IMPLEMENTED.
    Parameters:
      Array.<opensocial.Permission> permissions - The permissions to request from the viewer
      String reason - Displayed to the user as the reason why these permissions are needed
      Function opt_callback - 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.

requestSendMessage

<static> requestSendMessage(recipients, message, opt_callback, opt_params)
    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:
      Array.<String>, String recipients - An ID, array of IDs, or a group reference; the supported keys are VIEWER, OWNER, VIEWER_FRIENDS, OWNER_FRIENDS, or a single ID within one of those groups
      opensocial.Message message - The message to send to the specified users
      Function opt_callback - The function to call once the request has been processed; either this callback will be called or the gadget will be reloaded from scratch
      opensocial.NavigationParameters opt_params - 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

requestShareApp

<static> requestShareApp(recipients, reason, opt_callback, opt_params)
    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:
      Array.<String>, String recipients - An ID, array of IDs, or a group reference; the supported keys are VIEWER, OWNER, VIEWER_FRIENDS, OWNER_FRIENDS, or a single ID within one of those groups
      opensocial.Message reason - 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.
      Function opt_callback - The function to call once the request has been processed; either this callback will be called or the gadget will be reloaded from scratch
      opensocial.NavigationParameters opt_params - 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

Back to top

Class opensocial.Activity

 SUMMARY     DETAIL

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

Method Summary

 String getField(key, opt_params)
Gets the activity data that's associated with the specified key.
 String getId()
Gets an ID that can be permanently associated with this activity.
setField(key, data)
Sets data for this activity associated with the given key.
 

Method Detail

getField

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

getId

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

setField

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

Back to top

Static Class opensocial.Activity.Field

 SUMMARY     DETAIL

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

Field Summary

<static> object APP_ID
A string specifying the application that this activity is associated with.
<static> object BODY

A string specifying an optional expanded version of an activity.

<static> object BODY_ID

A string specifying the body template message ID in the gadget spec.

<static> object EXTERNAL_ID
An optional string ID generated by the posting application.
<static> object ID
A string ID that is permanently associated with this activity.
<static> object MEDIA_ITEMS
Any photos, videos, or images that should be associated with the activity.
<static> object POSTED_TIME
A string specifying the time at which this activity took place in milliseconds since the epoch.
<static> object PRIORITY
A number between 0 and 1 representing the relative priority of this activity in relation to other activities from the same source
<static> object STREAM_FAVICON_URL
A string specifying the URL for the stream's favicon.
<static> object STREAM_SOURCE_URL
A string specifying the stream's source URL.
<static> object STREAM_TITLE
A string specifing the title of the stream.
<static> object STREAM_URL
A string specifying the stream's URL.
<static> object TEMPLATE_PARAMS

A map of custom key/value pairs associated with this activity.

<static> object TITLE

A string specifying the primary text of an activity.

<static> object TITLE_ID

A string specifying the title template message ID in the gadget spec.

<static> object URL
A string specifying the URL that represents this activity.
<static> object USER_ID
The string ID of the user who this activity is for.
 

Field Detail

APP_ID

<static> object APP_ID
    A string specifying the application that this activity is associated with. This value can not be set.

BODY

<static> object BODY

    A string specifying an optional expanded version of an activity.

    Bodies may only have the following HTML tags: <b> <i>, <a>, <span>. The container may ignore this formatting when rendering the activity.

BODY_ID

<static> object BODY_ID

    A string specifying the body template message ID in the gadget spec.

    The body is an optional expanded version of an activity.

    Bodies may only have the following HTML tags: <b> <i>, <a>, <span>. The container may ignore this formatting when rendering the activity.

EXTERNAL_ID

<static> object EXTERNAL_ID
    An optional string ID generated by the posting application.

ID

<static> object ID
    A string ID that is permanently associated with this activity. This value can not be set.

MEDIA_ITEMS

<static> object MEDIA_ITEMS
    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>.

POSTED_TIME

<static> object POSTED_TIME
    A string specifying the time at which this activity took place in milliseconds since the epoch. This value can not be set.

PRIORITY

<static> object PRIORITY
    A number between 0 and 1 representing the relative priority of this activity in relation to other activities from the same source

STREAM_FAVICON_URL

<static> object STREAM_FAVICON_URL
    A string specifying the URL for the stream's favicon.

STREAM_SOURCE_URL

<static> object STREAM_SOURCE_URL
    A string specifying the stream's source URL.

STREAM_TITLE

<static> object STREAM_TITLE
    A string specifing the title of the stream.

STREAM_URL

<static> object STREAM_URL
    A string specifying the stream's URL.

TEMPLATE_PARAMS

<static> object TEMPLATE_PARAMS

    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.

TITLE

<static> object TITLE

    A string specifying the primary text of an activity.

    Titles may only have the following HTML tags: <b> <i>, <a>, <span>. The container may ignore this formatting when rendering the activity.

TITLE_ID

<static> object TITLE_ID

    A string specifying the title template message ID in the gadget spec.

    The title is the primary text of an activity.

    Titles may only have the following HTML tags: <b> <i>, <a>, <span>. The container may ignore this formatting when rendering the activity.

URL

<static> object URL
    A string specifying the URL that represents this activity.

USER_ID

<static> object USER_ID
    The string ID of the user who this activity is for. This value can not be set.

Back to top

Class opensocial.Address

 SUMMARY     DETAIL

Base interface for all address objects.

Method Summary

 String getField(key, opt_params)
Gets data for this body type that is associated with the specified key.
 

Method Detail

getField

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

Back to top

Static Class opensocial.Address.Field

 SUMMARY     DETAIL

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

Field Summary

<static> object COUNTRY
The country, specified as a string.
<static> object EXTENDED_ADDRESS
The extended street address, specified as a string.
<static> object LATITUDE
The latitude, specified as a number.
<static> object LOCALITY
The locality, specified as a string. This field is usually used to specify a small geographical concept, such as a city (for example, Mountain View or Chicago).
<static> object LONGITUDE
The longitude, specified as a number.
<static> object PO_BOX
The P.O.
<static> object POSTAL_CODE
The postal code, specified as a string.
<static> object REGION
The region, specified as a string. This field is usually used to specify a large geographical concept, such as a state (for example, California or Florida).
<static> object STREET_ADDRESS
The street address, specified as a string.
<static> object TYPE
The address type or label, specified as a string.
<static> object UNSTRUCTURED_ADDRESS
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.
 

Field Detail

COUNTRY

<static> object COUNTRY
    The country, specified as a string.

EXTENDED_ADDRESS

<static> object EXTENDED_ADDRESS
    The extended street address, specified as a string.

LATITUDE

<static> object LATITUDE
    The latitude, specified as a number.

LOCALITY

<static> object LOCALITY
    The locality, specified as a string. This field is usually used to specify a small geographical concept, such as a city (for example, Mountain View or Chicago).

LONGITUDE

<static> object LONGITUDE
    The longitude, specified as a number.

PO_BOX

<static> object PO_BOX
    The P.O. box of the address, if there is one; specified as a string.

POSTAL_CODE

<static> object POSTAL_CODE
    The postal code, specified as a string.

REGION

<static> object REGION
    The region, specified as a string. This field is usually used to specify a large geographical concept, such as a state (for example, California or Florida).

STREET_ADDRESS

<static> object STREET_ADDRESS
    The street address, specified as a string.

TYPE

<static> object TYPE
    The address type or label, specified as a string. Examples: work, my favorite store, my house, etc.

UNSTRUCTURED_ADDRESS

<static> object UNSTRUCTURED_ADDRESS
    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.

Back to top

Class opensocial.BodyType

 SUMMARY     DETAIL

Base interface for all body type objects.

Method Summary

 String getField(key, opt_params)
Gets data for this body type that is associated with the specified key.
 

Method Detail

getField

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

Back to top

Static Class opensocial.BodyType.Field

 SUMMARY     DETAIL

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

Field Summary

<static> object BUILD
The build of the person's body, specified as a string.
<static> object EYE_COLOR
The eye color of the person, specified as a string.
<static> object HAIR_COLOR
The hair color of the person, specified as a string.
<static> object HEIGHT
The height of the person in meters, specified as a number.
<static> object WEIGHT
The weight of the person in kilograms, specified as a number.
 

Field Detail

BUILD

<static> object BUILD
    The build of the person's body, specified as a string. Container support for this field is OPTIONAL.

EYE_COLOR

<static> object EYE_COLOR
    The eye color of the person, specified as a string. Container support for this field is OPTIONAL.

HAIR_COLOR

<static> object HAIR_COLOR
    The hair color of the person, specified as a string. Container support for this field is OPTIONAL.

HEIGHT

<static> object HEIGHT
    The height of the person in meters, specified as a number. Container support for this field is OPTIONAL.

WEIGHT

<static> object WEIGHT
    The weight of the person in kilograms, specified as a number. Container support for this field is OPTIONAL.

Back to top

Class opensocial.Collection

 SUMMARY     DETAIL

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.

Method Summary

 Array.<Object> asArray()
Returns an array of all the objects in this collection.
each(fn)
Executes the provided function once per member of the collection, with each member in turn as the parameter to the function.
 Object? getById(id)
Finds the entry with the given ID value, or returns null if none is found.
 Number getOffset()
Gets the offset of this collection within a larger result set.
 Number getTotalSize()
Gets the total size of the larger result set that this collection belongs to.
 Number size()
Gets the size of this collection, which is equal to or less than the total size of the result.
 

Method Detail

asArray

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

each

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

getById

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

getOffset

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

getTotalSize

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

size

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

Back to top

Static Class opensocial.CreateActivityPriority

 SUMMARY     DETAIL

The priorities a create activity request can have.

See also: opensocial.requestCreateActivity()

Field Summary

<static> object HIGH
If the activity is of high importance, it will be created even if this requires asking the user for permission.
<static> object LOW
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.
 

Field Detail

HIGH

<static> object HIGH
    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.

LOW

<static> object LOW
    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.

Back to top

Class opensocial.DataRequest

 SUMMARY     DETAIL

Used to request social information from the container. This includes data for friends, profiles, app data, and activities. All apps that require access to people information should send a DataRequest.

Here's an example of creating, initializing, sending, and handling the results of a data request: 

function requestMe() {
  var req = opensocial.newDataRequest();
  req.add(req.newFetchPersonRequest(
            opensocial.IdSpec.PersonId.VIEWER),
          "viewer");
  req.send(handleRequestMe);
};

function handleRequestMe(data) {
  var viewer = data.get("viewer");
  if (viewer.hadError()) {
    //Handle error using viewer.getError()...
    return;
  }

  //No error. Do something with viewer.getData()...
}

See also: opensocial.newDataRequest()

Method Summary

add(request, opt_key)
Adds an item to fetch (get) or update (set) data from the server.
 Object newFetchActivitiesRequest(idSpec, opt_params)
Creates an item to request an activity stream from the server.
 Object newFetchPeopleRequest(idSpec, opt_params)
Creates an item to request friends from the server.
 Object newFetchPersonAppDataRequest(idSpec, keys, opt_params)
Creates an item to request app data for the given people.
 Object newFetchPersonRequest(id, opt_params)
Creates an item to request a profile for the specified person ID.
 Object newRemovePersonAppDataRequest(id, keys)
Deletes the given keys from the datastore for the given person.
 Object newUpdatePersonAppDataRequest(id, key, value)
Creates an item to request an update of an app field for the given person.
send(opt_callback)
Sends a data request to the server in order to get a data response.
 

Method Detail

add

add(request, opt_key)
    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:
      Object request - Specifies which data to fetch or update
      String opt_key - A key to map the generated response data to

newFetchActivitiesRequest

Object newFetchActivitiesRequest(idSpec, opt_params)
    Creates an item to request an activity stream from the server.

    When processed, returns a Collection<Activity>.

    Parameters:
      opensocial.IdSpec idSpec - An IdSpec used to specify which people to fetch. See also IdSpec.
      Map.<opensocial.DataRequest.ActivityRequestFields, Object> opt_params - Additional parameters to pass to the request; not currently used
    Returns:
      Object  A request object

newFetchPeopleRequest

Object newFetchPeopleRequest(idSpec, opt_params)
    Creates an item to request friends from the server. When processed, returns a Collection <Person> object.
    Parameters:
      opensocial.IdSpec idSpec - An IdSpec used to specify which people to fetch. See also IdSpec.
      Map.<opensocial.DataRequest.PeopleRequestFields, Object> opt_params - Additional params to pass to the request
    Returns:
      Object  A request object

newFetchPersonAppDataRequest

Object newFetchPersonAppDataRequest(idSpec, keys, opt_params)
    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:
      opensocial.IdSpec idSpec - An IdSpec used to specify which people to fetch. See also IdSpec.
      Array.<String>, String keys - The keys you want data for; this can be an array of key names, a single key name, or "*" to mean "all keys"
      Map.<opensocial.DataRequest.DataRequestFields, Object> opt_params - Additional params to pass to the request
    Returns:
      Object  A request object

newFetchPersonRequest

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

newRemovePersonAppDataRequest

Object newRemovePersonAppDataRequest(id, keys)
    Deletes the given keys from the datastore for the given person. When processed, does not return any data.
    Parameters:
      String id - The ID of the person to update; only the special VIEWER ID is currently allowed.
      Array.<String>, String keys - 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:
      Object  A request object

newUpdatePersonAppDataRequest

Object newUpdatePersonAppDataRequest(id, key, value)
    Creates an item to request an update of an app field for the given person. When processed, does not return any data.
    Parameters:
      String id - The ID of the person to update; only the special VIEWER ID is currently allowed.
      String key - The name of the key. This may only contain alphanumeric (A-Za-z0-9) characters, underscore(_), dot(.) or dash(-).
      Object value - The value, must be valid json
    Returns:
      Object  A request object

send

send(opt_callback)
    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:
      Function opt_callback - The function to call with the data response generated by the server

Back to top

Static Class opensocial.DataRequest.DataRequestFields

 SUMMARY     DETAIL

Field Summary

<static> object ESCAPE_TYPE
How to escape person data returned from the server; defaults to HTML_ESCAPE.
 

Field Detail

ESCAPE_TYPE

<static> object ESCAPE_TYPE
    How to escape person data returned from the server; defaults to HTML_ESCAPE. Possible values are defined by EscapeType.

Back to top

Static Class opensocial.DataRequest.FilterType

 SUMMARY     DETAIL

The filters available for limiting person requests.

Field Summary

<static> object ALL
Retrieves all friends.
<static> object HAS_APP
Retrieves all friends that use this application.
<static> object TOP_FRIENDS
Retrieves only the user's top friends as defined by the container.
 

Field Detail

ALL

<static> object ALL
    Retrieves all friends.

HAS_APP

<static> object HAS_APP
    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.

TOP_FRIENDS

<static> object TOP_FRIENDS
    Retrieves only the user's top friends as defined by the container. Container support for this filter type is OPTIONAL.

Back to top

Static Class opensocial.DataRequest.PeopleRequestFields

 SUMMARY     DETAIL

Field Summary

<static> object FILTER
How to filter the people objects; defaults to ALL.
<static> object FILTER_OPTIONS
Additional options to be passed into the filter, specified as a Map<String, Object>.
<static> object FIRST
When paginating, the index of the first item to fetch; specified as a number.
<static> object MAX
The maximum number of items to fetch, specified as a number; defaults to 20.
<static> object PROFILE_DETAILS
An array of opensocial.Person.Field specifying what profile data to fetch for each of the person objects.
<static> object SORT_ORDER
A sort order for the people objects; defaults to TOP_FRIENDS.
 

Field Detail

FILTER

<static> object FILTER
    How to filter the people objects; defaults to ALL. Possible values are defined by FilterType.

FILTER_OPTIONS

<static> object FILTER_OPTIONS
    Additional options to be passed into the filter, specified as a Map<String, Object>.

FIRST

<static> object FIRST
    When paginating, the index of the first item to fetch; specified as a number.

MAX

<static> object MAX
    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.

PROFILE_DETAILS

<static> object PROFILE_DETAILS
    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.

SORT_ORDER

<static> object SORT_ORDER
    A sort order for the people objects; defaults to TOP_FRIENDS. Possible values are defined by SortOrder.

Back to top

Static Class opensocial.DataRequest.SortOrder

 SUMMARY     DETAIL

The sort orders available for ordering person objects.

Field Summary

<static> object NAME
When used will sort people alphabetically by the name field.
<static> object TOP_FRIENDS
When used will sort people by the container's definition of top friends.
 

Field Detail

NAME

<static> object NAME
    When used will sort people alphabetically by the name field.

TOP_FRIENDS

<static> object TOP_FRIENDS
    When used will sort people by the container's definition of top friends.

Back to top

Class opensocial.DataResponse

 SUMMARY     DETAIL

This object contains the requested server data mapped to the requested keys.

See also: DataRequest

Method Summary

 opensocial.ResponseItem get(key)
Gets the ResponseItem for the requested field.
 String getErrorMessage()
If the entire request had a batch level error, returns the error message.
 Boolean hadError()
Returns true if there was an error in fetching this data from the server.
 

Method Detail

get

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

getErrorMessage

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

hadError

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

Back to top

Class opensocial.Email

 SUMMARY     DETAIL

Base interface for all email objects.

Method Summary

 String getField(key, opt_params)
Gets data for this body type that is associated with the specified key.
 

Method Detail

getField

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

Back to top

Static Class opensocial.Email.Field

 SUMMARY     DETAIL

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

Field Summary

<static> object ADDRESS
The email address, specified as a string.
<static> object TYPE
The email type or label, specified as a string.
 

Field Detail

ADDRESS

<static> object ADDRESS
    The email address, specified as a string.

TYPE

<static> object TYPE
    The email type or label, specified as a string. Examples: work, my favorite store, my house, etc.

Back to top

Class opensocial.Enum

 SUMMARY     DETAIL

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.

Method Summary

 String getDisplayValue()
The value of this enum.
 String getKey()
Use this for logic within your gadget.
 

Method Detail

getDisplayValue

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

getKey

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

Back to top

Static Class opensocial.Enum.Drinker

 SUMMARY     DETAIL

The enum keys used by the drinker field.

See also: opensocial.Person.Field.Drinker

Field Summary

<static> object HEAVILY
<static> object NO
<static> object OCCASIONALLY
<static> object QUIT
<static> object QUITTING
<static> object REGULARLY
<static> object SOCIALLY
<static> object YES
 

Field Detail

HEAVILY

<static> object HEAVILY

NO

<static> object NO

OCCASIONALLY

<static> object OCCASIONALLY

QUIT

<static> object QUIT

QUITTING

<static> object QUITTING

REGULARLY

<static> object REGULARLY

SOCIALLY

<static> object SOCIALLY

YES

<static> object YES

Back to top

Static Class opensocial.Enum.Gender

 SUMMARY     DETAIL

The enum keys used by the gender field.

See also: opensocial.Person.Field.Gender

Field Summary

<static> object FEMALE
<static> object MALE
 

Field Detail

FEMALE

<static> object FEMALE

MALE

<static> object MALE

Back to top

Static Class opensocial.Enum.LookingFor

 SUMMARY     DETAIL

The enum keys used by the lookingFor field.

See also: opensocial.Person.Field.LookingFor

Field Summary

<static> object ACTIVITY_PARTNERS
<static> object DATING
<static> object FRIENDS
<static> object NETWORKING
<static> object RANDOM
<static> object RELATIONSHIP
 

Field Detail

ACTIVITY_PARTNERS

<static> object ACTIVITY_PARTNERS

DATING

<static> object DATING

FRIENDS

<static> object FRIENDS

NETWORKING

<static> object NETWORKING

RANDOM

<static> object RANDOM

RELATIONSHIP

<static> object RELATIONSHIP

Back to top

Static Class opensocial.Enum.Presence

 SUMMARY     DETAIL

The enum keys used by the networkPresence field.

See also: opensocial.Person.Field.NetworkPresence

Field Summary

<static> object AWAY
The entity or resource is temporarily away.
<static> object CHAT
The entity or resource is actively interested in chatting.
<static> object DND
The entity or resource is busy (dnd = "Do Not Disturb").
<static> object OFFLINE
The entity or resource is off line.
<static> object ONLINE
The entity or resource is on line.
<static> object XA
The entity or resource is away for an extended period (xa = "eXtended Away").
 

Field Detail

AWAY

<static> object AWAY
    The entity or resource is temporarily away.

CHAT

<static> object CHAT
    The entity or resource is actively interested in chatting.

DND

<static> object DND
    The entity or resource is busy (dnd = "Do Not Disturb").

OFFLINE

<static> object OFFLINE
    The entity or resource is off line.

ONLINE

<static> object ONLINE
    The entity or resource is on line.

XA

<static> object XA
    The entity or resource is away for an extended period (xa = "eXtended Away").

Back to top

Static Class opensocial.Enum.Smoker

 SUMMARY     DETAIL

The enum keys used by the smoker field.

See also: opensocial.Person.Field.Smoker

Field Summary

<static> object HEAVILY
<static> object NO
<static> object OCCASIONALLY
<static> object QUIT
<static> object QUITTING
<static> object REGULARLY
<static> object SOCIALLY
<static> object YES
 

Field Detail

HEAVILY

<static> object HEAVILY

NO

<static> object NO

OCCASIONALLY

<static> object OCCASIONALLY

QUIT

<static> object QUIT

QUITTING

<static> object QUITTING

REGULARLY

<static> object REGULARLY

SOCIALLY

<static> object SOCIALLY

YES

<static> object YES

Back to top

Class opensocial.Environment

 SUMMARY     DETAIL

Represents the current environment for a gadget.

See also: opensocial.getEnvironment(),

Method Summary

 String getDomain()
Returns the current domain — for example, "orkut.com" or "myspace.com".
 Boolean supportsField(objectType, fieldName)
Returns true if the specified field is supported in this container on the given object type.
 

Method Detail

getDomain

String getDomain()
    Returns the current domain — for example, "orkut.com" or "myspace.com".
    Returns:
      String  The domain

supportsField

Boolean supportsField(objectType, fieldName)
    Returns true if the specified field is supported in this container on the given object type.
    Parameters:
      opensocial.Environment.ObjectType objectType - The object type to check for the field
      String fieldName - The name of the field to check for
    Returns:
      Boolean  True if the field is supported on the specified object type

Back to top

Static Class opensocial.Environment.ObjectType

 SUMMARY     DETAIL

The types of objects in this container.

See also: Environment.supportsField()

Field Summary

<static> object ACTIVITY
<static> object ADDRESS
<static> object BODY_TYPE
<static> object EMAIL
<static> object FILTER_TYPE
<static> object MEDIA_ITEM
<static> object MESSAGE
<static> object MESSAGE_TYPE
<static> object NAME
<static> object ORGANIZATION
<static> object PERSON
<static> object PHONE
<static> object SORT_ORDER
<static> object URL
 

Field Detail

ACTIVITY

<static> object ACTIVITY

ADDRESS

<static> object ADDRESS

BODY_TYPE

<static> object BODY_TYPE

EMAIL

<static> object EMAIL

FILTER_TYPE

<static> object FILTER_TYPE

MEDIA_ITEM

<static> object MEDIA_ITEM

MESSAGE

<static> object MESSAGE

MESSAGE_TYPE

<static> object MESSAGE_TYPE

NAME

<static> object NAME

ORGANIZATION

<static> object ORGANIZATION

PERSON

<static> object PERSON

PHONE

<static> object PHONE

SORT_ORDER

<static> object SORT_ORDER

URL

<static> object URL

Back to top

Static Class opensocial.EscapeType

 SUMMARY     DETAIL

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

Field Summary

<static> object HTML_ESCAPE
When used will HTML-escape the data.
<static> object NONE
When used will not escape the data.
 

Field Detail

HTML_ESCAPE

<static> object HTML_ESCAPE
    When used will HTML-escape the data.

NONE

<static> object NONE
    When used will not escape the data.

Back to top

Class opensocial.IdSpec

 SUMMARY     DETAIL

Base interface for all id spec objects.

Method Summary

 String getField(key, opt_params)
Gets the id spec's data that's associated with the specified key.
setField(key, data)
Sets data for this id spec associated with the given key.
 

Method Detail

getField

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

setField

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

Back to top

Static Class opensocial.IdSpec.Field

 SUMMARY     DETAIL

All of the fields that id specs can have.

See also: opensocial.IdSpec.getField()

Field Summary

<static> object GROUP_ID
A string representing the group id.
<static> object NETWORK_DISTANCE
An optional numeric parameter, used to specify how many "hops" are allowed between two people still considered part of the same group.
<static> object USER_ID
A string or an array of strings representing the user id.
 

Field Detail

GROUP_ID

<static> object GROUP_ID
    A string representing the group id.

NETWORK_DISTANCE

<static> object NETWORK_DISTANCE
    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.

USER_ID

<static> object USER_ID
    A string or an array of strings representing the user id.

Back to top

Static Class opensocial.IdSpec.PersonId

 SUMMARY     DETAIL

Constant person IDs available when fetching person information.

Field Summary

<static> object OWNER
<static> object VIEWER
 

Field Detail

OWNER

<static> object OWNER

VIEWER

<static> object VIEWER

Back to top

Class opensocial.MediaItem

 SUMMARY     DETAIL

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

Method Summary

 String getField(key, opt_params)
Gets the media item data that's associated with the specified key.
setField(key, data)
Sets data for this media item associated with the given key.
 

Method Detail

getField

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

setField

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

Back to top

Static Class opensocial.MediaItem.Field

 SUMMARY     DETAIL

All of the fields that media items have.

See also: opensocial.MediaItem.getField()

Field Summary

<static> object MIME_TYPE
The MIME type of media, specified as a string.
<static> object TYPE
The type of media, specified as a MediaItem.Type object.
<static> object URL
A string specifying the URL where the media can be found.
 

Field Detail

MIME_TYPE

<static> object MIME_TYPE
    The MIME type of media, specified as a string.

TYPE

<static> object TYPE

URL

<static> object URL
    A string specifying the URL where the media can be found.

Back to top

Static Class opensocial.MediaItem.Type

 SUMMARY     DETAIL

The possible types of media items.

See also: opensocial.MediaItem.Field

Field Summary

<static> object AUDIO
<static> object IMAGE
<static> object VIDEO
 

Field Detail

AUDIO

<static> object AUDIO

IMAGE

<static> object IMAGE

VIDEO

<static> object VIDEO

Back to top

Class opensocial.Message

 SUMMARY     DETAIL

Base interface for all message objects. *

See also: opensocial.newMessage(), opensocial.requestSendMessage()

Method Summary

 String getField(key, opt_params)
Gets the message data that's associated with the specified key.
setField(key, data)
Sets data for this message associated with the given key.
 

Method Detail

getField

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

setField

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

Back to top

Static Class opensocial.Message.Field

 SUMMARY     DETAIL

All of the fields that messages can have.

See also: opensocial.Message.getField()

Field Summary

<static> object BODY
The main text of the message.
<static> object BODY_ID
The main text of the message as a message template.
<static> object TITLE
The title of the message.
<static> object TITLE_ID
The title of the message as a message template.
<static> object TYPE
The title of the message, specified as an opensocial.Message.Type.
 

Field Detail

BODY

<static> object BODY
    The main text of the message. HTML attributes are allowed and are sanitized by the container.

BODY_ID

<static> object BODY_ID
    The main text of the message as a message template. Specifies the message ID to use in the gadget xml.

TITLE

<static> object TITLE
    The title of the message. HTML attributes are allowed and are sanitized by the container.

TITLE_ID

<static> object TITLE_ID
    The title of the message as a message template. Specifies the message ID to use in the gadget xml.

TYPE

<static> object TYPE
    The title of the message, specified as an opensocial.Message.Type.

Back to top

Static Class opensocial.Message.Type

 SUMMARY     DETAIL

The types of messages that can be sent.

Field Summary

<static> object EMAIL
An email.
<static> object NOTIFICATION
A short private message.
<static> object PRIVATE_MESSAGE
A message to a specific user that can be seen only by that user.
<static> object PUBLIC_MESSAGE
A message to a specific user that can be seen by more than that user.
 

Field Detail

EMAIL

<static> object EMAIL
    An email.

NOTIFICATION

<static> object NOTIFICATION
    A short private message.

PRIVATE_MESSAGE

<static> object PRIVATE_MESSAGE
    A message to a specific user that can be seen only by that user.

PUBLIC_MESSAGE

<static> object PUBLIC_MESSAGE
    A message to a specific user that can be seen by more than that user.

Back to top

Class opensocial.Name

 SUMMARY     DETAIL

Base interface for all name objects.

Method Summary

 String getField(key, opt_params)
Gets data for this name that is associated with the specified key.
 

Method Detail

getField

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

Back to top

Static Class opensocial.Name.Field

 SUMMARY     DETAIL

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

Field Summary

<static> object ADDITIONAL_NAME
The additional name, specified as a string.
<static> object FAMILY_NAME
The family name, specified as a string.
<static> object GIVEN_NAME
The given name, specified as a string.
<static> object HONORIFIC_PREFIX
The honorific prefix, specified as a string.
<static> object HONORIFIC_SUFFIX
The honorific suffix, specified as a string.
<static> object UNSTRUCTURED
The unstructured name, specified as a string.
 

Field Detail

ADDITIONAL_NAME

<static> object ADDITIONAL_NAME
    The additional name, specified as a string.

FAMILY_NAME

<static> object FAMILY_NAME
    The family name, specified as a string.

GIVEN_NAME

<static> object GIVEN_NAME
    The given name, specified as a string.

HONORIFIC_PREFIX

<static> object HONORIFIC_PREFIX
    The honorific prefix, specified as a string.

HONORIFIC_SUFFIX

<static> object HONORIFIC_SUFFIX
    The honorific suffix, specified as a string.

UNSTRUCTURED

<static> object UNSTRUCTURED
    The unstructured name, specified as a string.

Back to top

Class opensocial.NavigationParameters

 SUMMARY     DETAIL

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: 1) 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. 2) 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.

Method Summary

 String getField(key, opt_params)
Gets the NavigationParameters' data that's associated with the specified key.
setField(key, data)
Sets data for this NavigationParameters associated with the given key.
 

Method Detail

getField

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

setField

setField(key, data)
    Sets data for this NavigationParameters associated with the given key.
    Parameters:
      String key - The key to set data for
      Object data - The data to set

Back to top

Static Class opensocial.NavigationParameters.DestinationType

 SUMMARY     DETAIL

The destinations available for navigation in requestShareApp and requestSendMessage.

Field Summary

<static> object RECIPIENT_DESTINATION
<static> object VIEWER_DESTINATION
 

Field Detail

RECIPIENT_DESTINATION

<static> object RECIPIENT_DESTINATION

VIEWER_DESTINATION

<static> object VIEWER_DESTINATION

Back to top

Static Class opensocial.NavigationParameters.Field

 SUMMARY     DETAIL

All of the fields that NavigationParameters can have.

See also: opensocial.NavigationParameters.getField()

Field Summary

<static> object OWNER
A string representing the owner id.
<static> object PARAMETERS
An optional list of parameters passed to the gadget once the new view, with the new owner, has been loaded.
<static> object VIEW
The View to navigate to.
 

Field Detail

OWNER

<static> object OWNER
    A string representing the owner id.

PARAMETERS

<static> object PARAMETERS
    An optional list of parameters passed to the gadget once the new view, with the new owner, has been loaded.

VIEW

<static> object VIEW
    The View to navigate to.

Back to top

Class opensocial.Organization

 SUMMARY     DETAIL

Base interface for all organization objects.

Method Summary

 String getField(key, opt_params)
Gets data for this body type that is associated with the specified key.
 

Method Detail

getField

String getField(key, opt_params)
    Gets data for this body type that is associated with the specified key.
    Parameters:
      Map.<opensocial.DataRequest.DataRequestFields, Object> opt_params - Additional params to pass to the request
    Returns:
      String  The data

Back to top

Static Class opensocial.Organization.Field

 SUMMARY     DETAIL

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

Field Summary

<static> object ADDRESS
The address of the organization, specified as an opensocial.Address.
<static> object DESCRIPTION
A description or notes about the person's work in the organization, specified as a string.
<static> object END_DATE
The date the person stopped at the organization, specified as a Date.
<static> object FIELD
The field the organization is in, specified as a string.
<static> object NAME
The name of the organization, specified as a string.
<static> object SALARY
The salary the person receieves from the organization, specified as a string.
<static> object START_DATE
The date the person started at the organization, specified as a Date.
<static> object SUB_FIELD
The subfield the Organization is in, specified as a string.
<static> object TITLE
The title or role the person has in the organization, specified as a string.
<static> object WEBPAGE
A webpage related to the organization, specified as a string.
 

Field Detail

ADDRESS

<static> object ADDRESS
    The address of the organization, specified as an opensocial.Address. Container support for this field is OPTIONAL.

DESCRIPTION

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

END_DATE

<static> object END_DATE
    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.

FIELD

<static> object FIELD
    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.

NAME

<static> object NAME
    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.

SALARY

<static> object SALARY
    The salary the person receieves from the organization, specified as a string. Container support for this field is OPTIONAL.

START_DATE

<static> object START_DATE
    The date the person started at the organization, specified as a Date. Container support for this field is OPTIONAL.

SUB_FIELD

<static> object SUB_FIELD
    The subfield the Organization is in, specified as a string. Container support for this field is OPTIONAL.

TITLE

<static> object TITLE
    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.

WEBPAGE

<static> object WEBPAGE
    A webpage related to the organization, specified as a string. Container support for this field is OPTIONAL.

Back to top

Static Class opensocial.Permission

 SUMMARY     DETAIL

The permissions an app can ask for.

See also: opensocial.hasPermission(), opensocial.requestPermission()

Field Summary

<static> object VIEWER
Access to the viewer person object
 

Field Detail

VIEWER

<static> object VIEWER
    Access to the viewer person object

Back to top

Class opensocial.Person

 SUMMARY     DETAIL

Base interface for all person objects.

Method Summary

 String getDisplayName()
Gets a text display name for this person; guaranteed to return a useful string.
 String getField(key, opt_params)
Gets data for this person that is associated with the specified key.
 String getId()
Gets an ID that can be permanently associated with this person.
 Boolean isOwner()
Returns true if this person object represents the owner of the current page.
 Boolean isViewer()
Returns true if this person object represents the currently logged in user.
 

Method Detail

getDisplayName

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

getField

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

getId

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

isOwner

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

isViewer

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

Back to top

Static Class opensocial.Person.Field

 SUMMARY     DETAIL

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

Field Summary

<static> object ABOUT_ME
A general statement about the person, specified as a string.
<static> object ACTIVITIES
Person's favorite activities, specified as an Array of strings.
<static> object ADDRESSES
Addresses associated with the person, specified as an Array of Addresses.
<static> object AGE
Person's age, specified as a number.
<static> object BODY_TYPE
Person's body characteristics, specified as an opensocial.BodyType.
<static> object BOOKS
Person's favorite books, specified as an Array of strings.
<static> object CARS
Person's favorite cars, specified as an Array of strings.
<static> object CHILDREN
Description of the person's children, specified as a string.
<static> object CURRENT_LOCATION
Person's current location, specified as an Address.
<static> object DATE_OF_BIRTH
Person's date of birth, specified as a Date object.
<static> object DRINKER
Person's drinking status, specified as an opensocial.Enum with the enum's key referencing opensocial.Enum.Drinker.
<static> object EMAILS
Emails associated with the person, specified as an Array of Emails.
<static> object ETHNICITY
Person's ethnicity, specified as a string.
<static> object FASHION
Person's thoughts on fashion, specified as a string.
<static> object FOOD
Person's favorite food, specified as an Array of strings.
<static> object GENDER
Person's gender, specified as an opensocial.Enum with the enum's key referencing opensocial.Enum.Gender.
<static> object HAPPIEST_WHEN
Describes when the person is happiest, specified as a string.
<static> object HAS_APP
A boolean indicating whether the person has used the current app.
<static> object HEROES
Person's favorite heroes, specified as an Array of strings.
<static> object HUMOR
Person's thoughts on humor, specified as a string.
<static> object ID
A string ID that can be permanently associated with this person.
<static> object INTERESTS
Person's interests, hobbies or passions, specified as an Array of strings.
<static> object JOB_INTERESTS
Person's favorite jobs, or job interests and skills, specified as a string.
<static> object JOBS
Jobs the person has held, specified as an Array of Organizations.
<static> object LANGUAGES_SPOKEN
List of the languages that the person speaks as ISO 639-1 codes, specified as an Array of strings.
<static> object LIVING_ARRANGEMENT
Description of the person's living arrangement, specified as a string.
<static> object LOOKING_FOR
Person's statement about who or what they are looking for, or what they are interested in meeting people for.
<static> object MOVIES
Person's favorite movies, specified as an Array of strings.
<static> object MUSIC
Person's favorite music, specified as an Array of strings.
<static> object NAME
A opensocial.Name object containing the person's name.
<static> object NETWORK_PRESENCE
Person's current network status.
<static> object NICKNAME
A String representing the person's nickname.
<static> object PETS
Description of the person's pets, specified as a string.
<static> object PHONE_NUMBERS
Phone numbers associated with the person, specified as an Array of Phones.
<static> object POLITICAL_VIEWS
Person's political views, specified as a string.
<static> object PROFILE_SONG
Person's profile song, specified as an opensocial.Url.
<static> object PROFILE_URL
Person's profile URL, specified as a string.
<static> object PROFILE_VIDEO
Person's profile video, specified as an opensocial.Url.
<static> object QUOTES
Person's favorite quotes, specified as an Array of strings.
<static> object RELATIONSHIP_STATUS
Person's relationship status, specified as a string.
<static> object RELIGION
Person's relgion or religious views, specified as a string.
<static> object ROMANCE
Person's comments about romance, specified as a string.
<static> object SCARED_OF
What the person is scared of, specified as a string.
<static> object SCHOOLS
Schools the person has attended, specified as an Array of Organizations.
<static> object SEXUAL_ORIENTATION
Person's sexual orientation, specified as a string.
<static> object SMOKER
Person's smoking status, specified as an opensocial.Enum with the enum's key referencing opensocial.Enum.Smoker.
<static> object SPORTS
Person's favorite sports, specified as an Array of strings.
<static> object STATUS
Person's status, headline or shoutout, specified as a string.
<static> object TAGS
Arbitrary tags about the person, specified as an Array of strings.
<static> object THUMBNAIL_URL
Person's photo thumbnail URL, specified as a string.
<static> object TIME_ZONE
Person's time zone, specified as the difference in minutes between Greenwich Mean Time (GMT) and the user's local time.
<static> object TURN_OFFS
Person's turn offs, specified as an Array of strings.
<static> object TURN_ONS
Person's turn ons, specified as an Array of strings.
<static> object TV_SHOWS
Person's favorite TV shows, specified as an Array of strings.
<static> object URLS
URLs related to the person, their webpages, or feeds.
 

Field Detail

ABOUT_ME

<static> object ABOUT_ME
    A general statement about the person, specified as a string. Container support for this field is OPTIONAL.

ACTIVITIES

<static> object ACTIVITIES
    Person's favorite activities, specified as an Array of strings. Container support for this field is OPTIONAL.

ADDRESSES

<static> object ADDRESSES
    Addresses associated with the person, specified as an Array of Addresses. Container support for this field is OPTIONAL.

AGE

<static> object AGE
    Person's age, specified as a number. Container support for this field is OPTIONAL.

BODY_TYPE

<static> object BODY_TYPE
    Person's body characteristics, specified as an opensocial.BodyType. Container support for this field is OPTIONAL.

BOOKS

<static> object BOOKS
    Person's favorite books, specified as an Array of strings. Container support for this field is OPTIONAL.

CARS

<static> object CARS
    Person's favorite cars, specified as an Array of strings. Container support for this field is OPTIONAL.

CHILDREN

<static> object CHILDREN
    Description of the person's children, specified as a string. Container support for this field is OPTIONAL.

CURRENT_LOCATION

<static> object CURRENT_LOCATION
    Person's current location, specified as an Address. Container support for this field is OPTIONAL.

DATE_OF_BIRTH

<static> object DATE_OF_BIRTH
    Person's date of birth, specified as a Date object. Container support for this field is OPTIONAL.

DRINKER

<static> object DRINKER
    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.

EMAILS

<static> object EMAILS
    Emails associated with the person, specified as an Array of Emails. Container support for this field is OPTIONAL.

ETHNICITY

<static> object ETHNICITY
    Person's ethnicity, specified as a string. Container support for this field is OPTIONAL.

FASHION

<static> object FASHION
    Person's thoughts on fashion, specified as a string. Container support for this field is OPTIONAL.

FOOD

<static> object FOOD
    Person's favorite food, specified as an Array of strings. Container support for this field is OPTIONAL.

GENDER

<static> object GENDER
    Person's gender, specified as an opensocial.Enum with the enum's key referencing opensocial.Enum.Gender. Container support for this field is OPTIONAL.

HAPPIEST_WHEN

<static> object HAPPIEST_WHEN
    Describes when the person is happiest, specified as a string. Container support for this field is OPTIONAL.

HAS_APP

<static> object HAS_APP
    A boolean indicating whether the person has used the current app. Container support for this field is OPTIONAL.

HEROES

<static> object HEROES
    Person's favorite heroes, specified as an Array of strings. Container support for this field is OPTIONAL.

HUMOR

<static> object HUMOR
    Person's thoughts on humor, specified as a string. Container support for this field is OPTIONAL.

ID

<static> object ID
    A string ID that can be permanently associated with this person.

INTERESTS

<static> object INTERESTS
    Person's interests, hobbies or passions, specified as an Array of strings. Container support for this field is OPTIONAL.

JOB_INTERESTS

<static> object JOB_INTERESTS
    Person's favorite jobs, or job interests and skills, specified as a string. Container support for this field is OPTIONAL.

JOBS

<static> object JOBS
    Jobs the person has held, specified as an Array of Organizations. Container support for this field is OPTIONAL.

LANGUAGES_SPOKEN

<static> object LANGUAGES_SPOKEN
    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.

LIVING_ARRANGEMENT

<static> object LIVING_ARRANGEMENT
    Description of the person's living arrangement, specified as a string. Container support for this field is OPTIONAL.

LOOKING_FOR

<static> object LOOKING_FOR
    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.

MOVIES

<static> object MOVIES
    Person's favorite movies, specified as an Array of strings. Container support for this field is OPTIONAL.

MUSIC

<static> object MUSIC
    Person's favorite music, specified as an Array of strings. Container support for this field is OPTIONAL.

NAME

<static> object NAME
    A opensocial.Name object containing the person's name.

NETWORK_PRESENCE

<static> object NETWORK_PRESENCE
    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.

NICKNAME

<static> object NICKNAME
    A String representing the person's nickname.

PETS

<static> object PETS
    Description of the person's pets, specified as a string. Container support for this field is OPTIONAL.

PHONE_NUMBERS

<static> object PHONE_NUMBERS
    Phone numbers associated with the person, specified as an Array of Phones. Container support for this field is OPTIONAL.

POLITICAL_VIEWS

<static> object POLITICAL_VIEWS
    Person's political views, specified as a string. Container support for this field is OPTIONAL.

PROFILE_SONG

<static> object PROFILE_SONG
    Person's profile song, specified as an opensocial.Url. Container support for this field is OPTIONAL.

PROFILE_URL

<static> object PROFILE_URL
    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.

PROFILE_VIDEO

<static> object PROFILE_VIDEO
    Person's profile video, specified as an opensocial.Url. Container support for this field is OPTIONAL.

QUOTES

<static> object QUOTES
    Person's favorite quotes, specified as an Array of strings. Container support for this field is OPTIONAL.

RELATIONSHIP_STATUS

<static> object RELATIONSHIP_STATUS
    Person's relationship status, specified as a string. Container support for this field is OPTIONAL.

RELIGION

<static> object RELIGION
    Person's relgion or religious views, specified as a string. Container support for this field is OPTIONAL.

ROMANCE

<static> object ROMANCE
    Person's comments about romance, specified as a string. Container support for this field is OPTIONAL.

SCARED_OF

<static> object SCARED_OF
    What the person is scared of, specified as a string. Container support for this field is OPTIONAL.

SCHOOLS

<static> object SCHOOLS
    Schools the person has attended, specified as an Array of Organizations. Container support for this field is OPTIONAL.

SEXUAL_ORIENTATION

<static> object SEXUAL_ORIENTATION
    Person's sexual orientation, specified as a string. Container support for this field is OPTIONAL.

SMOKER

<static> object SMOKER
    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.

SPORTS

<static> object SPORTS
    Person's favorite sports, specified as an Array of strings. Container support for this field is OPTIONAL.

STATUS

<static> object STATUS
    Person's status, headline or shoutout, specified as a string. Container support for this field is OPTIONAL.

TAGS

<static> object TAGS
    Arbitrary tags about the person, specified as an Array of strings. Container support for this field is OPTIONAL.

THUMBNAIL_URL

<static> object THUMBNAIL_URL
    Person's photo thumbnail URL, specified as a string. This URL must be fully qualified. Relative URLs will not work in gadgets.

TIME_ZONE

<static> object TIME_ZONE
    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.

TURN_OFFS

<static> object TURN_OFFS
    Person's turn offs, specified as an Array of strings. Container support for this field is OPTIONAL.

TURN_ONS

<static> object TURN_ONS
    Person's turn ons, specified as an Array of strings. Container support for this field is OPTIONAL.

TV_SHOWS

<static> object TV_SHOWS
    Person's favorite TV shows, specified as an Array of strings. Container support for this field is OPTIONAL.

URLS

<static> object URLS
    URLs related to the person, their webpages, or feeds. Specified as an Array of opensocial.Url. Container support for this field is OPTIONAL.

Back to top

Class opensocial.Phone

 SUMMARY     DETAIL

Base interface for all phone objects.

Method Summary

 String getField(key, opt_params)
Gets data for this phone that is associated with the specified key.
 

Method Detail

getField

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

Back to top

Static Class opensocial.Phone.Field

 SUMMARY     DETAIL

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

Field Summary

<static> object NUMBER
The phone number, specified as a string.
<static> object TYPE
The phone number type or label, specified as a string.
 

Field Detail

NUMBER

<static> object NUMBER
    The phone number, specified as a string.

TYPE

<static> object TYPE
    The phone number type or label, specified as a string. Examples: work, my favorite store, my house, etc.

Back to top

Class opensocial.ResponseItem

 SUMMARY     DETAIL

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

Method Summary

 Object getData()
Gets the response data.
 String getErrorCode()
If the request had an error, returns the error code.
 String getErrorMessage()
If the request had an error, returns the error message.
 opensocial.DataRequest getOriginalDataRequest()
Returns the original data request.
 Boolean hadError()
Returns true if there was an error in fetching this data from the server.
 

Method Detail

getData

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

getErrorCode

String getErrorCode()
    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:
      String  The error code, or null if no error occurred

getErrorMessage

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

getOriginalDataRequest

opensocial.DataRequest getOriginalDataRequest()
    Returns the original data request.
    Returns:
      opensocial.DataRequest  The data request used to fetch this data response

hadError

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

Back to top

Static Class opensocial.ResponseItem.Error

 SUMMARY     DETAIL

Error codes that a response item can return.

Field Summary

<static> object BAD_REQUEST
The request was invalid.
<static> object FORBIDDEN
The gadget can never have access to the requested data.
<static> object INTERNAL_ERROR
The request encountered an unexpected condition that prevented it from fulfilling the request.
<static> object LIMIT_EXCEEDED
The gadget exceeded a quota on the request.
<static> object NOT_IMPLEMENTED
This container does not support the request that was made.
<static> object UNAUTHORIZED
The gadget does not have access to the requested data.
 

Field Detail

BAD_REQUEST

<static> object BAD_REQUEST
    The request was invalid. Example: 'max' was -1.

FORBIDDEN

<static> object FORBIDDEN
    The gadget can never have access to the requested data.

INTERNAL_ERROR

<static> object INTERNAL_ERROR
    The request encountered an unexpected condition that prevented it from fulfilling the request.

LIMIT_EXCEEDED

<static> object LIMIT_EXCEEDED
    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.

NOT_IMPLEMENTED

<static> object NOT_IMPLEMENTED
    This container does not support the request that was made.

UNAUTHORIZED

<static> object UNAUTHORIZED

Back to top

Class opensocial.Url

 SUMMARY     DETAIL

Base interface for all URL objects.

Method Summary

 String getField(key, opt_params)
Gets data for this URL that is associated with the specified key.
 

Method Detail

getField

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

Back to top

Static Class opensocial.Url.Field

 SUMMARY     DETAIL

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

Field Summary

<static> object ADDRESS
The address the URL points to, specified as a string.
<static> object LINK_TEXT
The text of the link, specified as a string.
<static> object TYPE
The URL number type or label, specified as a string.
 

Field Detail

ADDRESS

<static> object ADDRESS
    The address the URL points to, specified as a string.

LINK_TEXT

<static> object LINK_TEXT
    The text of the link, specified as a string.

TYPE

<static> object TYPE
    The URL number type or label, specified as a string. Examples: work, blog feed, website, etc.

Back to top