Before you start developing on-site applications, you have to make sure your development environment must be set up. This involves signing up for a developer account and adding your application to your developer profile.
Sign up for the Developer Sandbox
To develop on-site applications for Orkut, you must convert your normal Orkut account into a developer account. For better organization, you may want to set up a separate developer profile instead of using your personal Orkut account for this, but it's your choice. To convert an Orkut account to a developer account, visit the Sandbox Signup Page and fill in the required fields. After submitting the form, wait a few minutes for changes to take effect.
To test that signup was successful, try to log into the developer sandbox with your account. To do that, visit https://sandbox.orkut.com (you might want to bookmark this link) and log in normally.
If you stay in sandbox.orkut.com after login, you have successfully signed up. If you are redirected to www.orkut.com, signup has failed due to an unusual circumstance, in which case you can try to do the signup again or try again a little later.
The rest of this guide will assume you are logged into the sandbox.
Prod Sandbox: an Alternative to Sandbox
Apart from sandbox.orkut.com, we also have another environment called the Production Sandbox, which can be accessed at https://prod.sandbox.orkut.com. You may want to bookmark this link as well. The difference is that Sandbox uses the bleeding-edge latest version of the Orkut platform while Prod Sandbox uses the same version of the platform that's currently in the production environment.
In a few words: Sandbox is the future, Prod Sandbox is the present version of Orkut. This is designed so that you test your applications both in an environment that brings you the latest updates and fixes (Sandbox) and in an environment that closely approximates the current production environment (Prod Sandbox).
You should routinely check that your application is performing well on both environments to be sure that your users won't have any problems.
Important: since Sandbox runs on a very recent version the Orkut platform code which is usually still undergoing some testing and QA, it may become unstable from time to time. We believe the advantage of of having early access to the new version of the platform is worth this small (and, hopefully, infrequent) inconvenience. So, when Sandbox is not working or behaving strangely, please use Prod Sandbox instead (and let us know through one of our Community Channels).
Set up hosting for your XML
To begin your development, you have to set up your hosting service and place your XML file in a place where it's publicly visible from the Internet. If you are just starting, the starting version of your XML will probably be a placeholder, which you will fill in over time as you develop your application.
For example, a starting XML file for your on-site application could be:
<?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="Your Title Here" author="Your Name Here" author_email="your_email_here@your_domain_here.com" description="Description of your application goes here" screenshot="http://full/url/to/a/screenshot/of/your/app.png" thumbnail="http://full/url/to/a/thumbnail/of/your/app.png"> <Require feature="opensocial-0.8" /> </ModulePrefs> <Content type="html"> <![CDATA[ <br> <br> <br> <big>Hello, world!</big> ]]> </Content> </Module>
The full specification of the possible tags and fields in this XML is documented in the Gadgets API, but for the purposes of Orkut, you only need the features above. You should make sure that your application has all the required attributes: title, author, author email, description, screenshot and thumbnail as the example above illustrates. All these attributes are mandatory, so applications that omit them will be rejected during review.
So, at this point you should set up your XML file on your hosting service and it should be accessible via a public URL. For the purposes of our examples, we will use http://my.domain.here/myapp.xml.
Adding the Application to your Developer Profile
Next, you have to add the application to your developer profile in Sandbox. To do that, log in to sandbox.orkut.com with your developer profile. After logging in (and making sure the URL still says sandbox.orkut.com and not www.orkut.com), please visit the Developer Page at:
Due to how the servers redirects are set up, visiting the link above directly before logging into the sandbox will not work. You will see a 404 error instead. If that happens, please log into sandbox first using its root URL (sandbox.orkut.com), and then visit the URL above.
Likewise, you can also use Prod Sandbox (just replace sandbox.orkut.com with prod.sandbox.orkut.com in the URLs).
If the preceding steps worked correctly, what you are seeing now is the Developer Page. illustrated below. In this page, you can see a list of your applications and can perform actions on them by clicking the corresponding buttons.
The Developer Page
To add a new application to your profile, simply type its URL in the box entitled add an application by URL and click the Add button. Note that this will only add the application to your developer profile. This will not cause the application to be published or to appear anywhere else.
Important: adding your application to your developer profile is not the same as submitting your application. Adding will simply cause it to show on your developer profile so you can run it, but will not cause the review process to begin and will not publish it on the directory.
After you add the application, wait a few seconds and refresh the page, and it should now appear in the list of applications, with buttons labeled View and Submit.
Important: for efficiency reasons, what the Developer Page shows is a snapshot from a few minutes ago. Therefore, your operations may take several minutes to produce an effect on this page. If your application does not appear on this page after you add it, keep refreshing the page every few minutes until it appears.
When you see your application on the page, click the View button next to it. This will cause the application to run. At this point, if you copied our example, your application doesn't do much: it should say "Hello world".
What is your application's AppID?
One of the important pieces of information you will have to know about your application is that it has a unique numeric ID called AppID. Pay close attention to the URL on the browser when you view your application. It will typically look like the following (the numeric part will, of course, be different for you):
So, in our example, our AppID is 272186130535.
This full URL is called the application canvas URL.
The Modify/Test Cycle
Now that you have added the application to your developer profile, you are ready to start developing. This will usually involve a cycle where you make modifications to your XML, test it on Orkut, observe problems and go back to modifying your XML. It's important to emphasize that you don't need to re-add your application every time you modify it, because what Orkut knows is simply a link to your XML (the URL), it does not copy the XML itself. So if you simply modify your XML on your server and run the application again, you should see your changes.
However, there is the caching issue: since the Orkut servers cache your XML, you may not see your changes immediately. This is a very good feature for a production environment, but naturally this delay can be very disruptive to your workflow in a development environment. This is why we provide a way for you to bypass the Orkut XML cache during development. To do that, just add "&bpc=1" after your AppID on the application canvas URL (not to be confused with your XML's URL). For example:
Important: This trick only works in the development environment and only affects you. It will not cause Orkut to invalidade its cached version of your XML, so other users will still see the cached version of your XML until the cache expires (which should happen in a few hours, at most).
Important Note about Secrecy
Remember that your XML is public and open to the world, so anyone that accesses your XML's URL will be able to see its contents. Also, your developer profile can also be accessed by other users, subject to the same rules of privacy control as any other profile on Orkut. So if another developer visits your developer profile in the sandbox, they will see your applications under development. They can run them and even install them on their own profiles.
This is one of the reasons why we recommend that you set up a developer profile that's separate from your personal profile, to make it less discoverable. While that doesn't guarantee that no one will see your applications while you develop them, that will certainly be much less likely to happen.
During the course of development, it's often useful to test snippets of code on the fly in order to experiment with API calls and test that they work as expected. That is the purpose of OrkutDevBox. To install it, simply log into your developer profile and install OrkutDevBox.
OrkutDevBox: An easy way to experiment with the Orkut API
The code that we show in this guide will work directly in OrkutDevBox: you just have to copy and paste the code into the box and click "Execute". If you are using the code outside OrkutDevBox (in your application, for example), you should remove the calls to the debug.* and replace with something more suitable to your application.
Please keep in mind, however, that the code we will show you throughout this guide is only the HTML portion of the application (the part that goes between the <![CDATA[ and ]]> tags in the example XML structure we presented above. So, if you are running it in OrkutDevBox, you can use it directly, but if you are making your own application, you need to embed it into a application XML as our previous example demonstrated.
Now that we introduced the basics of how to set up an initial on-site application, we will now give you a tour of the main features of the API that allow you to access profile information, application data, post activities, send messages, communicate with remote servers and interact with the Orkut environment.
However, before we begin with actual API elements, let's discuss some common patterns that will appear throughout the code.