MySpace Developer Platform

A Place For Developers
From MySpace Open Platform: Documentation Wiki

Create an OpenSocial Application

Jump to: navigation, search
Content > MySpace Apps > OpenSocial > Basics

Learn how to create an application with error checking, additional functionality and other features.

Contents

Definitions

  • Container – JavaScript that surrounds an application.
  • Owner – the User that installs an application.
  • Viewer – the User that is looking at the application.

Note: Owners can also be Viewers.

Initialize the Code

Note: If you are starting from the MySpace workflow page titled Create App, follow the path associated with the Application Platform flow (on the left hand side). Click the button at the bottom labeled "CreateOn-site App". This is the path for creating an OpenSocial application.

To start an application, use the init() function.

Example Code: Initializing an Application -- OpenSocial Equivalent of main() 

<script type="text/javascript">
function init()
{
    //This is your entry point.
}
init();
</script>



Request Data from the API

The requestDataFromAPI() function requests data from the API.

When DataRequest.send({callback}) is called, requestDataFromAPI() responds with:

  • Owner Friend data
  • Owner Profile data

To ensure optimal performance:

  1. Construct the DataRequest object.
  2. Create RequestItem objects to add to the DataRequest object.
  3. Dispatch the request.

Example Code: Request for Owner Friends and Owner Profile Data 

function requestDataFromAPI()
{
 
    //1: Create the DataRequest.
    var container = opensocial.Container.get();
    var dataRequest = container.newDataRequest();
 
    //2: Prepare RequestItems to be added to the DataRequest
    var friendRequest = dataRequest.newFetchPeopleRequest(opensocial.DataRequest.Group.OWNER_FRIENDS);
    var personRequest = dataRequest.newFetchPersonRequest(opensocial.DataRequest.PersonId.OWNER);
 
    //3: Add the RequestItems to the DataRequest.
    dataRequest.add(friendRequest);
    dataRequest.add(personRequest);
 
    //4: Send it along, and expect a function called responseCallback(dataResponse) to be executed when it's done.
    dataRequest.send(responseCallback);
 
}



Notice the special parameters passed to newFetchPeopleRequest and newFetchPersonRequest methods.

Request the friends of the Viewing User: 

var friendRequest = dataRequest.newFetchPeopleRequest(opensocial.DataRequest.Group.VIEWER_FRIENDS);;



Request the friends of the Owning User: 

var friendRequest = dataRequest.newFetchPeopleRequest(opensocial.DataRequest.Group.VIEWER_FRIENDS);;



The OpenSocial convention for a constant parameter is an upper-case variable. See the opensocialreference.js file for definitions of these constants.

The definition of the opensocial.DataRequest.Group object used as a parameter for the previous friendRequest example: 

var friendRequest = dataRequest.newFetchPeopleRequest(opensocial.DataRequest.Group.OWNER_FRIENDS);



Receive Data Back from the API

An example of the callback assigned to the previous request:

Example: DataResponse callback for owner and owner's friends 

function responseCallback(data)
{
    var friends = data.get(opensocial.DataRequest.Group.OWNER_FRIENDS).getData();
    var owner = data.get(opensocial.DataRequest.PersonId.OWNER).getData();
}



Error Checking

An example to check for errors using hadError:

Example: Check Error on Response 

function responseCallback(data)
{
    var errorHappened = data.hadError();
    if(!errorHappened)
    {
        var friends = data.get(opensocial.DataRequest.Group.OWNER_FRIENDS).getData();
        var owner = data.get(opensocial.DataRequest.PersonId.OWNER).getData();
    }
    else
    {
        alert("Hello, I am an incredibly obnoxious box informing the user they had an error.");
    }
}



Items to remember:

  • The data parameter passed into the responseCallback method is an instance of opensocial.DataResponse.
  • DataResponse contains a set of ResponseItem instances, one for each of the results.
  • ResponseItem has the same type of error checking as DataResponse.

The following example uses all of the available error trapping capabilities of OpenSocial.

Example: Response Callback with Full Error Checking 

function responseCallback(data)
{
    //The below variables is now an opensocial.ResponseItem instance. var friendResponse = data.get(opensocial.DataRequest.Group.OWNER_FRIENDS);
    if(friendResponse.hadError())
    {
        switch(friendResponse.getErrorCode())
        {
            case opensocial.ResponseItem.Error.INTERNAL_ERROR : //There was an error on the server.  
            break;
            case opensocial.ResponseItem.Error.UNAUTHORIZED : //There was a permissions issue: the app is not allowed to show the data. 
            break;
            case opensocial.ResponseItem.Error.BAD_REQUEST : //There was an error in the Container. 
            break;
            case opensocial.ResponseItem.Error.FORBIDDEN : //The Container was unable to contact the server. 
            break;
            case opensocial.ResponseItem.Error.NOT_IMPLEMENTED : //MySpace did not implement this particular OpenSocial interface. 
            break;
        }
        //You don't have to write your own error messages--the message will be provided to you by the Container. alert("Unable to get friends: " + friendResponse.getErrorMessage());
    }
}



Privacy Checking

The MySpace Open Platform uses standard OpenSocial error codes to let an application know when privacy rules are broken.

For example:

  1. User A has an application installed that requests VIEWER_FRIENDS.
  2. User B visits User A's profile. Both users are not friends on MySpace.
  3. Privacy rules are invoked to prevent User A's application from harvesting User B's entire list of friends.

If User A and User B both have the same application installed, or they are friends, VIEWER_FRIENDS will be available.

Code needs to gracefully fail if User B is blocked. Below is an example of code that specifically probes for whether or not the user is authorized to see VIEWER_FRIENDS:

Example: dataResponse -- Check for Authorization Issues 

//Assume a DataRequest was issued for the VIEWER_FRIENDS
function dataLoadCallback(dataResponse) {
    if (dataResponse.hadError())
    {
        var friendsResponse = dataResponse.get(opensocial.DataRequest.Group.VIEWER_FRIENDS);
        if(friendsResponse.getErrorCode() == opensocial.ResponseItem.Error.UNAUTHORIZED)
        {
            alert("The app is not authorized to get the viewer's friends in this case.");
        }
    }
    else
    {
        var viewerData = dataResponse.get(opensocial.DataRequest.PersonId.VIEWER).getData();
        var viewerName = viewerData.getField(opensocial.Person.Field.NAME);
        //do more app specific stuff
    }
}



Requesting Data from Your Site

Integrate an external Web site's functionality with MySpace, use OpenSocial's asynchronous makeRequest method.

The following example grabs text from a URL.

Example Application: makeRequest -- Simple URL Grab 

<script>
function init()
{
    var url = "http://www.w3c.com";
    os_params = {
    }
    ;
    gadgets.io.makeRequest(url, makeRequest_Callback, os_params);
    function makeRequest_Callback(data){
        var responseText = data.responseText;
        alert(responseText);
    }
}
init();
</script>

It is common to grab JSON or XML. Below is a simple call to evaluate the response into a JSON object:

Example Application: makeRequest -- Simple URL grab with JSON 

<script>
function init()
{
    var url = "http://www.w3c.com/json";
    os_params = {
    }
    ;
    gadgets.io.makeRequest(url, makeRequest_Callback, os_params);
    function makeRequest_Callback(data){
        var responseText = data.responseText;
        var jsonedResponseObject = data.responseText.evalJSON();
    }
}
init();
</script>



Next Steps

Learn about the MySpace Specific Extensions on OpenSocial.

Retrieved from "http://wiki.developer.myspace.com/index.php?title=Create_an_OpenSocial_Application"