Building OpenSocial Apps
A Field Guide to Working with the MySpace Platform
Upper Saddle River, NJ • Boston • Indianapolis • San Francisco
New York • Toronto • Montreal • London • Munich • Paris • Madrid
Capetown • Sydney • Tokyo • Singapore • Mexico City
Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and the publisher was aware of a trademark claim, the designations have been printed with initial capital letters or in all capitals.
The screenshots and other depictions of myspace.com contained in this book may not accurately represent myspace.com as it exists today or in the future, including without limitation with respect to any policies, technical specs or product design.
The authors and publisher have taken care in the preparation of this book, but make no expressed or implied warranty of any kind and assume no responsibility for errors or omissions. No liability is assumed for incidental or consequential damages in connection with or arising out of the use of the information or programs contained herein.
The publisher offers excellent discounts on this book when ordered in quantity for bulk purchases or special sales, which may include electronic versions and/or custom covers and content particular to your business, training goals, marketing focus, and branding interests. For more information, please contact:
U.S. Corporate and Government Sales
(800) 382-3419
[email protected]
For sales outside the United States, please contact:
International Sales
[email protected]
Visit us on the Web: informit.com/aw
Editor-in-Chief
Mark L. Taub
Acquisitions Editor
Trina MacDonald
Development Editor
Songlin Qiu
Managing Editor
John Fuller
Full-Service Production Manager
Julie B. Nahil
Project Management
diacriTech LLC
Copy Editor
Barbara Wood
Indexer
Jack Lewis
Proofreader
George Seki
Technical Reviewers
Cassie Doll
Bess Ho
Benjamin Schupak
Book Designer
Gary Adair
Compositor
diacriTech LLC
Library of Congress Cataloging-in-Publication Data
Cole, Chris, 1974-
Building OpenSocial apps : a field guide to working with the
MySpace platform/Chris Cole, Chad Russell, Jessica Whyte.
p. cm.
Includes bibliographical references and index.
ISBN-13: 978-0-321-61906-8 (pbk. : alk. paper)
ISBN-10: 0-321-61906-4 (pbk. : alk. paper)
1. Entertainment computing. 2. Internet programming. 3. MySpace.com. 4. OpenSocial.
5. Web site development. 6. Social networks—Computer network resources.
7. Application program interfaces (Computer software) I. Russell, Chad. II. Whyte, Jessica. III. Title.
QA76.9.E57C65 2010
006.7'54—dc22
2009032342
Copyright © 2010 Pearson Education, Inc.
All rights reserved. Printed in the United States of America. This publication is protected by copyright, and permission must be obtained from the publisher prior to any prohibited reproduction, storage in a retrieval system, or transmission in any form or by any means, electronic, mechanical, photocopying, recording, or likewise. For information regarding permissions, write to:
Pearson Education, Inc
Rights and Contracts Department
501 Boylston Street, Suite 900
Boston, MA 02116
Fax: (617) 671-3447
ISBN-13: 978-0-321-61906-8
ISBN-10: 0-321-61906-4
Text printed in the United States on recycled paper at RR Donnelley in Crawfordsville, Indiana.
First printing, October 2009
This book is dedicated to my ever-suffering wife, Kristen, and our two crazy and wonderful children, Darien and Reece. Thanks for working overtime with the kids, baby.
—Chris Cole
To the reader, we hope this book serves you well.
—Chad Russell and Jessica Whyte
Contents at a Glance
I: Building Your First MySpace Application
3 Getting Additional MySpace Data
5 Communication and Viral Features
6 Mashups and External Server Communications
7 Flushing and Fleshing: Expanding Your App and Person-to-Person Game Play
10 OSML, Gadgets, and the Data Pipeline
11 Advanced OSML: Templates, Internationalization, and View Navigation
III: Growth and How to Deal with It
13 Performance, Scaling, and Security
15 Porting Your App to OpenSocial 0.9
Contents
I: Building Your First MySpace Application
Creating the App—“Hello World”
Step 1: Sign Up for a Developer Account
Step 3: Enter Your Source Code
Installing and Running Your App
The Two Concepts That Every Developer Should Know
Basic Concepts: Owner and Viewer
Basic Concepts: Permissions for Accessing MySpace Data
Accessing Profile Information Using the opensocial.Person Object
Getting More than Just the Default Profile Data
opensocial.DataResponse and opensocial.ResponseItem (aka, Using MySpace User Data)
3 Getting Additional MySpace Data
How to Fetch a Friend List and Make Use of the Data
Refactoring to Build a Local App Data Store
Building the Cookie Jacker App
5 Communication and Viral Features
Using opensocial.requestShareApp to Spread Your App to Other Users
Writing the requestShareApp Code
Using opensocial.requestSendMessage to Send Messages and Communications
Writing the requestSendMessage Code
Callback in requestSendMessage
Getting Your App Listed on the Friend Updates with opensocial.requestCreateActivity Basics
Defining opensocial.requestCreateActivity
Using the Template System to Create Activities
Using the Template Editor to Create Templates
Using opensocial.requestCreateActivity
6 Mashups and External Server Communications
Communicating with External Servers
Adding a Feed Reader to Our App
Overview of gadgets.io.makeRequest
Setup and Design of the Feed Reader
Secure Communication with Signed makeRequest
7 Flushing and Fleshing: Expanding Your App and Person-to-Person Game Play
Supporting Person-to-Person Game Play
Adding P2P Game Play Support in the Game Engine
Advantages and Disadvantages of App Data P2P Play
Testing Your OAuth Implementation Locally
Spicing Up the Home and Profile Surfaces Using makeRequest
How a REST Web Service Is Addressed
Setting Up an External Iframe App
Friends Web Service and Paging
Using the 0.7 Container for postTo
The Friends Response from the REST API
10 OSML, Gadgets, and the Data Pipeline
Adding a Second Surface to the Gadget
Declaring and Using Basic Data
In-Network versus Out-of-Network Data
Data Tags os:ViewerRequest and os:OwnerRequest
JavaScript Blocks in OSML Apps
OpenSocial Markup Language (OSML)
Putting It Together: OSML Tic-Tac-Toe
11 Advanced OSML: Templates, Internationalization, and View Navigation
Defining and Using a Tag Template
Adding Targeted Content with myspace:RenderRequest
Displaying JSON Results with a Data Listener
Internationalization and Message Bundles
Creating Our First Message Bundle
Creating Translations of the Message Bundle
Including Translations in an App and Testing
III: Growth and How to Deal with It
What’s Allowed, or Why So Many Apps Get Rejected
Making Changes to a Live App (Multiple Versions)
Changing the App Profile/Landing Page
Event Handling—Installs and Uninstalls
Suspension and Deletion of Your App
13 Performance, Scaling, and Security
Performance and Responsiveness
What Is Responsive Performance and What Is Scale Performance?
Responsive OpenSocial App Performance Guidelines
App Guidelines for Internet-Scale Performance
Rule 2: Test OpenSocial DataResponse Objects for Errors
Rule 3: Provide Time-Outs and Error Flow
Rule 4: Don’t Assume That Weird Error Was an Anomaly
Using MySpace to Promote Your App
App Profile, or Bringing Out the Bling
Interviews with Successful App Developers
Dave Westwood: BuddyPoke (www.myspace.com/buddypoke)
Eugene Park: Flixster (www.myspace.com/flixstermovies)
Tom Kincaid: TK’s Apps (www.myspace.com/tomsapps)
Dan Yue: Playdom (www.myspace.com/playdom)
15 Porting Your App to OpenSocial 0.9
Updating Albums and Media Items
Foreword
The Internet is constantly evolving, with vast arrays of information on every topic growing at a remarkable pace. Google’s 1998 search index had only 26 million Web pages; a decade later it recognizes more than 1 trillion URLs. With so much information, we need a new set of tools to make sense of the Internet. The transition is from a strict focus on informational content, to being able to take advantage of our context, our relationships, and our activities.
Enter the social Web, a relatively new twist to the Internet, which is being built up by social networks, portals, and even more traditional businesses. The “Open Stack” is a set of specifications being developed by grass-roots communities all over the world, enabling developers to create new products and services enhanced by user-specific data. The Open Stack includes specifications such as OAuth, which provides secure access to data; OpenID, a global identity standard; and OpenSocial, a common API for building applications. These specifications are becoming the underlying infrastructure for the social Web, weaving a social fabric throughout the Web.
OpenSocial enables developers to learn a single core programming model that can be applied to all “OpenSocial containers,” those sites that support the OpenSocial specification. With standards-based tools, including a JavaScript-based gadget API, a REST-based data access API, lightweight storage capabilities, and access to common viral channels, developers can build inside those containers as well as create applications for mobile phones or other sites. In late 2009, less than two years after its introduction, more than 50 sites have implemented support for the OpenSocial specification. In aggregate, these sites provide developers with access to more than 750 million users all over the world.
By taking advantage of the OpenSocial API and the information available in this book, you will have a great opportunity to reach a lot of users. For example, you’ll find the OpenSocial API supported by many major sites that span the globe: Yahoo!, iGoogle, Xiaonei and 51.com (China), Mixi (Japan), orkut (Brazil), Netlog (Europe), and, of course, MySpace. Beyond that, OpenSocial is also supported by more productivity-oriented sites like LinkedIn and by Fortune 100 companies as diverse as IBM and Lockheed Martin.
With this book, you can quickly get up and running with OpenSocial on MySpace, and you’ll be poised to leverage that experience to reach users on other sites as well. The in-depth programming examples provide a good introduction to the design options available when building with the OpenSocial API, and the code is open source for ease of use and future reference. Additionally, the MySpace Platform tips sprinkled throughout will help you avoid common mistakes and understand the intricacies of their platform policies. Getting a feel for how social platforms operate will be valuable as you continue to explore the wide world of OpenSocial.
OpenSocial is constantly evolving, just like the rest of the Internet. The OpenSocial specification is managed through an open process where anyone can contribute their ideas to influence the next version of the specification and help move the social Web forward. Since its creation, there have been several significant revisions to the specification, introducing some new programming methodologies and improvements that make it easier for new developers to start using OpenSocial. As you’re getting into the OpenSocial API, be sure to contribute back to the OpenSocial.org community your ideas on how to improve the specification.
It’s open. It’s social. It’s up to you.
—Dan Peterson, president, OpenSocial Foundation
San Francisco, California
August 2009
Acknowledgments
Chris Cole: I’d like to acknowledge the great team at MySpace that helped build the developer platform and all the people who’ve contributed to refining the OpenSocial specification. Compromise is hard, but a bad spec would have been even harder.
Chad Russell: Thank you to Dan Peterson, for being a resource and agreeing to write our Foreword. And, of course, a big thanks to our technical editors, Bess Ho, Cassie Doll, and Ben Schupak, who all found a number of issues that would otherwise slipped through the cracks.
Jessica Whyte: Thank you to Trina MacDonald and Olivia Basegio at Addison-Wesley for your support. I’d also like to acknowledge Tom Kincaid, Eugene Park, Dave Westwood, Dan Yue, Jon Nguyen, and Katie Simpkins for taking the time to answer all of my (many) questions about the platform.
About the Authors
Chris Cole is a software architect at MySpace and is a major contributor to building the MySpace Open Platform and keeping it committed to OpenSocial. He’s been a core contributor to the OpenSocial 0.9 specification and is the primary architect and implementer of OSML (OpenSocial Markup Language) on the MySpace platform. Chris has been in software for fifteen years and has spent much of that time riding the various waves of the Internet and pushing the boundaries of the Web.
Chad Russell is the lead developer on the MySpace OpenSocial team. He knows the OpenSocial spec front to back, in addition to every tip, trick, and nuance of the MySpace platform itself. Chad holds an engineering degree from the University of Toronto and currently resides in Seattle, Washington.
Jessica Whyte has worked for several years as a journalist, most recently with Journalists for Human Rights, and is currently a graduate student at the University of Washington, studying Human-Centered Design and Engineering. She lives in Seattle with her husband and coauthor, Chad Russell.
Introduction
Welcome to the wonderful world of social apps. You are about to enter—or have already entered—a fast-paced and treacherous landscape that can be exciting, frustrating, intellectually challenging—and yes, it can even be pretty profitable.
We hope to be your guide through both the hidden pitfalls and the soaring peaks. There is much to gain from this exciting new market; social apps have been around for only a few years, after all. Many successful apps have yet to be created and then discovered by the millions upon millions of passionate MySpace users.
In this book we’ll start from scratch and walk you through the entire process of building apps, from signing up as a developer all the way to building highly complex social apps that can scale out to thousands of users. We have extensive experience on the MySpace Development Platform (MDP), from building apps to helping build the platform itself. We’ll point out the many idiosyncrasies and quirks of the platform, as well as the many ways to squeeze out a little better performance by making a few tweaks to your existing apps.
Throughout this book we’ll demonstrate best practices and show lots of sample code as we take a step-by-step approach to app development. Starting with a simple “Hello World”–style app, we’ll add functionality until we have a fully built, feature-rich app. We’ll fetch data on the current user, get the user’s friend list and photos, and parse all the data that comes back to display it on the screen. We’ll send app invitations and notifications to help spark viral growth and send requests back to Web services running on a third-party server in order to process and store data. Finally, and possibly most important, we’ll show you how to make money developing apps using ads and micropayments.
When it comes to developing social apps on the MySpace platform, the sky is the limit. As of this writing, the most popular app on MySpace has more than 13 million installs. Maybe your app will be the next big thing. All it takes is a good idea and a little bit of knowledge. If you provide the former, we can provide the latter.
Our hope is that this book is accessible both to experienced social app developers and to those developers who have only heard about it on the news. To that end, if you’re standing in the technology section of your local bookstore reading this, and you have a bit of computer programming knowledge mixed in with some free time and curiosity, this book is for you.
We’ll start from scratch in this introduction to ramp you up on MySpace and OpenSocial. For those who already have apps up and running out in the wild, this book is also for you, as we’ll dig pretty deeply into the platform a little later on. You may be familiar with the ideas and terms we introduce here, so feel free to skip ahead a bit. (Check out the section on tools, though!)
How to Read This Book
There are a couple of ways to read this book. If you’re an experienced app developer, you can use this as a reference book. The index will direct you to specific topics, where you can consult the various tables, sample code, and tips. Or, if you need to learn a new aspect of the platform, you can skip directly to that chapter and dive right in.
If you’re not an experienced app developer, we suggest you start from the beginning. We’ll start off with a “Hello World”–style app in Chapter 1 and add to it in each subsequent chapter. By the time the app is completed, you’ll have a broad knowledge base of the entire platform. We then branch out into some advanced topics to take you a step further.
Assumptions Made by the Authors
This is not a book about how to code in JavaScript or Python or any other language. We will try to follow good practice in our sample code throughout the book, and we’ll point out a few interesting tidbits along the way, but that’s all. This is a book on how to write OpenSocial apps on MySpace.
To that end, we assume the following:
• You have basic knowledge of computer programming in general. Maybe you work at a software company and write PHP every day, or you’ve taken a few programming classes, or you’ve taught yourself by constructing your own Web page.
• You have basic knowledge of JavaScript or are willing to pick up the basics. We’re not talking advanced stuff here, just the basics like calling functions, giving values to variables, and that kind of thing.
With all that said, let’s get started!
What Is MySpace?
Ah, MySpace. Land of lost friends now found, hours wasted, and every band on the planet, large and small. Oh, and spam. Lots of spam. You can find the site here: www.myspace.com.
MySpace is a social network. You sign up for free and you’re given a “profile”; the Profile page is a Web page that others can view and you can edit. On your Profile you can add information about yourself, pick a display name, and upload a picture. Others who view your Profile can leave comments for all to see. The cascading style sheets (CSS) of Profile pages can also be edited, so individuals can alter the styles of the page to “bling” out their Profiles in ways both beautiful and stunningly, shockingly bad.
In addition to a Profile page, you are given a Home page (shown in Figure I.1), which only you can see. It contains your notifications, “You have new mail!” and the like, along with various links to other parts of the site and updates from your friends.
Figure I.1 A MySpace Home page.
It is the friend aspect that truly makes a social network. The idea is simple; you sign up and are assigned a single solitary friend: Tom, one of the cofounders of MySpace. Through various means, such as searching, browsing, or having a robot guess “People You May Know,” you can find new friends and add them to your list. Having other users as friends grants you certain privileges to their information. You may have access to their Profiles even if they’re set to “Private”; you see their updates on your feed; and, most important to us, friends can interact inside apps.
That’s MySpace in a nutshell. You sign up, bling out your Profile, add some friends, upload some pictures, install some apps, and send some messages.
What Is OpenSocial?
OpenSocial is a specification that defines how Web sites allow third-party apps to run on their sites. That means many things. For example, OpenSocial defines what information a Web site can and must expose for each of its users. It defines a client-side JavaScript runtime environment with a set of APIs that describe how to fetch and update that user data. This environment is commonly called an “OpenSocial container.” Likewise, it defines a set of server-side APIs that manipulate the same data but can be called from a server running your language of choice, such as PHP. It also defines a markup language called OSML that can be used to draw your app and fetch data.
This specification was started by the folks at Google, along with the help of MySpace, Hi5, and other initial early adopters. Maintenance of the spec has since been passed to the OpenSocial Foundation and the community. That means any implementers, such as MySpace, Orkut, and LinkedIn, app developers, or really anyone at all can suggest modifications to the spec and participate in setting the direction. Those modifications are then voted on in a public forum and either brought into the spec (found at http://opensocial.org) or rejected.
Any site on the Web is free to implement the OpenSocial spec. The idea is that when a site becomes OpenSocial-compliant, it is able to run almost any of the thousands of apps already created using OpenSocial. If a site has correctly implemented all the various APIs, an app running on MySpace should run just as well anywhere else. That’s the theory, anyway. In practice there are differences, some small, some large, between the various OpenSocial implementers, which can make it tricky to maintain an app on multiple sites.
What Is the MySpace Open Platform?
The MySpace Open Platform (sometimes called MySpace Developer Platform or MDP) is simply MySpace’s implementation of the OpenSocial spec. MDP is a blanket term that covers how to sign up as a developer, how to update your app, and how to actually run your app.
MySpace tries its best (we really do) to fully implement the OpenSocial spec, but there are bound to be some inconsistencies. Most of these inconsistencies are small, but we’ll cover them as they come up throughout this book. MySpace has also implemented some features that aren’t in the spec; we’ll cover these as well.
More than on any other OpenSocial-enabled site, developing apps on the MySpace platform gives you access to a huge number of users and potential customers. As of this writing, MySpace has more than 130 million monthly active users and is growing every day. Forty-five million of those users have installed apps. To give you an idea of the demographics, 53% of app users are female, with an average age of 18 to 24. That is a very marketable demographic to have at your fingertips.
What Tools Will You Need?
Here’s where we finally start to get a little technical. After many long nights spent debugging why that callback wasn’t being fired or where that stupid 401 unauthorized error was coming from, we’ve found some really useful tools that will make your life easier. Let’s repeat that for effect: These tools will make your life easier.
Browsers
First, a quick note on browsers. Install Firefox right now. Go to www.firefox.com. In our opinion it’s best to develop on Firefox, get your app running the way you like it, then worry about running it in Internet Explorer (IE) as well. Developing on the Web is still an “IE and everyone else” process. You get an app working in Firefox, and that means it will probably work just fine in Safari, Chrome, and Opera. Then you can bang your head for a few hours (days?) fighting floating divs and onclick handlers in IE.
Firebug
Firebug is the main reason Firefox is the Web developer’s browser of choice. Firebug is an incredible tool for all Web developers, and every single one of us should install this Firefox extension. It’s even more useful because all JavaScript “alert” and “confirm” functions are blocked by the OpenSocial container, so it really is the best way to debug. Get it at http://getfirebug.com.
Firebug has many useful functions. We won’t go into every last one here, but there are a few that we use every single day. To follow along at home, install the Firebug extension, restart Firefox, navigate to your Web page of choice, then click Tools → Firebug → Open Firebug. The Firebug window will open at the bottom of the browser.
Inspect
The Inspect feature allows you to view and edit CSS and inline style on any HTML element currently on the page. Click Inspect at the top left of the Firebug window and hover your cursor over a Web page. You’ll see that the various HTML elements become highlighted. Clicking on one will show you the HTML markup of that element in the left pane and its current style in the right pane. You can then add a style or modify the existing style on the fly.
This is very useful for building up user interface (UI) elements quickly. Instead of making a change, saving a file, uploading it, and reloading the page in a browser, you can just edit the style very quickly and try different values. When you find what works in Firebug, you can make one edit to your page and it should be good to go.
Console
The Console tab shows you a couple of useful things. The first useful bit of information is that any and all JavaScript errors are displayed here, with a description of the error along with its file name and line number. The second is that any outgoing Web service requests are shown here. You’ll be able to view the exact outgoing URL, any parameters and headers sent along, and the response from the server. As most MySpace requests are sent as outgoing Web service requests, this is an invaluable debugging tool. You’ll be able to see if the correct parameters were appended to the request, and you won’t have to output the response onto a div on the UI to see if you got the correct response or some sort of error.
Script
The Script tab is your debugger. You can load any HTML or JavaScript file into the left pane by selecting the file in the drop-down above that pane. You can then set breakpoints at any line with a green line number. In the right pane you can set watches on variables, view the current stack, and manipulate the breakpoints you’ve set.
With the Watch window you can interrogate any object by simply typing the variable name into the New Watch Expression bar. Doing so displays the object’s current state and value. But you can also directly manipulate objects. Say you wanted to see what would happen if a Boolean variable were true instead of false; you can set that directly by entering something like varName = true into the Watch Expression bar.
Need to figure out what’s causing that JavaScript error? Set a breakpoint on that line and inspect the objects and variables that are causing the issue. Need to figure out exactly what the response looks like from a request to the MySpace servers? Set a breakpoint in your callback function and add the response object to your Watch list (see this in action in Figure I.2).
Figure I.2 Interrogating the response from MySpace’s servers using Firebug.
There are countless other things you can do with the Script tab, and Firebug in general, but we can’t discuss them all here. We hope we’ve sold you on its usefulness and that you’ll discover the many great features it has to offer.
Fiddler
Fiddler is a free tool that watches all the traffic coming into and out of your computer. With respect to building apps, it is useful mainly if you decide to use the server APIs as opposed to the JavaScript APIs. We’ll discuss what that means later on in the book, but keep this tool in mind when you get there. To give you a little bit of a preview, you’ll be sending requests for data to MySpace, and those requests need to be sent using an authentication scheme. Using the authentication scheme is tricky, but Fiddler will help you see exactly what you’re sending to MySpace and exactly what MySpace is sending back to you. Get it here: www.fiddler2.com.
One other thing to note is that Fiddler works natively in Internet Explorer but not Firefox. If you do a little bit of Googling, you can get it up and running in both browsers.