This guide will help you build and manage applications within the orkut environment. It is meant for developers who have some general familiarity with orkut, the Gadgets API, and JavaScript in general, but provides links to other resources in places where you may need more information.
Orkut has been updated to support version 0.7 of the OpenSocial API, and this document has been modified to reflect changes from this update. Sections are marked as being New! or Updated! to help you identify coding practices that have changed since the last version.
Each OpenSocial container will have a different development experience. This section will familiarize you with the process of developing applications for use on orkut.
This article will use the following terms to describe elements and topics related to the orkut development experience.
| Activity stream | Data feed that contains activities from one person. |
|---|---|
| Application | Third party code that uses the Gadgets and OpenSocial APIs to extend the orkut experience. |
| Application definition | XML file that defines the application. Syntax is based on gadget XML, also known as the "gadget spec". |
| Application directory | Listing of available applications. |
| Application settings page | Listing of applications installed by user. Allows the user to add and remove applications. |
| Canvas view New! | Full page view of an application. |
| Left navbar | The list of links on the left hand side of orkut pages. The left navbar lists links for the logged in user (on the orkut homepage) or a friend (when looking at the friend's profile). |
| Left nav link | A link on the left navbar. These links can be to different orkut sections (e.g. profile), or to an OpenSocial application canvas page. |
| Profile view New! | View of an application on a user's profile |
| View New! | The location where an application is displayed. In orkut, applications can be displayed on either the canvas or profile views. Views were formerly called Surfaces in version 0.6. |
Before building applications for orkut it is useful to first familiarize yourself with orkut's new application platform. A helpful guide is the "Anatomy of an orkut Application" article, which serves as a visual guide to all of the enhancements that orkut has undergone in order to host applications.
If this is your first OpenSocial application, follow the steps listed in the OpenSocial Tutorial for Orkut to familiarize yourself with the OpenSocial API. This tutorial will cover the steps needed to develop a simple gift-giving application using the OpenSocial API.
If you do not have access to a server to store your gadget XML files, the Google Gadget Editor is a great tool to quickly edit and host gadgets. To create a quick "Hello World" application, make sure that you are logged in with a Google account (or else you will not be able to save your gadget) and paste the following code into the gadget editor:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Hello World!">
<Require feature="opensocial-0.7" />
</ModulePrefs>
<Content type="html">
<![CDATA[
Hello, world!
]]>
</Content>
</Module>
When this is done, open your application's XML file by clicking on the filename in the top right-hand corner of the editor.
This will open the application XML in your browser. You'll need the URL of this file to install your app in the next section.
Note that preview mode in the Google Gadget Editor will not work for social applications. To see your code work in orkut, obtain the URL of your app as described above and follow the instructions in the next section.
Applications need to run inside of a container in order to access social network data. Orkut currently offers a developer sandbox where you can access the OpenSocial APIs and other new features. If you don't have access to http://sandbox.orkut.com (i.e. you get redirected to http://www.orkut.com when you try to access the sandbox) you should request that your orkut account be whitelisted as a developer. Since the orkut sandbox only returns data about friends who are also whitelisted for the sandbox, you will likely want to friend a few other developers to get some test data to work with. This thread in the OpenSocial developer forum and this orkut community are good places to grow your personal network of friends.
Inside the orkut sandbox, navigate to the applications page by clicking the "add apps" link orkut's left navbar or visiting http://sandbox.orkut.com/MyApps.aspx.
The "My applications" list will likely be empty if you are running examples for the first time, but you will see a field labeled "add an application directly by its url:".
Paste the URL of your application into this field and press the "add application" button.
New! You will be taken to the application's information page. Here you can see whether other users have rated or left comments about the application. Notice the "add application" button. Pressing this button will attempt to add this application to your profile.
Orkut will load the "Application Authorization" page. Listed on this page are privileges that you will be granting the application by installing it. Currently these are:
Some privileges have to be granted for the application to function, but you will also be able to choose whether to allow extra permissions, such as the ability to post to your activity stream. Check the boxes next to the optional permissions you wish to grant to the application.
To grant these privileges and install the application to your profile, click "add application". You will see the sample application listed in the page, as well as a link to the application in the left navbar.
At this point, click the "profile" link in the left navbar to see the application running in its orkut profile view. You can also click on the application's name in the navbar to be taken directly to the application's canvas view.
New! If you add multiple applications, you will notice that arrows appear next to the names of each application in the "My applications" view. Click these arrows to change the order of applications in your profile. Only the top three applications show up in your profile, so be sure to put applications you want visible on your profile at the top of this list.
Orkut caches OpenSocial application XML to minimize the number of times that each file has to be fetched, saving bandwidth and reducing user latency. Caching is great for cases where many users are requesting your application, but can be disruptive during application development when you want to see each change as soon as you update your application's code.
Fortunately, you can disable this caching mechanism by appending
&bpc=1 to the URL of any profile or application canvas page. This "bypass cache"
parameter instructs orkut to pull a fresh version of the gadget XML from your
server, rather than the version currently in its cache.
For example, if you are viewing:
http://sandbox.orkut.com/Application.aspx?uid=XXXXXXXXXXXX&appId=XXXXXXXX
You can view the uncached version by navigating to:
http://sandbox.orkut.com/Application.aspx?uid=XXXXXXXXXXXX&appId=XXXXXXXX&bpc=1
Note that the bpc=1 parameter only disables application XML
caching, and will not affect caching that you may experience if you link to
external JavaScript files or use gadgets.io.makeRequest
calls. The opensocial-resources
wiki contains an approach
to bypass the makeRequest cache that can help you in this case.
Keep in mind that users who are not viewing pages with the &bpc=1
parameter will not see updated changes until orkut refreshes its cache.
Typically, this should happen within an hour of your changes being saved.
Now that you've learned the basics for installing and updating applications, here are some tips and tricks that will help you build robust, social applications for orkut.
OpenSocial applications are a new type of application, based on gadgets technology, but extended to interact with social data retrieved from a website (also referred to as a container) that supports the OpenSocial API. Orkut is an example of an OpenSocial container, and this section focuses on the development aspects of working with OpenSocial applications specifically within the orkut environment.
Orkut provides some querystring parameters that give you additional data
about the context your application is running in. These parameters can be
parsed manually using window.location.href, or you can use the gadget
convenience function gadgets.util.getUrlParameters(). Here's a
list of available parameters and example values:
| Name | How to retrieve | Example value |
|---|---|---|
| Country | gadgets.util.getUrlParameters()["country"] | US |
| Language | gadgets.util.getUrlParameters()["lang"] | en-US |
| Owner ID | gadgets.util.getUrlParameters()["gadgetOwner"] | 12345678901234567890 |
| Viewer ID [1] | gadgets.util.getUrlParameters()["gadgetViewer"] | 12345678901234567890 |
| Parent URL | gadgets.util.getUrlParameters()["parent"] | http://sandbox.orkut.com |
| Gadget URL | gadgets.util.getUrlParameters()["url"] | http://example.com/gadget_specification.xml |
| View Name | gadgets.util.getUrlParameters()["view"] | canvas |
| View Parameters | gadgets.util.getUrlParameters()["view-params"] | {"foo":12345,"bar":"Bar value"} |
[1] Only available if the viewer has the gadget installed.
In orkut, your application may be displayed in the canvas and profile views. The easiest way to get the current view is to include the "views" feature in your application module preferences:
<ModulePrefs title="Views example">
<Require feature="views" />
</ModulePrefs>
When the views feature is included, you can obtain the current view by
calling the following gadget.util.getCurrentView() function. This assigns a gadgets.views.View
object to the current_view variable. See Available views in orkut for a listing of
views that may be returned by this call.
The following example demonstrates getting the current view and conditionally executing code against the returned value:
function getViewName() {
return gadgets.views.getCurrentView().getName();
}
if (getViewName() == "canvas") {
/* Do canvas specific stuff here */
}
if (getViewName() == "profile") {
/* Do profile specific stuff here */
}
<Require
feature="views"> in the ModulePrefs section of your
application.Obtain the available View objects by calling
the gadgets.views.getSupportedViews() function.
var supported_views = gadgets.views.getSupportedViews();
The object returned by the getSupportedViews call contains
gadgets.views.View
objects representing all of the available views in orkut, indexed by view name
Currently, these are:
| Name | Code to retrieve | Is only visible gadget |
|---|---|---|
| canvas | supported_views["canvas"] | true |
| profile | supported_views["profile"] | false |
| default | supported_views["default"] | false |
Each view corresponds with a different orkut page:
profile corresponds with a user's profile view. Profile
URLs look like
http://sandbox.orkut.com/Profile.aspx?uid=#####
canvas corresponds with the maximized view of an
application. Canvas URLs look like
http://sandbox.orkut.com/Application.aspx?uid=#####&appId=#####
default does not correspond with any orkut view. This view
is returned for compatibility with the multiple
content section feature of
the gadget specification. You should not use this view for navigation.In addition to requesting a view by name, you can also obtain a view by using a ViewType object. This allows you to obtain a type of view with specific properties without referring to the view by name.
The following table shows you how ViewType objects may be used
and which views they map to on orkut:
| Name | Code to retrieve | Maps to on orkut |
|---|---|---|
| DASHBOARD | supported_views[gadgets.views.ViewType.DASHBOARD] | profile |
| FULL_PAGE | supported_views[gadgets.views.ViewType.FULL_PAGE] | canvas |
| POPUP | N/A | N/A [1] |
[1] POPUP does not correspond with any of the orkut views.
<Require
feature="views"> in the ModulePrefs section of your
application.If you wish to provide links to other views, you need to pass a
gadgets.views.View object to the
gadgets.views.requestNavigateTo() method. You can choose to use one
of the objects returned by the getSupportedViews() call
described in the Available views in orkut. The
following code sample demonstrates this method:
function navigateTo(dest) {
var supported_views = gadgets.views.getSupportedViews();
gadgets.views.requestNavigateTo(supported_views[dest]);
};
/**
* When called, this method asks the container to switch to the canvas
*/
function gotoCanvas() {
navigateTo("canvas");
};
/**
* When called, this method asks the container to switch to the profile
*/
function gotoProfile() {
navigateTo("profile");
};
An alternative is to create a new View object manually, and
then use that to initiate navigation. The following code sample shows creating a new
gadgets.views.View object and
passing it to the gadgets.views.requestNavigateTo() method:
/**
* When called, this method asks the container to switch to the canvas
*/
function gotoCanvas() {
var canvas_view = new gadgets.views.View("canvas");
gadgets.views.requestNavigateTo(canvas_view);
};
/**
* When called, this method asks the container to switch to the profile
*/
function gotoProfile() {
var profile_view = new gadgets.views.View("profile");
gadgets.views.requestNavigateTo(profile_view);
};
You can obtain the application's ID number in orkut with the following call:
var application_id = gadgets.util.getUrlParameters()["gadgetId"];
After executing the snippet above, application_id will
contain the same value as the appId parameter in your
application's orkut URL.
<Require
feature="views"> in the ModulePrefs section of your
application.If you are using the gadgets.views.requestNavigateTo() calls, you
may supply an optional parameter containing data to be passed to the new page.
The following code passes two variables: foo and
bar to the canvas surface of the current application:
function gotoCanvas(params) {
var canvas_view = new gadgets.views.View("canvas");
gadgets.views.requestNavigateTo(canvas_view, params);
};
var my_params = {
foo : 12345,
bar : "Bar value"
};
gotoCanvas(my_params);
You should see that after the navigation has taken place, your URL will look similar to:
http://sandbox.orkut.com/Application.aspx?appId=xxxxxx&uid=xxxxxx&appParams=%7B%22foo%22%3A12345%2C%22bar%22%3A%22Bar%20value%22%7D
In the canvas view, check for these values with the following code:
var prefs = gadgets.views.getParams(); var foo = prefs["foo"]; /* foo contains 12345 */ var bar = prefs["bar"]; /* bar contains "Bar value" */
Caution! In orkut, the profile view may contain more than one application, which makes targeting data to a specific application using the OpenSocial 0.7 API impossible. Therefore, you can only pass data in this manner to the canvas view of an application. Data passed to the profile view will be ignored.
<Require
feature="views"> in the ModulePrefs section of your
application.There are cases where you may need to pass data to your application's canvas view from the querystring. Orkut allows for a special parameter named "appParams" that you can use to pass parameter data to your application. For example, going to the URL
http://sandbox.orkut.com/Application.aspx?appId=xxxxxxxxxxxx&appParams=%7B%20%22hello%22%20%3A%20%22hi%22%20%7D
(where xxxxxxxxxxxx is your application's ID number) will
forward a parameter named hello with a value of hi to
your application. You can retrieve this parameter in the following manner:
var querydata = gadgets.views.getParams(); var hello = querydata["hello"]; /* hello now contains the value "hi" */
%7B%20%22hello%22%20%3A%20%22hi%22%20%7D represents a URL-encoded
version of a JSON encoded object, which is the format orkut
expects the appParams value to be in. If you wish to custom-code
URLs to pass data to your applications, you will need to define a JSON object
and then encode this data to be able to be passed as a querystring parameter to
your application.
For example, to pass variables
foo with value 12345 and bar with value
"Bar value", first place these values in an object:
var data = { "foo" : 12345,
"bar" : "Bar value" };
To convert this to a JSON string, you can use the
gadgets.json.stringify function, or any other JSON library.
var json_data = gadgets.json.stringify(data);
json_data will contain the value {"foo":12345,"bar":"Bar
value"} after running the previous two code snippets. To escape this
value for use in a querystring, use the encodeURIComponent JavaScript
function:
var url_data = encodeURIComponent(json_data);
url_data will contain the value
%7B%22foo%22%3A12345%2C%22bar%22%3A%22Bar%20value%22%7D after
executing the previous snippets. You may now use this value in the
appParams querystring parameter to pass your data to your
application:
http://sandbox.orkut.com/Application.aspx?appId=xxxxxxxxxxxx&appParams=%7B%22foo%22%3A12345%2C%22bar%22%3A%22Bar%20value%22%7D
This approach is more difficult to use than the
requestNavigateTo() approach outlined in Passing data to your application through
requestNavigateTo() but the links you generate in this manner can be
displayed on external websites or in activity stream entries.
There are times when you need to obtain a Person's orkut UID, which is different from their OpenSocial ID number. For example, the orkut UID be used to generate a link to a canvas page in another user's context. Get the orkut UID by parsing the user's profile URL and extracting the UID parameter:
Caution! This method is orkut-specific and not portable to other OpenSocial containers. You should not use this method unless your application needs this data for orkut-only functionality.
function request() {
var req=opensocial.newDataRequest();
req.add(req.newFetchPersonRequest("VIEWER"), "viewer");
req.send(response);
};
function response(data) {
var viewer = data.get("viewer").getData();
var profile_url = viewer.getField(opensocial.Person.Field.PROFILE_URL);
var regex = /uid=([^&#]+)/;
var result = profile_url.match(regex);
if (result.length == 2) {
var uid = result[1];
/* uid now contains the viewer's orkut UID */
} else {
/* there was a problem getting the UID */
}
};
request();
The uid variable will contain a value that can be used to
construct links to an application canvas. See Linking to pages inside your application for more
information.
<Require
feature="views"> in the ModulePrefs section of your
application.You can combine some of these techniques to create URLs that can link to different pages in your application. Imagine that you wish to provide a link to an "about" page in your application. First, you need to dynamically generate a link similar to:
http://sandbox.orkut.com/Application.aspx?appId=XXXXXXXX&uid=YYYYYYYY&appParams=%7B%22page%22%3A%22about%22%7D
Where XXXXXXXX is the application ID (see Obtaining the application's ID) and
YYYYYYYY is the orkut UID of the person you wish to link to (see
Getting a user's orkut UID). URLs in this format can be
constructed in the following manner:
function makeLink(page, app_id, uid) {
return [ gadgets.util.getUrlParameters()["parent"],
"/Application.aspx?appId=",
app_id,
"&uid=",
uid,
"&appParams=%7B%22page%22%3A%22",
page,
"%22%7D"].join("");
};
/* stored_app_id should be initialized to the application ID - Check the
* "Obtaining the application's ID" section for details on
* obtaining this.
* stored_uid should be initialized to the user's orkut UID - Note that
* is _not_ the same as the opensocial ID number! Check the
* "Getting a user's orkut UID" section for details on
* obtaining this. */
var about_url = makeLink("about", stored_app_id, stored_uid);
You can print these links in a user's activity stream, or even on an external website.
If you don't want to generate a URL, but just want to redirect a user to the
"about" page as they use your application, call
gadgets.views.requestNavigateTo() with extra parameter data:
function gotoPage(to_page) {
var canvas_view = new gadgets.views.View("canvas");
var params = {};
params["page"] = to_page;
gadgets.views.requestNavigateTo(canvas_view, params);
};
gotoPage("about");
In your application, switch on the value of the page
parameter to choose which page to render:
var page = gadgets.views.getParams()["page"];
if (page == "about") {
renderAboutPage();
} else {
renderNormalPage();
}
This code will work no matter which method you choose to pass the
page parameter to your application.
Activity streams allow developers to send notifications to a user's friends about actions that the user has made while interacting with an orkut application. Activity streams are rendered as "updates" in the orkut user interface. To view your friends updates, visit http://sandbox.orkut.com/Notifications.aspx. To view your updates, visit http://sandbox.orkut.com/MyUpdates.aspx.
Applications are extensions of a user's profile. Orkut's activity stream
policies are therefore the same as other parts of the site, like photos,
scrapbook, and profile fields. The following list shows when calls to
requestCreateActivity will and will not succeed in orkut:
Activity stream entries will be shown on:
[1] Currently, orkut does not support friend groups or ranking
of updates based on importance. These features are forthcoming.
[2] Events are currently not listed on profile pages in orkut.
This feature is forthcoming.
The following table shows which events will be shown in which locations:
| Event type | Homepage and "view more" page | User's profile page |
|---|---|---|
| Native events | Photo, video, status, testimonial, and important profile field updates | Photo, video, status, testimonial, and all profile field updates |
| App install and uninstall | No | Yes |
| Events from applications | Yes | Yes |
To avoid applications spamming the activity stream, applications will be limited to posting three activity stream updates per application per user per day. Note that this limit will only be in place on production orkut (www.orkut.com). To make development easier, the sandbox will not have any limits on activity stream updates.
The OpenSocial API provides access to information about orkut's users in the form of profile data. This data is not all given by default, so this section explains what information will, may, and will not be available to applications on orkut.
For an application to access user profile data, the user must have granted access to the app by installing the application on their own profile.
Orkut will not share personally identifiable information (PII) with applications. Applications will not have access to phone numbers, email addresses, birthdays, and street addresses of orkut users.
The data that will be made available to applications will only be data that users have marked as being available to "everyone". Data that is restricted to friends or friends of friends will not be available to applications.
This section lists all the profile fields available through OpenSocial, and orkut's access policy for each. The following policy labels are used:
| Available | Data will be made available to the application if the user sets privacy on this field to "share with everyone". |
|---|---|
| Not Yet Implemented | This field will be available in the future. |
| Personally Identifiable Information | Will not be available to applications. |
| Orkut field | OpenSocial field | Orkut access policy |
|---|---|---|
| First name | NAME (GIVEN_NAME) | Available |
| Last name | NAME (FAMILY_NAME) | Available |
| Gender | GENDER | Available |
| Relationship status | RELATIONSHIP_STATUS | Available |
| Birthday | DATE_OF_BIRTH | Personally Identifiable Information |
| Birthyear | DATE_OF_BIRTH | Personally Identifiable Information |
| City, State, Country | CURRENT_LOCATION and ADDRESSES | Available |
| Latitude / Longitude | CURRENT_LOCATION and ADDRESSES | Available |
| Zipcode | CURRENT_LOCATION and ADDRESS | Personally Identifiable Information |
| Languages I speak | LANGUAGES_SPOKEN | Available |
| High school | SCHOOLS | Not Yet Implemented |
| College / university | SCHOOLS | Not Yet Implemented |
| Company / organization | JOBS | Not Yet Implemented |
| Interested in | LOOKING_FOR | Not Yet Implemented |
| Orkut field | OpenSocial field | Orkut access policy |
|---|---|---|
| Children | CHILDREN | Not Yet Implemented |
| Ethnicity | ETHNICITY | Not Yet Implemented |
| Religion | RELIGION | Not Yet Implemented |
| Political view | POLITICAL_VIEWS | Available |
| Humor | HUMOR | Available |
| Sexual orientation | SEXUAL_ORIENTATION | Not Yet Implemented |
| Fashion | FASHION | Available |
| Smoking | SMOKER | Not Yet Implemented |
| Drinking | DRINKER | Not Yet Implemented |
| Pets | PETS | Not Yet Implemented |
| Living | LIVING_ARRANGEMENT | Available |
| Hometown | ADDRESSES | Not Yet Implemented |
| Webpage | URLS | Available |
| About me | ABOUT_ME | Available |
| Passions | INTERESTS | Available |
| Sports | SPORTS | Available |
| Activities | ACTIVITIES | Available |
| Books | BOOKS | Available |
| Music | MUSIC | Available |
| TV Shows | TV_SHOWS | Available |
| Movies | MOVIES | Available |
| Cuisines | FOOD | Available |
| Orkut field | OpenSocial field | Orkut access policy |
|---|---|---|
| Primary email | EMAILS | Personally Identifiable Information |
| Secondary emails | EMAILS | Personally Identifiable Information |
| Google Talk IM | N/A | N/A |
| IM usernames | N/A | N/A |
| Home phone | PHONE_NUMBERS | Personally Identifiable Information |
| Cell phone | PHONE_NUMBERS | Personally Identifiable Information |
| SMS | PHONE_NUMBERS | Personally Identifiable Information |
| Address | ADDRESSES and CURRENT_LOCATION | Personally Identifiable Information |
| City, State, Country | ADDRESSES and CURRENT_LOCATION | Available |
| Latitude / Longitude | CURRENT_LOCATION and ADDRESSES | Available |
| Zipcode | ADDRESSES and CURRENT_LOCATION | Personally Identifiable Information |
| Orkut field | OpenSocial field | Orkut access policy |
|---|---|---|
| Education | N/A | N/A |
| High school | SCHOOLS | Not Yet Implemented |
| College / university | SCHOOLS | Not Yet Implemented |
| Major | N/A | N/A |
| Degree | N/A | N/A |
| Year | SCHOOLS (END_DATE) | Not Yet Implemented |
| Occupation | JOBS | Not Yet Implemented |
| Industry | JOBS (FIELD) | Not Yet Implemented |
| Sub-industry | JOBS (SUB_FIELD) | Not Yet Implemented |
| Company / organization | JOBS (NAME) | Not Yet Implemented |
| Company webpage | JOBS (WEBPAGE) | Not Yet Implemented |
| Title | JOBS (TITLE) | Not Yet Implemented |
| Job description | JOBS (DESCRIPTION) | Not Yet Implemented |
| Work email | EMAILS | Personally Identifiable Information |
| Work phone | PHONE_NUMBERS | Personally Identifiable Information |
| Career skills | N/A | N/A |
| Career interests | JOB_INTERESTS | Not Yet Implemented |
| Orkut field | OpenSocial field | Orkut access policy |
|---|---|---|
| Headline | N/A | N/A |
| First thing you will notice about me | N/A | N/A |
| Height (ft/in) | BODY_TYPE (HEIGHT) | Not Yet Implemented |
| Eye color | BODY_TYPE (EYE COLOR) | Not Yet Implemented |
| Hair color | BODY_TYPE (HAIR_COLOR) | Not Yet Implemented |
| Build | BODY_TYPE (BUILD) | Not Yet Implemented |
| Body art | N/A | N/A |
| Looks | N/A | N/A |
| Best feature | N/A | N/A |
| Turn ons | TURN_ONS | Available |
| Turn offs | TURN_OFFS | Available |
| My idea of a perfect first date | N/A | N/A |
| From my past relationships I learned | N/A | N/A |
| Five things I can't live without | N/A | N/A |
| In my bedroom you will find | N/A | N/A |
| Ideal match | ROMANCE | Available |
Scrap extension applications are currently not supported on orkut.
You have completed this review of application development within an orkut environment. To continue learning about the OpenSocial API in general, you'll also want to check out the additional documentation and materials hosted at the OpenSocial API home page.