Orkut Application Platform

On-Site Application Developer Guide: Friends

Contents

Retrieving Friends

To retrieve a person's friends (this person can only be the viewer or the owner), you have to issue a "Fetch People" request as illustrated below. This example lists the viewer's friends (up to a maximum of 20 friends):

function init() {
   var req = opensocial.newDataRequest();
   var opt_params = {};
   opt_params[opensocial.DataRequest.PeopleRequestFields.MAX] = 20;
   var idspec = opensocial.newIdSpec({ "userId" : "VIEWER", "groupId" : "FRIENDS" });
   req.add(req.newFetchPeopleRequest(idspec, 
      opt_params), 'viewerFriends');

   req.send(onLoadFriends);
   debug.say("Waiting for reply...");
}

function onLoadFriends(data) {
  if (data.hadError()) {
     debug.say("Error: " + data.getErrorMessage());
     // handle error here
     return;
  }

  var friends = data.get('viewerFriends').getData().asArray();

  debug.say(friends.length + " friends returned:");
  for (var i in friends)
    if (friends[i].getId()) debug.say('- ' + friends[i].getDisplayName());
}

gadgets.util.registerOnLoadHandler(init);

Notice the idspec variable. We initialized it with the following:

var idspec = opensocial.newIdSpec({ "userId" : "VIEWER", "groupId" : "FRIENDS" });

This indicates that the target of our request will be the viewer's friends. If, instead, we wanted the owner's friends, we would have used:

var idspec = opensocial.newIdSpec({ "userId" : "OWNER", "groupId" : "FRIENDS" });

It's worth noting that the returned data object that you get from getData() on the callback is an OpenSocial Collection, which you can convert to a Javascript array calling asArray(), which is what we do in the code above. Each element in that array will be an OpenSocial Person.

If you want to retrieve additional information from friends, such as their thumbmail URLs, you can add that to the request via opt_params:


<div id='friendsdiv'>Loading...</div>
<script type="text/javascript">

function init() {
   var req = opensocial.newDataRequest();
   var opt_params = {};
   opt_params[opensocial.DataRequest.PeopleRequestFields.MAX] = 20;
   opt_params[opensocial.DataRequest.PeopleRequestFields.PROFILE_DETAILS] = [
          opensocial.Person.Field.THUMBNAIL_URL
   ];
   var idspec = opensocial.newIdSpec({ "userId" : "VIEWER", "groupId" : "FRIENDS" });
   req.add(req.newFetchPeopleRequest(idspec,
      opt_params), 'viewerFriends');

   req.send(onLoadFriends);
   debug.say("Waiting for reply...");
}

function formatFriend(f) {
   var thumburl = f.getField(opensocial.Person.Field.THUMBNAIL_URL);
   var name = gadgets.util.escapeString(f.getDisplayName());
   return "<img src='" + thumburl + "'> " + name + "<br>";
}

function onLoadFriends(data) {
  if (data.hadError()) {
     debug.say("Error: " + data.getErrorMessage());
     // handle error here
     return;
  }

  var friends = data.get('viewerFriends').getData().asArray();
 
  debug.say(friends.length + " friends returned.");
  var html = [];
  for (var i in friends)
    if (friends[i].getId())
       html.push(formatFriend(friends[i]));
  document.getElementById('friendsdiv').innerHTML = html.join('');
}  

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

The preceding example loads the friends and their profile pictures, and displays them in an HTML div.

Important: most data fields are only available to you if that person also has your application installed on their profile. If the person you are listing does not have your application installed, you will be able to query for little more than the name and the profile picture.

Listing only the friends that have the app

If you only want to list the person's friends who also have your application installed (as opposed to all friends), you can add that as a filter option to the request:

function init() {
   var req = opensocial.newDataRequest();
   var idspec = opensocial.newIdSpec({ "userId" : "VIEWER", "groupId" : "FRIENDS" });

   var opt_params = {};
   opt_params[opensocial.DataRequest.PeopleRequestFields.MAX] = 20;
   opt_params["filter"] = "hasApp";   // only friends w/ app installed

   req.add(req.newFetchPeopleRequest(idspec, opt_params), 'viewerFriends');
   req.send(onLoadFriends);
   debug.say("Waiting for reply...");
}

function onLoadFriends(data) {
   // ...
}

gadgets.util.registerOnLoadHandler(init);

Paginating the Friends List

The examples we provided above all limit the number of friends to 20. We do this in order to limit the size of the request since the user might have several hundred friends. If you don't specify the page size as we did above, your request would essentially ask for the entire list, which may take long to load and you may see timeout errors.

Therefore, the recommended way to list friends is to do it incrementally, requesting one page at a time until the list is complete. Here is an example that does exactly that.

<div id='mosaicdiv'>Loading friends... Please wait.</div>

<script type='text/javascript'>
var first = 0;
var PAGE_SIZE = 20;
var friends = [];

function startFetchPage() {
   var req = opensocial.newDataRequest();
   var param = {};

   // indicate the start index and how many friends we want to list
   param[opensocial.DataRequest.PeopleRequestFields.FIRST] = first;
   param[opensocial.DataRequest.PeopleRequestFields.MAX] = PAGE_SIZE;
   param[opensocial.DataRequest.PeopleRequestFields.PROFILE_DETAILS] = [
      opensocial.Person.Field.THUMBNAIL_URL
   ];

   var idspec = opensocial.newIdSpec({ "userId" : "VIEWER", 
       "groupId" : "FRIENDS" });
   req.add(req.newFetchPeopleRequest(idspec, param), "data");
   req.send(onLoadPage);
   debug.say("Loading friends " + first + " to " + (first + PAGE_SIZE) + "...");
}

function buildMosaic() {
   var html = [];
   for (var i in friends) {
      html.push("<img src='");
      html.push(friends[i].getField(opensocial.Person.Field.THUMBNAIL_URL));
      html.push("' alt='");
      html.push(friends[i].getDisplayName());
      html.push("'>");
   }
   document.getElementById('mosaicdiv').innerHTML = html.join('');
}

function onLoadPage(data) {
   if (data.hadError()) {
      debug.say("*** Error: " + data.getErrorMessage());
      // handle error here
      return;
   }

   var returnedArray = data.get("data").getData().asArray();

   if (returnedArray.length == 0) {
      // done loading! No more friends to load.
      debug.say("Done loading. " + friends.length + " friends loaded.");
      buildMosaic();
   }
   else {
      // add to our current list
      friends = friends.concat(returnedArray);

      // and ask for more
      first += PAGE_SIZE;
      startFetchPage();
   }
}

gadgets.util.registerOnLoadHandler(startFetchPage);

</script>

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.