Orkut Application Platform

On-Site Application Developer Guide: The Orkut Environment

In this section, we will discuss a little bit about some features of the Orkut environment that are available to your application. Most of these features are somewhat specific to Orkut, so, even though applications are based on the OpenSocial standard, some of the techniques presented in this section are unlikely to work in other social containers.

Contents

Bypassing the XML Cache

There is a way to force Orkut to bypass the XML cache, which is useful when testing your application because it will show the result of your changes immediately: just add the bpc=1 parameter to the URL when opening the canvas app page. This only works in your app's canvas page, in sandbox or prod sandbox.

So, for example:

http://sandbox.orkut.com/Main#Application?appId=0000000&bpc=1

Disabling URL Rewriting

Orkut does agressive caching of your application's resources in order to ensure the best possible user experience. However, this can be inconvenient during development, since you usually want to see the result of your changes immediately.

This caching strategy is implemented by rewriting your URLs to route them through our proxy, so in order to disable this mechanism, all you have to do is disable URL rewriting. You can do that for all URLs or only selected patterns (regular expressions) of URLs through the <Optional feature="content-rewrite"> tag, which you can add to the <ModulePrefs> tag on your application's XML.

<Optional feature="content-rewrite">
  <Param name="include-urls"></Param>
  <Param name="exclude-urls">.*</Param>
  <Param name="include-tags"></Param>
</Optional>

This example will disable URL rewriting for all URLs. However, remember to re-enable URL rewriting before launching your application, as that's a very important asset in the fight against latency!

For more information about techniques to reduce latency in your applications, see our article on Latency Tips.

Environment Parameters

Orkut makes certain environment parameters available to your application through the query string of the iframe that contains it. While you can query those parameters directly by inspecting window.location.href, it is probably a better idea to use the gadgets.util.getUrlParameters function to retrieve them.

For example, to retrieve the user's country, you might write:

var urlParams = gadgets.util.getUrlParameters();
debug.say("Viewer's country is " + urlParams['country']);

These are the URL parameters available to your application:

Parameter Meaning Example(s)
country The viewer's country code US
lang The viewer's language code en
gadgetId Your application's AppID 617779396847
gadgetOwner The Opensocial ID of the owner of the application, that is, the person on whose profile the application is installed 181958226559752186890
gadgetViewer The Opensocial ID of the viewer of the application, that is, the person who is currently viewing the application 181958226559752186890
parent Parent URL. This is Orkut's "base URL" as currently shown. This reflects the user's country and whether the application is running on sandbox, prod sandbox or production. http://www.orkut.com.br, http://prod.sandbox.orkut.com
url The URL of the applicaiton's XML. http://...../yourapp.xml
view-params Arbitrary string passed to the page via the appParams= parameter (we will discuss this further below) hello xyz123 abcdefgh
gadgetWidth If available, this indicates the width of the application, in pixels. If this parameter is absent, you should assume the width is 835px. 900
containerVersion If available, this specifies the version of the application container, which determines whether certain features are available. We will give more details about this parameter below. 1 or 2

Container Version Detection

The Container Version is supplied to your application in a new iframe parameter (containerVersion) in canvas view, so it can be retrieved like this:

var containerVersion = gadgets.util.getUrlParameters()["containerVersion"];

Its value is 1 for the canvas view container in the old orkut UI and 2 for the canvas view container in the new orkut UI. You can read this to determine which container your application is running inside of. Please be aware, however, that "container version" is not the same as "orkut UI version" and they may come out of sync when we launch new container versions or new UIs.

Configurable App Width

Orkut supports configurable width for applications in canvas view. You can specify a "preferred width" to orkut in your applications XML by means of the preferred_width attribute of the <Content> tag:

<?xml version="1.0" encoding="UTF-8"?>
<Module>
   <ModulePrefs title="Yourtitlehere"
      author="authorhere"
      author_email="email_here@......com"
      description="Description here...."
      screenshot="http://url/of/a/screenshot/of/your/app"
      thumbnail="http://url/of/the/thumbnail/for/your/app">
      <Require feature="opensocial-0.8" />
      <Locale lang="en" country="us" />
   </ModulePrefs>
<Content type="html" preferred_width="900">
<![CDATA[

...

</Content>
</Module>

The container will try to allocate your indicated width but might have to crop it if it's too big and expand it if it's too small. The actual width will be reported to you in the "gadgetWidth" iframe parameter.

Some points to take into account are:

  • The preferred_width parameter will only be taken into account when rendering your application on container version 2, but will be ignored in container version 1.

  • The container might or might not honor your preferred width depending on the available space.

  • The gadgetWidth iframe parameter is only available to your application in container version 2 and above. This is the "slight catch" we were talking about above.

Therefore, the correct way to determine your application's actual width is first testing the container version and then, if the version is 2 or above, reading the gadgetWidth parameter. Otherwise (container version 1), the width of the application is fixed at 835px. So an example of Javascript code would be:

// Determines the actual width of the application
function getActualWidth() {
   var w = (gadgets.util.getUrlParameters()["containerVersion"] >= 2) ?
             gadgets.util.getUrlParameters()["gadgetWidth"] : 835;
   if (w == null || typeof w == 'undefined') w = 835;  // just in case
   return w;
}

Arbitrary Application Parameters (AppParams)

You can pass an arbitrary string as a parameter to your application. There are many uses for this such as knowing where that user came from. To pass an arbitrary string to your application, include an appParams GET parameter on the URL of your Canvas Page (see the section on Orkut Pages for more information about the different landing pages related to your application), for example:

http://www.orkut.com/Application?appId=0000000000&appParams=abcdef12345

When your application runs, you can retrieve that value from the view-params environment parameter:

var urlParams = gadgets.util.getUrlParameters();
debug.say("App params: " + urlParams['view-params']);

If your link is meant to be accessed by users who do not yet have your application and may not be logged into Orkut at the moment (for example, if your link is a landing page for an advertisement), then you should use the PublicAppInfo page instead of the Application page:

http://www.orkut.com/PublicAppInfo?appId=0000000000&appParams=abcdef12345

This technique is very useful when you wish to embed data to be passed to your application upon installation. Some of the scenarios where this might be useful are:

  • Tracking install origins: you can include an identifier on the appParams indicating what is the origin of the click. Thus, if you use links with different IDs on each of your ad campaigns, links on websites and other sources of promotion, you can track which sources your users are coming from.
  • Gifts/Promotions: you can insert a gift ID on the URL that your application will interpret as a signal to grant a certain virtual gift to the user upon installation. That way, you can make gift certificates, promotions and other campaigns.
  • Customize the user's experience: If you are sending users to install your application after you know something about them, you might want to include parameters that customize the user's experience within the application. For example, if your application is location-aware and you already know the user's home city, you could pass that information along instead of having to ask the user again.

Getting a user's Orkut UID

On Orkut, each profile has an UID, which is what appears on the URL as the uid= parameter. For example:

http://www.orkut.com/Main#Profile?uid=4992458421129485385

This UID is not the same as the OpenSocial ID and cannot be used interchangeably. The Orkut UID is useful when creating links to Orkut pages, so you may want to obtain it from your code. Here is an example function that retrieves a person's Orkut UID:

function getUid(person) {  // person is an OpenSocial Person object
   var result = person.getField(
      opensocial.Person.Field.PROFILE_URL).match(/uid=([^&#]+)/);
   return (result.length == 2) ? result[1] : "ERROR";
}

As you can see, this function parses the Orkut UID from the profile URL. Parsing from URLs is currently the only way to obtain the Orkut UID. Here is an example that uses this function to list the Orkut UID for each of 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;

   // important: we must request the PROFILE_URL field in order to be able to parse
   // the Orkut UID from it!
   opt_params[opensocial.DataRequest.PeopleRequestFields.PROFILE_DETAILS] = [
      opensocial.Person.Field.PROFILE_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 getUid(person) {
   var result = person.getField(
      opensocial.Person.Field.PROFILE_URL).match(/uid=([^&#]+)/);
   return (result.length == 2) ? result[1] : "ERROR";
}

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

  var friends = data.get('viewerFriends').getData().asArray();
  for (var i in friends)
    if (friends[i].getId())
       debug.say('- ' + friends[i].getDisplayName() + "'s uid is " + getUid(friends[i]));
}

gadgets.util.registerOnLoadHandler(init);

Miscellaneous Notes

  • URL sanitization and URL length limit: Orkut applies sanitization to every URL that your application produces to display to the user (for example, any links sent in a message or posted on the activity stream). There is a 160-character limit to the length of any URL you employ. This includes any "app parameter string" you may wish to feed to your application. If you exceed this limit, the sanitizer may remove your URL because its processed version may become too large.

  • Use of tracking pixels on Activity Stream posts: Tracking pixels are currently not useful on an activity stream post, because URLs of assets referenced in these posts are always rewritten to go through our proxy, so tracking pixels will be cached and therefore lose their usefulness.

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.