The new Developer Page is up, and with that, the application development and submission flow is now considerably different (and, we hope, easier to understand).
New Application Development/Submission/Review Workflow
By btco, 2011-02-13
0. Before we start...
Warning #0: The new developer page is working but please bear with us as we polish some rough edges that still exist. Please read this guide thoroughly before using the new page. The workarounds and known issues are highlighted in red.
Warning #1: Much of the information here overrides what is currently written in other documentation posted in
code.google.com/apis/orkut. If you see an inconsistency, please follow what we say here instead of what you see in the older documentation.
1. Sandbox signup
If this is your first time developing an application (or if you are using a new profile you just created and you never developed an application with it), the first thing you have to do is
sign up for the orkut Developer Sandbox. If you've already done that some time in your life with this profile, you don't need to do this again. If you already had signed up for sandbox in the old development/submission/review workflow, you do not need to sign up again. It's the same sandbox, it's just a different process!
[ Tip ] Use a separate Developer Profile
If you have a personal profile on orkut, please use a separate profile for application development. This will make your life much easier and more organized!
[ Tip ] If sandbox is ever offline...
Yes, sandbox is offline sometimes because it's very new code and sometimes it fails or becomes a little slow. If that's the case, please use Prod Sandbox as an alternative (
prod.sandbox.orkut.com). You don't have to sign up for prod sandbox separately (your sandbox signup works for prod sandbox too). Prod sandbox is a sandbox environment that's closer to the production environment, since it runs the same binary and has similar flags.
2. Sign into sandbox
Sign into sandbox by going to
http://sandbox.orkut.com. After signing in, notice if the URL stays as "
sandbox.orkut.com". If it reverts back to
www.orkut.com, something is wrong -- you probably didn't sign up for the sandbox! If you did sign up for sandbox and you are still getting thrown back into
www.orkut.com, it's a bug: please complain at the forum.
3. Access the New Developer Page
The new developer page is located at
http://sandbox.orkut.com/Main#Developer. There is no link to it from the interface (there will be soon), so bookmark this URL or memorize it to have it handy. However,
you can only access it AFTER logging into sandbox (step 2). If you try to go there directly without logging in first, you will get a 404 error as if the page didn't exist.
If this is your first time developing an orkut app, please make sure to read at least the
OpenSocial Tutorial for Orkut, but please bear in mind that the app testing/submission workflow written there is
out of date (use this one instead).
4. Add your application to your developer profile.
To do this, just type the URL to its XML in the box that appears at the top of the page (the one that says "add an application by URL") and clicking the "add" button. After that, you have to reload the page in order for it to work. If you don't do that, your newly added app will not show up. Just to be clear, this step only adds the application to your developer profile so you can run it and test it, this does NOT cause the application to be published. After adding your application here, it will show in your list of applications and you can run it.
5. Test and debug your app.
Now it's time to test and debug until your app is clean, shiny and ready to hit the shelves. To run your application, simply click the View button under its entry in the Developer Page. Once the app is running, you will notice that the URL changes to something like
The highlighed part above is your AppID, a number that identifies your application. If you ever have a complaint or doubt about your application, always mention this AppID, otherwise we won't be able to do anything for you.
6. My changes aren't showing!
If you modify your app and the modification is not showing: this is because we keep an internal cache of assets and XML. However, this can be a pain when developing, since you want to see the results of your modifications immediately. In this case, please append the "&bpc=1" parameter to your URL to force a cache bypass. When you do that, you should be able to see your changes immediately:
7. Polish your XML.
Make sure your XML is well formed and has all the necessary parameters. Your XML should look something like:
<?xml version="1.0" encoding="UTF-8"?>
<Module>
<ModulePrefs title="Your App Title Here"
author="Your name here (or your company's name)"
description="A description of your app here"
<Require feature="opensocial-0.8" />
<Locale lang="en" country="us" />
</ModulePrefs>
<Content type="html" preferred_width="900">
<![CDATA[
<!--ALm6fM2Ja1zhd/onBrNuxUWETQAoxE1lyg3WP0pqtO1OfnRFc8e4yPgDuW0oC9l8w1gTqJRoZbx0oQThry4Uo5uBZ87rtmTdLrIpCx0CRuc9pkS3NemA/xDaL2WvlEIDP/wEJXOzNre8-->
...your content goes here...
]]>
</Content>
</Module>
The funny-looking <!-- ALm6.... --> string is the Verification Token. You'll get it in the next step (verification), it's okay not to have it at first.
Naturally, the Locale element should be as appropriate for your application, my example uses US English. Please include all the locales of the users who might reasonably want to play your app. This is because of a current bug (Known Issue K04), which causes users whose locales are not compatible with the application's locale to experience weird bugs (they might see "app not whitelisted" while running the app, and will not be able to post newsfeeds).
Always include all this information: author name, e-mail, description, thumbnail, screenshot. If your XML is missing any of the required parameters, your application will fail review.
8. Submitting your app.
When you're done editing your application and you're ready to show it to the world, you have to Submit it. To do that, look up your application in the Developer Page and click the corresponding "Submit" button. You will then be shown a Verification Token that looks like <!-- Aafoiwejfaowijw..... --> (it's longer than that). You must now copy that token and paste into your application's XML. This is done to verify that you are indeed the owner of the application (we presume that if you can write an arbitrary string to it, then it must be because you own it). Please make sure to copy the whole token! It ends in "-->".
This verification token MUST go into the <Content> tag of your XML. You you put it anywhere else, the verification service won't find it. And do use <![CDATA[, otherwise there might be strange escaping problems that will prevent your application from being verified. Also, DO NOT split the token into multiple lines! Leave it all on the same line:
<Content>
<![CDATA[
<!--ALm6fM2hd...........-->
...your content here...
]]>
</Content>
After you've added this string to your XML, test that it's really being served with that string. Open a different browser and point it to your XML's URL, for example, and check that it's showing the XML with the verification token. If you see the plain XML without the verification token, please take action to correct your server's configuration! It is probably caching what it shouldn't.
After checking that the new XML with the verification token is indeed being served, you are ready to click the "Verify" button on the Developer Page, which appears right under the Verification Token.
After doing that, the page will display a Consumer Key and a Consumer Secret. Write down those values!!! Copy them and paste them to a place of your choice. WARNING: These values will never be shown again and cannot be recovered, so do not lose them!
9. My app is now 'pending'. Now what?
If the previous step ended successfully, then your app must now be showing as 'pending', in orange, on the page. This means that your application was submitted and is awaiting orkut's review. Now you must wait until our team reviews your application (the piece of software on our side that does this is called AppReviewer).
Normally, the review process should take 48 hours or so, but currently (as of 2011-02-13), we're having some trouble with AppReviewer so we're running it manually every week or so. Therefore, you might have to wait up to a week to get your application reviewed.
Q: I refreshed the page and my app is no longer pending! It came back to the "testing" state!!! Was it rejected? Is it a bug? Do I have to submit again??
A: Calm down! Please see Known Issue #K10 in the forum (if it's not there, it's because I haven't posted it yet -- I'll do so after posting this guide). Summarizing: the Developer Page displays a state that's a few minutes old. So recent status changes (from testing to featured, for example) may not appear on the page for several minutes (yes, even though it did seem to change at first -- that was smoke and mirrors on the interface side!).
10. How long is considered a "normal" time to wait for an approval?
Currently, up to 1 week is normal. As listed in the Known Issues, AppReviewer is currently offline and we're running it manually every week or so. Therefore, it may take up to a week for AppReviewer to take a first look at your application, at which point you will receive an e-mail indicating whether your application was approved or not.
11. I've been waiting for 23 years, 8 months and 3 days for an approval. Is that normal?
If you find yourself waiting for more than 2 weeks and never got an e-mail from AppReviewer, something is very wrong. In this case, please check your spam box -- maybe your e-mail filtering backend doesn't like our friendly AppReviewer messages and sends them to your spam folder. If the AppReviewer e-mail is not there, please complain to us on the forum, and provide your appID so we can look into it and tell you what's going on.
12. I got an AppReviewer error. Now what?
You have to fix your application and submit it again. The message will tell you what's wrong with your application, and all you have to do is fix it. Okay, that's lie. The message is often a bit obscure. We're fixing that, I promise! Now, if the error is in a URL that your app uses, it's probably because we're having trouble fetching the asset from that URL. Please check that it's spelled right. If it's spelled right and you can access the asset yourself, then maybe your content provider is not reliable -- it may work for you now, but when we try to pull it, the server might be overloaded and giving us a "temporary error".
Also, please take a look at "Common causes for AppReviewer failures" below.
Now, if the URL error is on some strange internal orkut URL, something to do with a "gmodules" proxy, in that case it's our fault -- your app failed review because AppReviewer couldn't access our own internal cache. In the (increasingly unlikely) case that happens to you, please complain and try to submit your app again.
13. What are common causes for AppReviewer failures?
0. XML syntax errors. Your syntax is bad, or you are missing one of the required parameters (author name, author e-mail, screenshot, thumbnail, etc). Refer to our XML example a few pages above.
1. HTTP errors: your resources can't be fetched. Sure they may work now for you, but perhaps they are only available some of the time, and were offline when we tried to fetch them. Please switch to a reliable hosting service.
2. You are using a registered trademark in your app. You can't use "Google", "orkut", or any other trademark you don't own. So if your app is using any unauthorized trademarks, you will not get approval (and the error message won't really explain why).
3. Your app has objectionable content.
4. Your app redirects the user to another app or page, or does any other funny or suspicious trick with the browser. You are not allowed to do that.
5. Your app has a security breach which allows it to be exploited maliciously.
6. You are violating one or more of our Developer Guidelines. We have automated tests that verify compliance to many of them, and we manually review several cases.
7. A bug in AppReviewer. If you believe you've found an AppReviewer bug, we'd like to know about it!
14. Success \o/
If you fix all the problems in your application (if there were any), you'll eventually get a message from AppReviewer saying your app was successfully reviewed and published. Congratulations!
IMPORTANT: It may take up to 48 hours for our DB to replicate to the production environment, so you may have to wait up to 48h after approval to see your app go live. During this period, users will not be able to add or run your application.
15. What if I have to update my application once it's live?
Your updates are immediate! There is no need to resubmit. Once you change your XML, the changes are automatically live. However, due to caching, some assets (notably graphics) may take a while to go stale and refresh (a few hours, typically). So, if it all possible (and this is a general recommendation for any Web development), use a different resource name if your resource's content has changed. That may help solve the caching issues. In any event, our internal asset cache should normally refresh its version of your assets in at most 24 hours.
WARNING: our review process runs continually, so if you introduce a change in your application that causes it to fail review (say, for instance, you broke the XML's syntax or changed the screenshot to something that's causing an HTTP error), it may be taken down and rejected. If it is taken down and rejected, you will have to fix the problem and, in this case, submit it again, as it will not be automatically reviewed again after a rejection.
[ Tip ] Use version-specific assets
One of the recommeded ways to do application updates is to always use version-specific assets. For example, on version 1 of your application, your screenshot would be hosted at http://.../myapp/v1/screenshot.jpg. Likewise, any other assets would all be located at the "v1" directory... for example, your theme song that your app plays could go into http://.../myapp/v1/theme.mp3. Your XML would be http://.../myapp/v1/app.xml. But that's NOT the one you submit to orkut -- instead, make a link (or copy) in http://.../myapp/latest.xml. THAT's the one you submit (notice that this one is not tied to any version -- it's by definition the LATEST launched version).
Now, when developing an update, all you have to do is create a new directory on your server, "v2", starting out with a copy from "v1". You can update your screenshot, theme song and any other assets there (careful to update the URL's to say v2 instead of v1), including the XML, which now lives at http://.../myapp/v2/app.xml.
When you want to launch version 2, all you have to do is replace the link (or copy) so that http://.../myapp/latest.xml now points to (or contains a copy of) http://.../myapp/v2/app.xml.
Since the asset URL's are all different, caching at any point in the pipeline won't be an issue (the new never-seen v2 assets will be fetched), and your new version will launch as a whole, without having to wait for assets to individually refresh on the cache.
Also, if you ever want to test a specific past version of your app, all you have to do is go into the sandbox and load the path to the specific version's XML and play it. It will come with that version's specific assets, so doing that, you obtain the effect of "going back in time" and seeing a specific version of your app. Twenty years from now when you're in version 1492, you might even be able to offer your users the ability to play the "vintage" version 1 of your app :)