OpenSocial API Reference V 8.0

OpenSocial API Reference (v0.8) 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   Type Conventions opensocial o Activity  Field o Address  Field o BodyType  Field o Collection o CreateActivityPriority o DataRequest  DataRequestFields  FilterType  PeopleRequestFields  SortOrder o DataResponse o Email  Field o Enum  Drinker  Gender  LookingFor  Presence  Smoker o Environment  ObjectType o EscapeType o IdSpec  Field  PersonId o MediaItem  Field  Type o Message  Field  Type o Name  Field o NavigationParameters  DestinationType  Field o Organization  Field o o Permission Person  Field o Phone  Field o ResponseItem  Error o Url  Field Back to top Type Conventions This document uses the following conventions for types: Array or Array. An Array filled with only objects of type T. This convention is similar to Java generics. Map or Map. 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 opensocial.Environment getEnvironment() Boolean hasPermission(permission) opensocial.Activity newActivity(params) opensocial.DataRequest newDataRequest() opensocial.IdSpec newIdSpec(parameters) Gets the current environment for this gadget. Returns true if the current gadget has access to the specified permission. Creates an activity object, which represents an activity on the server. Creates a data request object to use for sending and fetching data from the server. Creates an IdSpec object.  opensocial.MediaItem newMediaItem(mimeType, url, opt_params) opensocial.Message newMessage(body, opt_params) opensocial.NavigationParameters newNavigationParameters(parameters) Creates a media item. Creates a media item associated with an activity. Creates a NavigationParameters object. requestCreateActivity(activity, priority, opt_callback) Takes an activity and tries to create it, without waiting for the operation to complete. requestPermission(permissions, reason, opt_callback) Requests the user to grant access to the specified permissions. requestSendMessage(recipients, message, opt_callback, opt_params) Requests the container to send a specific message to the specified users. requestShareApp(recipients, reason, opt_callback, opt_params) Requests the container to share this gadget with the specified users. Method Detail getEnvironment 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: opensocial.Environment The current environment hasPermission 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 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. params - Parameters defining the activity Returns: opensocial.Activity The new activity object newDataRequest 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 opensocial.IdSpec newIdSpec(parameters) Creates an IdSpec object. Parameters: Map. parameters - Parameters defining the id spec Returns: opensocial.IdSpec The new IdSpec object newMediaItem 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 mimeType - MIME type of the media String url - Where the media can be found Map. 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 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. 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 opensocial.NavigationParameters newNavigationParameters(parameters) Creates a NavigationParameters object. See also: requestShareApp() Parameters: Map. parameters - Parameters defining the navigation Returns: opensocial.NavigationParameters The new NavigationParameters object requestCreateActivity 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 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. 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 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 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 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 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: ${Subject.Count} of your friends have suggested listening to songs by ${Artist}! ${Subject.Count} of your friends have suggested listening to ${Song} ! ${Subject.DisplayName} has recommended ${Song.Count} songs to you. 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. 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 object APP_ID A string specifying the application that this activity is associated with. object BODY A string specifying an optional expanded version of an activity. object BODY_ID A string specifying the body template message ID in the gadget spec. object EXTERNAL_ID An optional string ID generated by the posting application. object ID A string ID that is permanently associated with this activity. object MEDIA_ITEMS Any photos, videos, or images that should be associated with the activity. object POSTED_TIME A string specifying the time at which this activity took place in milliseconds since the epoch. object PRIORITY A number between 0 and 1 representing the relative priority of this activity in relation to other activities from the same source object STREAM_FAVICON_URL A string specifying the URL for the stream's favicon. object STREAM_SOURCE_URL A string specifying the stream's source URL. object STREAM_TITLE A string specifing the title of the stream. object STREAM_URL A string specifying the stream's URL. object TEMPLATE_PARAMS A map of custom key/value pairs associated with this activity. object TITLE A string specifying the primary text of an activity. object TITLE_ID A string specifying the title template message ID in the gadget spec. object URL A string specifying the URL that represents this activity. object USER_ID The string ID of the user who this activity is for. Field Detail APP_ID object APP_ID A string specifying the application that this activity is associated with. This value can not be set. BODY object BODY A string specifying an optional expanded version of an activity. Bodies may only have the following HTML tags: , , . The container may ignore this formatting when rendering the activity. BODY_ID 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: , , . The container may ignore this formatting when rendering the activity. EXTERNAL_ID object EXTERNAL_ID An optional string ID generated by the posting application. ID object ID A string ID that is permanently associated with this activity. This value can not be set. MEDIA_ITEMS 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 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 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 object STREAM_FAVICON_URL A string specifying the URL for the stream's favicon. STREAM_SOURCE_URL object STREAM_SOURCE_URL A string specifying the stream's source URL. STREAM_TITLE object STREAM_TITLE A string specifing the title of the stream. STREAM_URL object STREAM_URL A string specifying the stream's URL. TEMPLATE_PARAMS 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. 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: o o o o 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 object TITLE A string specifying the primary text of an activity. Titles may only have the following HTML tags: , , . The container may ignore this formatting when rendering the activity. TITLE_ID 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: , , . The container may ignore this formatting when rendering the activity. URL object URL A string specifying the URL that represents this activity. USER_ID 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. 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 object COUNTRY The country, specified as a string. object EXTENDED_ADDRESS The extended street address, specified as a string. object LATITUDE The latitude, specified as a number. object LOCALITY The locality, specified as a string. object LONGITUDE The longitude, specified as a number. object PO_BOX The P.O. object POSTAL_CODE The postal code, specified as a string. object REGION The region, specified as a string. object STREET_ADDRESS The street address, specified as a string. object TYPE The address type or label, specified as a string. 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 object COUNTRY The country, specified as a string. EXTENDED_ADDRESS object EXTENDED_ADDRESS The extended street address, specified as a string. LATITUDE object LATITUDE The latitude, specified as a number. LOCALITY object LOCALITY The locality, specified as a string. LONGITUDE object LONGITUDE The longitude, specified as a number. PO_BOX object PO_BOX The P.O. box of the address, if there is one; specified as a string. POSTAL_CODE object POSTAL_CODE The postal code, specified as a string. REGION object REGION The region, specified as a string. STREET_ADDRESS object STREET_ADDRESS The street address, specified as a string. TYPE object TYPE The address type or label, specified as a string. Examples: work, my favorite store, my house, etc. UNSTRUCTURED_ADDRESS 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. 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 object BUILD The build of the person's body, specified as a string. object EYE_COLOR The eye color of the person, specified as a string. object HAIR_COLOR The hair color of the person, specified as a string. object HEIGHT The height of the person in meters, specified as a number. object WEIGHT The weight of the person in kilograms, specified as a number. Field Detail BUILD object BUILD The build of the person's body, specified as a string. Container support for this field is OPTIONAL. EYE_COLOR object EYE_COLOR The eye color of the person, specified as a string. Container support for this field is OPTIONAL. HAIR_COLOR object HAIR_COLOR The hair color of the person, specified as a string. Container support for this field is OPTIONAL. HEIGHT object HEIGHT The height of the person in meters, specified as a number. Container support for this field is OPTIONAL. WEIGHT 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.