My favorites | English | Sign in

Faster apps faster - GWT 2.0 with Speed Tracer New!

orkut Developer Home

OpenSocial Javascript API with orkut feature mapping

The OpenSocial Javascript API includes two namespaces: opensocial.* and gadgets.*. Not all of this data is available by default. This section explains what information of the opensocial.* namespace is available to aplications on orkut. The gadgets.* namespace is covered in the Gadgets API Reference.

OpenSocial Namespace reference

  1. opensocial
  2. opensocial.Activity
  3. opensocial.Address
  4. opensocial.Album
  5. opensocial.BodyType
  6. opensocial.Collection
  7. opensocial.CreateActivityPriority
  8. opensocial.DataRequest
  9. opensocial.DataResponse
  10. opensocial.Email
  11. opensocial.Enum
  12. opensocial.Environment
  13. opensocial.EscapeType
  14. opensocial.IdSpec
  15. opensocial.MediaItem
  16. opensocial.Message
  17. opensocial.MessageCollection
  18. opensocial.Name
  19. opensocial.NavigationParameters
  20. opensocial.Organization
  21. opensocial.Permission
  22. opensocial.Person
  23. opensocial.Phone
  24. opensocial.ResponseItem
  25. opensocial.Url

OpenSocial API support

Class: opensocial

Methods:

Methods orkut access policy Description
getEnvironment() supported Returns opensocial.Environment — current environment
hasPermission(permission) supported opensocial.Permission permission — the permission
Returns Boolean — true if gadget has access for the permission
invalidateCache() supported Invalidates all resources cached for the current viewer
newActivity(params) supported Map. params — parameters defining the activity
Returns opensocial.Activity — new activity object
newAlbum(opt_params) supported Map. opt_params — any other fields that should be set on the album object;
Returns opensocial.MediaItem — new album album object
newDataRequest() supported Returns opensocial.DataRequest — request object
newIdSpec(params) supported Map. params — parameters defining the id spec
Returns opensocial.IdSpec — new IdSpec object
newMediaItem() not supported
newMessage(body, opt_params) supported String body — main text of the message
Map. params — fields set on the message object
Returns opensocial.Message — new message object
newNavigationParameters() not supported
requestCreateActivity(activity, priority, opt_callback) supported opensocial.Activity activity — activity to create
opensocial.CreateActivityPriority priority — priority for this request
Function opt_callback — function to call once the request has been processed
requestPermission(permissions, reason, opt_callback) supported 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 — function to call once the request has been processed
requestSendMessage(An, message, opt_callback, opt_params) supported Array. | String recipients An — An ID, array of IDs, or a group reference
opensocial.Message message — message to send to the specified users
Function opt_callback — function to call once the request has been processed
opt_params — not supported
Note: implementation error for the param "An" as idSpec
requestShareApp() not supported
requestUploadMediaItem(albumId, opt_callback) supported String albumId — Indicates which album/collection to insert the items into
Funtion opt_callback — Method to be called when the upload completes

Class: opensocial.Activity

Methods:

Methods orkut access policy Description
getField(key, opt_params) supported String key — key to get data for; keys are defined in opensocial.Activity.Field
Map. opt_params — Additional params to pass to the request
Returns String — data
getId() not supported
setField(key, data) supported String key — key to set data for
String data — data to set
Returns None

Fields (opensocial.Activity.Field):

OpenSocial field orkut access policy
APP_ID not supported
BODY supported
BODY_ID not supported
EXTERNAL_ID not supported
ID not supported
MEDIA_ITEMS not supported
POSTED_TIME not supported
PRIORITY not supported
STREAM_FAVICON_URL not supported
STREAM_SOURCE_URL not supported
STREAM_TITLE not supported
STREAM_URL not supported
TEMPLATE_PARAMS not supported
TITLE supported
TITLE_ID not supported
URL not supported
USER_ID not supported

Examples: 

  /** Posting  Activity========================================== */
  function postActivity(title, body) {
    var activity = opensocial.newActivity();
    activity.setField(opensocial.Activity.Field.TITLE,title);
    activity.setField(opensocial.Activity.Field.BODY,body);
    opensocial.requestCreateActivity(activity, opensocial.CreateActivityPriority.HIGH, callback);
  };

  function callback(data) {
    if (data.hadError()) {
      alert("There was a problem: " + data.getErrorMessage());
    } else {
      output("Activity posted successfully.");
    }
  };

  postActivity('This is a test activity', 'This is an activity body');

Class: opensocial.Address

Methods:

Methods orkut access policy Description
getField(key, opt_params) supported String key — key to get data for; keys are defined in opensocial.Address.Field
Map. opt_params — Additional params to pass to the request
Returns String — data

Fields (opensocial.Address.Field):

OpenSocial field orkut field orkut access policy
COUNTRY country supported
EXTENDED_ADDRESS not supported
LATITUDE supported
LOCALITY city supported
LONGITUDE supported
PO_BOX not supported
POSTAL_CODE not supported
REGION state supported
STREET_ADDRESS not supported
TYPE supported
UNSTRUCTURED_ADDRESS not supported

Examples: 

  /** Retrieves owner location details ========================================== */
  function getLocationDetails() {
    var req = opensocial.newDataRequest();
    var params = {};
    params[opensocial.DataRequest.PeopleRequestFields.PROFILE_DETAILS] =
        [opensocial.Person.Field.CURRENT_LOCATION];
    req.add(req.newFetchPersonRequest(opensocial.IdSpec.PersonId.OWNER, params), "owner");
    req.send(callback);
  };

  function callback(data) {
    if (data.hadError()) {
      alert("There was a problem: " + data.getErrorMessage());
    } else {
      var owner = data.get("owner").getData();
      var ownerLocation = owner.getField(opensocial.Person.Field.CURRENT_LOCATION);
      output(ownerLocation.getField(opensocial.Address.Field.COUNTRY));
      output(ownerLocation.getField(opensocial.Address.Field.LATITUDE));
      output(ownerLocation.getField(opensocial.Address.Field.LOCALITY));
      output(ownerLocation.getField(opensocial.Address.Field.LONGITUDE));
      output(ownerLocation.getField(opensocial.Address.Field.REGION));
    }
  };
 
  getLocationDetails();

Class: opensocial.Album

Methods:

methods orkut access policy description
getField(key, opt_params) supported String key — key to get data for; keys are defined in opensocial.Album.Field
Map. opt_params — Additional params to pass to the request
Returns String — data
setField(key, data) supported String key — key to set data for
String data — data to set
Returns None

Fields (opensocial.Album.Field):

OpenSocial field orkut field orkut access policy
DESCRIPTION description supported
ID supported
LOCATION not supported
MEDIA_ITEM_COUNT supported
MEDIA_MIME_TYPE not supported
MEDIA_TYPE not supported
OWNER_ID supported
THUMBNAIL_URL supported
TITLE/CAPTION title supported

Examples: 

  /** Create Album ========================================== */
  function createAlbum(title) {
    var req = opensocial.newDataRequest();
    var params = {};
    params[opensocial.Album.Field.TITLE] = title;
    var album = new opensocial.Album(params);
    var idSpec = opensocial.newIdSpec({"userId" : "OWNER", "groupId" : "@self"}); 
    req.add(req.newCreateAlbumRequest(idSpec, album), "album");
    req.send(responseCreate);
  };

  function responseCreate(data) {
    output("Album reply.");
    if (data.hadError()) {
      output("Error: " + data.get("album").getErrorMessage());
    } else {
      var album = data.get("album").getData();
      output("Album " + album.id + " created.");
    }
  };

  createAlbum('open_soc_AAA');

Class: opensocial.BodyType — not supported

Class: opensocial.Collection

Methods:

Methods orkut access policy Description
asArray() supported Returns Array. — array of objects in the collection
each(fn) supported Function fn — function to call with each collection entry
Returns None
getById(id) supported String id — id to look for
Returns Object — The data
getOffset() supported Returns Number — Offset into the total collection
getTotalSize() supported Returns Number — The total size of the result
size() supported Returns Number — size of this collection

Class: opensocial.CreateActivityPriority

Fields (opensocial.CreateActivityPriority):

OpenSocial field orkut access policy
HIGH supported
LOW supported

Class: opensocial.DataRequest

Methods:

Methods orkut access policy Description
add(request, opt_key) supported Object request — Specifies which data to fetch or update
String opt_key — Key to map the generated response data to
Returns None
newCreateAlbumRequest(An, album) supported opensocial.IdSpec An — IdSpec used to specify which people or groups to create an album for
opensocial.Album album — The album to create
Returns Object — request object
newCreateMediaItemRequest(An, albumId, mediaItem) not supported
newDeleteAlbumRequest (An, albumId) supported opensocial.IdSpec An — IdSpec used to specify which people or groups which own the album
String albumId — album to delete
Returns Object — request object
newFetchActivitiesRequest not supported
newFetchAlbumsRequest(An, opt_params) supported opensocial.IdSpec An — IdSpec used to specify which people or groups to fetch album from
Map. opt_params — opensocial.Album.Field.ID | opensocial.Album.Field.MEDIA_TYPE | opensocial.DataRequest.AlbumRequestFields.FIRST | opensocial.DataRequest.AlbumRequestFields.MAX
Returns Object — request object
newFetchMediaItemsRequest(An, albumId, opt_params) supported opensocial.IdSpec An — IdSpec used to specify which people or groups to fetch media items from
String albumId — the id of the album to fetch media items from
Map. opt_params — opensocial.MediaItem.Field.ID | opensocial.MediaItem.Field.MEDIA_TYPE | opensocial.DataRequest.MediaItemRequestFields.FIRST | opensocial.DataRequest.MediaItemRequestFields.MAX
Returns Object — request object
newFetchPeopleRequest(idSpec, opt_params) supported opensocial.IdSpec idSpec — IdSpec used to specify which people to fetch
Map. — Additional params to pass to the request
Returns Object — request object
newFetchPersonAppDataRequest (idSpec, keys, opt_params) supported opensocial.IdSpec idSpec — IdSpec used to specify which people to fetch
Array. | String keys — The keys you want data for; can be array of key names, single key name or "*" to mean all keys
Map. opt_params — additional params to pass to the request
Returns Object — request object
newFetchPersonRequest(id, opt_params) supported String id — Id of the person to fetch; can be standard person id of VIEWER or OWNER
Map. opt_params — Additional params pass to the request; supports PROFILE_DETAILS
Returns Object — request object
newRemovePersonAppDataRequest (keys) supported Array. | String keys — Keys u want to delete from the datastore; can be array of key names, single key name or "*" to mean all keys
Returns None
newUpdateAlbumRequest (An, albumId, fields) supported opensocial.IdSpec An — IdSpec used to specify which people or groups to own the album
String albumId — The album to update
Map fields — The album fields to update; fields that cannot be set MEDIA_ITEM_COUNT, OWNER_ID, ID
Returns Object — request Object
newUpdateMediaItemRequest (An, albumId, mediaItemId, fields) supported opensocial.IdSpec An — IdSpec used to specify which people/groups own the album/media item
String albumId — album containing the media item to update
String mediaItemId — media item to update
Map fields — Album fields to update; fields that cannot be set ID, CREATED, ALBUM_ID, FILE_SIZE, NUM_COMMENTS
Returns Object — request Object
newUpdatePersonAppDataRequest (key, value) supported String key — name of the key
Object value — the value, must be valid JSON
Returns Object — request Object
send (opt_callback) supported Function opt_callback — function to call with the data response generated by the server

Fields (opensocial.DataRequest.ActivityRequestFields):

OpenSocial field orkut access policy
FIRST not supported
MAX not supported

Fields (opensocial.DataRequest.AlbumRequestFields):

OpenSocial field orkut access policy
FIRST supported
MAX supported

Fields (opensocial.DataRequest.DataRequestFields):

OpenSocial field orkut access policy
ESCAPE_TYPE supported

Fields (opensocial.DataRequest.FilterType):

OpenSocial field orkut access policy
ALL supported
HAS_APP supported
IS_FRIENDS_WITH supported
TOP_FRIENDS supported

Fields (opensocial.DataRequest.MediaItemRequestFields):

OpenSocial field orkut access policy
FIRST supported
MAX supported

Fields (opensocial.DataRequest.PeopleRequestFields):

OpenSocial field orkut access policy
APP_DATA supported
ESCAPE_TYPE supported
FILTER supported
FILTER_OPTIONS supported
MAX supported
FIRST supported
PROFILE_DETAILS supported
SORT_ORDER supported

Fields (opensocial.DataRequest.SortOrder):

OpenSocial field orkut access policy
NAME not supported
TOP_FRIENDS supported

Examples: 

  /** Fetch Friends ========================================== */
  function fetchFriends() {
    var req = opensocial.newDataRequest();
    var params = {}; 
    var idSpec = opensocial.newIdSpec({"userId" : "VIEWER", "groupId" : "FRIENDS"});
    req.add(req.newFetchPeopleRequest(idSpec, params), "viewerFriends");
    req.send(loadFriends);
  };

  function loadFriends(data) {
    if (data.hadError()) {
      output("Error: " + data.get("viewerFriends").getErrorMessage());
    } else {
      var viewerFriends = data.get("viewerFriends").getData();
      viewerFriends.each(function(person) {
          output(person.getDisplayName());
      });
    }
  };

  fetchFriends();

Class: opensocial.DataResponse

Methods:

Methods orkut access policy Description
get(key) supported String key — name of the key
Returns opensocial.ResponseItem — Requested response calculated by the server
getErrorMessage() supported Returns String — Human-readable description of the error that occured
hadError() supported Reurns Boolean — Returns true if there was an error in fetching the data from server

Class: opensocial.Email — not supported

Class: opensocial.Enum

Methods:

Methods orkut access policy Description
getDisplayValue() supported Returns String — The enum's value
getKey() supported Returns String — The enum's key

Fields (opensocial.Enum.Drinker) — not supported

Fields (opensocial.Enum.Gender):

OpenSocial field orkut field orkut access policy
FEMALE gender(female) supported
MALE gender(male) supported

Fields (opensocial.Enum.LookingFor): — It is supported but there is a bug

OpenSocial field orkut field orkut access policy
ACTIVITY_PARTNERS activity partners supported
DATING dating supported
FRIENDS friends supported
NETWORKING business networking supported
RANDOM not supported
RELATIONSHIP not supported

Fields (opensocial.Enum.Presence) — not supported

Fields (opensocial.Enum.Smoker) — not supported

Class: opensocial.Environment

Methods:

Methods orkut access policy Description
getDomain() supported Returns String — The current domain
supportsField(objectType,fieldName) supported opensocial.Environment.ObjectType objectType — object type to check for the field
String fieldName — name of the field to check for
Returns Boolean — true if the field is supported

Fields (opensocial.Environment.ObjectType):

OpenSocial field orkut access policy
ACTIVITY supported
ADDRESS supported
BODY_TYPE not supported
EMAIL not supported
FILTER_TYPE supported
MEDIA_ITEM supported
MESSAGE supported
MESSAGE_TYPE not supported
NAME supported
ORGANIZATION not supported
PERSON supported
PHONE not supported
SORT_ORDER supported
URL supported

Examples: 

  /** Check ========================================== */
  function check() {
    var env = opensocial.getEnvironment();

   //Checks for opensocial.Activity.Field.TITLE_ID
    var supportsTitleId = env.supportsField(
        opensocial.Environment.ObjectType.ACTIVITY,
        opensocial.Activity.Field.TITLE_ID
    ); 

   //Checks for opensocial.Person.Field.ABOUT_ME
    var supportsAboutMe = env.supportsField(
        opensocial.Environment.ObjectType.PERSON,
        opensocial.Person.Field.ABOUT_ME
    );

    //Checks for opensocial.Person.Field.LOOKING_FOR
    var supportsLookingFor = env.supportsField(
        opensocial.Environment.ObjectType.PERSON,
        opensocial.Person.Field.LOOKING_FOR
    );

    output("Domain: " + env.getDomain());
    output("Supports activity title id?  " + supportsTitleId);
    output("Supports about me?  " + supportsAboutMe);
    output("Supports looking for?  " + supportsLookingFor);
  };

  check();

Class: opensocial.EscapeType

Fields(opensocial.EscapeType):

OpenSocial field orkut access policy
HTML_ESCAPE supported
NONE supported

Class: opensocial.IdSpec

Methods:

Methods orkut access policy Description
getField(key, opt_params) supported String key — key to get data for; keys are defined in opensocial.IdSpec.Field
Map. opt_params — Additional params to pass to the request
Returns String — data
setField(key, data) supported String key — key to set data for
String data — data to set
Returns None

Fields(opensocial.IdSpec.Field):

OpenSocial field orkut access policy Notes
GROUP_ID supported
NETWORK_DISTANCE supported orkut supports values less than or equal to 1
USER_ID supported

Fields(opensocial.IdSpec.GroupId):

OpenSocial field orkut access policy
ALL supported
FRIENDS supported
SELF supported

Fields(opensocial.IdSpec.PersonId):

OpenSocial field orkut access policy
OWNER supported
VIEWER supported

Class: opensocial.MediaItem

Methods:

Methods orkut access policy Description
getField(key, opt_params) supported String key — key to get data for; keys are defined in opensocial.MediaItem.Field
Map. opt_params — Additional params to pass to the request
Returns String — data
setField(key, data) supported String key — key to set data for
String data — data to set
Returns None

Fields(opensocial.MediaItem.Field):

OpenSocial field orkut access policy
ALBUM_ID supported
CREATED not supported
DESCRIPTION supported
DURATION not supported
FILE_SIZE not supported
ID supported
LANGUAGE not supported
LAST_UPDATED not supported
LOCATION not supported
MIME_TYPE supported
NUM_COMMENTS not supported
NUM_VIEWS not supported
NUM_VOTES not supported
RATING not supported
START_TIME not supported
TAGGED_PEOPLE not supported
TAGS not supported
THUMBNAIL_URL supported
TITLE/CAPTION supported
TYPE supported
URL supported

Fields(opensocial.MediaItem.Type):

OpenSocial field orkut access policy
AUDIO not supported
IMAGE supported
VIDEO not supported

Class: opensocial.Message

Methods:

Methods orkut access policy Description
getField(key, opt_params) supported String key — key to get data for; keys are defined in opensocial.Message.Field
Map. opt_params — Additional params to pass to the request
Returns String — data
setField(key, data) supported String key — key to set data for
String data — data to set
Returns None

Fields(opensocial.Message.Field):

OpenSocial field orkut access policy
APP_URL not supported
BODY supported
BODY_ID not supported
COLLECTION_IDS not supported
ID not supported
IN_REPLY_TO not supported
RECIPIENTS not supported
REPLIES not supported
SENDER_ID not supported
STATUS not supported
TIME_SENT not supported
TITLE supported
TITLE_ID not supported
TYPE not supported
UPDATED not supported
URLS not supported

Examples: 

  /** Sends an internal message to orkut ========================================== */

  function sendMessage(title, body) {
    var params = [];
    params[opensocial.Message.Field.TITLE] = title;
    params[opensocial.Message.Field.TYPE] = opensocial.Message.Type.EMAIL;

    var message = opensocial.newMessage(body, params);
    var recipient = "VIEWER";
    opensocial.requestSendMessage(recipient, message, callback);
  };

  function callback(data) {
    if (data.hadError()) {
      output("Error: " + data.getErrorMessage());
    } else {
      output("Message sent successfully");
    }
  };

  sendMessage("This is a test message", "How are you doing!");

Class: opensocial.MessageCollection — not supported

Class: opensocial.Name

Methods:

Methods orkut access policy Description
getField(key, opt_params) supported String key — key to get data for; keys are defined in opensocial.Name.Field
Map. opt_params — Additional params to pass to the request
Returns String — data

Fields(opensocial.Name.Field):

OpenSocial field orkut field orkut access policy
ADDITIONAL_NAME not supported
FAMILY_NAME last name supported
GIVEN_NAME first name supported
HONORIFIC_PREFIX not supported
HONORIFIC_SUFFIX not supported
UNSTRUCTURED not supported

Class: opensocial.NavigationParameters — not supported

Class: opensocial.Organization — not supported

Class: opensocial.Permission

Fields:

OpenSocial field orkut access policy
VIEWER supported

Class: opensocial.Person

Methods:

Methods orkut access policy Description
getAppData() not supported
getDisplayName() supported Returns String — The display name
getField(key, opt_params) supported String key — key to get data for; keys are defined in opensocial.Person.Field
Map. opt_params — Additional params to pass to the request
Returns String — data
getId() supported Returns String — the id
isOwner supported Returns Boolean — true if this is the owner of the page
isViewer supported Returns Boolean — true if this is the currently logged in user

Fields(opensocial.Profile.Field):

OpenSocial field orkut field(profile type) orkut access policy
ABOUT_ME about me(social) supported
ACTIVITIES activities(social) supported
ADDRESSES city, state, country, latitude/longitude (general/contact) supported
AGE not supported
BODY_TYPE not supported
BOOKS books(social) supported
CARS not supported
CHILDREN not supported
CURRENT_LOCATION city, state, country, latitude/longitude (general/contact) supported
DATE_OF_BIRTH not supported
DRINKER not supported
EMAILS not supported
ETHNICITY not supported
FASHION fashion(social) supported
FOOD cuisines(social) supported
GENDER gender(general) supported
HAPPIEST_WHEN not supported
HAS_APP not supported
HEROES not supported
HUMOR humor(social) supported
ID supported
INTERESTS passion(social) supported
JOB_INTERESTS career interests(professional) supported
JOBS not supported
LANGUAGES_SPOKEN languages i speak(general) supported
LIVING_ARRANGEMENT living(social) supported
LOOKING_FOR interested in(general) supported
MOVIES movies(social) supported
MUSIC music(social) supported
NAME(GIVEN_NAME) first name(general) supported
NAME(FAMILY_NAME) last name(general) supported
NETWORK_PRESENCE not supported
NICKNAME not supported
PETS not supported
PHONE_NUMBERS not supported
POLITICAL_VIEWS political view(social) supported
PROFILE_SONG not supported
PROFILE_URL profile url(general) supported
PROFILE_VIDEO not supported
QUOTES not supported
RELATIONSHIP_STATUS relationship status(general) supported
RELIGION not supported
ROMANCE ideal match(personal) supported
SCARED_OF not supported
SCHOOLS not supported
SEXUAL_ORIENTATION not supported
SMOKER not supported
SPORTS sports(social) supported
STATUS headline(personal) supported
TAGS not supported
THUMBNAIL_URL thumbnail url(general) supported
TIME_ZONE not supported
TURN_OFFS turn offs (personal) supported
TURN_ONS turn ons (personal) supported
TV_SHOWS tv shows(social) supported
URLS webpage(social) supported

Class: opensocial.Phone — not supported

Class: opensocial.ResponseItem

Methods:

Methods orkut access policy Description
getData() supported Retutrns Object — requested value calculated by the server
getErrorCode() supported Returns String — error code , or null if no error occurred
getErrorMessage() supported Returns String — Human readable description of the error that occurred
getOriginalDataRequest() supported Retutrns Object — Request item used to fetch this data response
hadError() supported Returns Boolean — true if there was an error

Fields (opensocial.ResponseItem.Error):

OpenSocial field orkut access policy
BAD_REQUEST supported
FORBIDDEN supported
INTERNAL_ERROR supported
LIMIT_EXCEEDED supported
NOT_IMPLEMENTED supported
UNAUTHORIZED supported

Class: opensocial.Url

Methods:

Methods orkut access policy Description
getField(key, opt_params) supported String key — key to get data for; keys are defined in opensocial.Url.Field
Map. opt_params — Additional params to pass to the request
Returns String — data

Fields (opensocial.Url.Field):

OpenSocial field orkut access policy
ADDRESS supported
LINK_TEXT not supported
TYPE supported