Orkut Application Platform

On-Site Application Developer Guide: People

Contents

Viewer and Owner

Any profile on Orkut is represented by a Person object. However, remember that on-site applications are always installed on someone's profile and are always being seen by a particular person, so these two persons are special to an application:

  • The owner is the person on whose profile the application is installed.
  • The viewer is the person who is currently viewing the application.

So if Joe installs an application on his profile and then views it, he is both the viewer and the owner (this is called running the application in owner mode). However, if Jane visit Joe's profile and views the application, then Joe is the owner and Jane is the viewer.

When the viewer is not the owner, we say that the application is running in guest mode. There are two possibilities for this mode: if the viewer has the app installed in his profile as well, then the application can have access to the viewer's information; otherwise, for safety reasons, the application cannot retrieve the viewer's information or identity, and this is called the anonymous guest mode.

So, to summarize:

Viewer is... Viewer Has App Installed in her profile too? Resulting Mode Notes
same as the owner yes owner mode can access both viewer and owner data (which are the same)
not the owner yes named guest mode can access both viewer and owner data (which are not the same)
not the owner no anonymous guest mode cannot access viewer's data

Request Example

This is an example of a code that retrieves information about the owner of a application:

function init() {
   var req = opensocial.newDataRequest();
   req.add(req.newFetchPersonRequest(
           opensocial.IdSpec.PersonId.OWNER), "mydata");
   req.send(callback);
   debug.say("Waiting for reply...");
}

function callback(data) {
   if (data.hadError()) { 
      debug.say("Error: " + data.getErrorMessage());
      // handle error here
      return;
   }
   var owner = data.get("mydata").getData();
   debug.say("Owner ID: " + owner.getId());
   debug.say("Owner: " + owner.getDisplayName());
}

gadgets.util.registerOnLoadHandler(init);

This code requests the owner of the application and displays the "display name" for that person (formatted first and last names).

Requesting the viewer is equally easy:

function init() {
   var req = opensocial.newDataRequest();
   req.add(req.newFetchPersonRequest(
           opensocial.IdSpec.PersonId.VIEWER), "mydata");
   req.send(callback);
   debug.say("Waiting for reply...");
}

function callback(data) {
   if (data.hadError()) { 
      debug.say("Error: " + data.getErrorMessage()); 
      // handle error here
      return; 
   }
   var viewer = data.get("mydata").getData();
   debug.say("Viewer ID: " + viewer.getId());
   debug.say("Viewer: " + viewer.getDisplayName());
}

gadgets.util.registerOnLoadHandler(init);

If the viewer data cannot be retrieved (for example, because the application is running in anonymous guest mode, data.hadError() will return true.

OpenSocial ID and Orkut UID

The ID that you get from calling getId() on an OpenSocial Person object is called the OpenSocial ID of the person. This is different from the Orkut UID, so this will not be the number you see on the URL when accessing that person's profile. See the section on the Orkut Environment for more information about how to get Orkut UID from an OpenSocial ID and how to build correct links to Orkut resources such as profiles.

Other Person Fields

If you need other fields from the Person object, you have to request them specifically. Here is an example that requests the owner's "about me" statement and his thumbnail URL, apart from the name:

function init() {
   var req = opensocial.newDataRequest();

   // specify what profile details we want to retrieve
   var extraParams = {};
   extraParams[opensocial.DataRequest.PeopleRequestFields.PROFILE_DETAILS] = [
          opensocial.Person.Field.ABOUT_ME,
          opensocial.Person.Field.THUMBNAIL_URL,
   ];

   req.add(req.newFetchPersonRequest("OWNER", extraParams), "mydata");
   req.send(callback);
   debug.say("Waiting for reply...");
}

function callback(data) {
   if (data.hadError()) { 
      debug.say("Error: " + data.getErrorMessage());
      // handle error here
      return;
   }
   var owner = data.get("mydata").getData();
   debug.say(
         "Display Name " + owner.getDisplayName() + "\n" +
         "OpenSocial ID: " + owner.getId() + "\n" +
         "About me: " + owner.getField(opensocial.Person.Field.ABOUT_ME) + "\n" +
         "Thumbnail: " + owner.getField(opensocial.Person.Field.THUMBNAIL_URL));
}

gadgets.util.registerOnLoadHandler(init);

As you can see, the extraParams dictionary lists what additional parameters we need, and the Person object's getField() method retrieves each field.

For a full list of all the Person fields that are available, please check the Person section of our OpenSocial Feature Mapping article. Apart from telling you which fields are available, this guide also indicates how the data is returned.

A complete example

The following example requests and lists the value of every OpenSocial field supported by Orkut to illustrate what is returned in each case:

<div id='output'>Loading...</div>
<script type='text/javascript'>
var fields = [];
var fielddescs = [];

function addfield(name, value) {
   if (typeof value == 'undefined') {
      debug.say('!!! WARNING: field ' + name + ' is unknown.');
      return;
   }
   fields.push(value);
   fielddescs.push( { name: name, value: value } );
}

function init() {
   addfield("ABOUT_ME", opensocial.Person.Field.ABOUT_ME);
   addfield("ADDRESSES", opensocial.Person.Field.ADDRESSES);
   addfield("BOOKS", opensocial.Person.Field.BOOKS);
   addfield("CURRENT_LOCATION", opensocial.Person.Field.CURRENT_LOCATION);
   addfield("FASHION", opensocial.Person.Field.FASHION);
   addfield("FOOD", opensocial.Person.Field.FOOD);
   addfield("GENDER", opensocial.Person.Field.GENDER);
   addfield("HUMOR", opensocial.Person.Field.HUMOR);
   addfield("INTERESTS", opensocial.Person.Field.INTERESTS);
   addfield("LANGUAGES_SPOKEN", opensocial.Person.Field.LANGUAGES_SPOKEN);
   addfield("LIVING_ARRANGEMENT", opensocial.Person.Field.LIVING_ARRANGEMENT);
   addfield("MOVIES", opensocial.Person.Field.MOVIES);
   addfield("MUSIC", opensocial.Person.Field.MUSIC);
   addfield("NAME", opensocial.Person.Field.NAME);
   addfield("PROFILE_URL", opensocial.Person.Field.PROFILE_URL);
   addfield("RELATIONSHIP_STATUS", opensocial.Person.Field.RELATIONSHIP_STATUS);
   addfield("SPORTS", opensocial.Person.Field.SPORTS);
   addfield("STATUS", opensocial.Person.Field.STATUS);
   addfield("THUMBNAIL_URL", opensocial.Person.Field.THUMBNAIL_URL);
   addfield("TURN_ONS", opensocial.Person.Field.TURN_ONS);
   addfield("TV_SHOWS", opensocial.Person.Field.TV_SHOWS);
   addfield("URLS", opensocial.Person.Field.URLS);

   req = opensocial.newDataRequest();
   params = [];
   params[opensocial.DataRequest.PeopleRequestFields.PROFILE_DETAILS] = fields;
   req.add(req.newFetchPersonRequest(
     opensocial.IdSpec.PersonId.VIEWER, params), 'viewer');
   req.send(callback);
   debug.say("Request sent. Waiting for reply.");
}

function callback(resp) {
   if (resp.hadError()) {
      debug.say("*** Error ***");
      return;
   }
   debug.say("success.");
   var viewer = resp.get('viewer').getData();

   var html = [];

   for (i in fielddescs) {
      var thisdesc = fielddescs[i];
      var fieldName = thisdesc.name;
      var fieldValue = thisdesc.value;
      var val = viewer.getField(fieldValue);
      var content;

      if (typeof val == 'undefined') content = "<em>undefined</em>";
      else if (val == null) content = "<em>null</em>";
      else
         content = gadgets.util.escapeString(gadgets.json.stringify(val));

      html.push("<p><b>" + fieldName + "</b><br />" + content + "</p>");
   }
   document.getElementById('output').innerHTML = html.join('');
}

gadgets.util.registerOnLoadHandler(init);
</script>

Here is a sample output from the above sample:

ABOUT_ME
"$%mgtd#&Hello, I am a test profile. Isn't that great?"

ADDRESSES
[{"fields_":{"region":"","locality":"Sao Nunca de Piratininga","type":"currentLocation","country":"BR"}}]

BOOKS
["Example Books"]

CURRENT_LOCATION
{"fields_":{"region":"","locality":"Sao Nunca de Piratininga","type":"currentLocation","country":"BR"}}

FASHION
"alternative,casual,classic,contemporary,designer,minimal,natural,outdoorsy,smart,trendy,urban"

FOOD
["Example Cuisines"]

GENDER
{"key":"MALE","displayValue":"male"}

HUMOR
"campy/cheesy,dry/sarcastic,clever/quick witted,friendly,goofy/slapstick,obscure,raunchy"

INTERESTS
["Example Passions"]

LANGUAGES_SPOKEN
["en-US"]

LIVING_ARRANGEMENT
"alone,with roommates,with partner,with pets,with kids,with parents,friends visit often,party every night"

MOVIES
["Example Movies"]

MUSIC
["Example Music"]

NAME
{"fields_":{"familyName":"Testprofile","givenName":"Aaaa"}}

PROFILE_URL
"http://prod.sandbox.orkut.com/Profile.aspx?uid=14286646651488297787&mt=os"

RELATIONSHIP_STATUS
"single"

SPORTS
["Example Sports"]

STATUS
"testing 123"

THUMBNAIL_URL
"http://img1.orkut.com/images/small/1302905532/620334405/ln.jpg"

TURN_ONS
["assertiveness","body piercings","candlelight","dancing","erotica","flirting","intelligence","long hair","public displays of affection","power","sarcasm","skinny dipping","tattoos","thrills","thunderstorms","wealth"]

TV_SHOWS
["Example TV Shows"]

URLS
[{"fields_":{"value":"http://example.com/web/page","address":"http://example.com/web/page"}}]

Why are certain fields unavailable?

Some important points to keep in mind about the availability of profile fields are:

  • Orkut does not expose any of the fields that contain personally identifiable information through the API, even if they are defined in the OpenSocial standard (for example, emails, phone numbers, etc).

  • If you are listing the fields of a friend of the viewer, your access may be further limited. If you are listing the fields of a friend who does not also have the application installed on his profile, you won't be able to access anything but the name and the profile photo.

  • Unless the person has marked a field on his profile as "accessible to everybody on Orkut", it will not be available to applications. So all fields marked as "visible only to friends" or only to "friends of friends" will not be returned by OpenSocial calls.

  • Some OpenSocial fields are not implemented yet despite being part of the standard.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.