App Notifications

App Notifications are generic one-to-one or one-to-many (new feature) communications from an application to a user or users of that application. In addition to providing a framework for communicating general application state messages, App Notifications also provide the user with multiple options for executing an application-specific action.

App Notifications should not be used for application install requests, as that is handled by the App Invite message type.

The purpose of this document is to:

• Define how an App Notification is raised using OpenSocial.
• Define how a batch App Notification can be sent to multiple Users with an OAuth REST endpoint.
• Create and send an App Notification with a simple Hello World-style application.
• Create an advanced App Notification application.

Please join in on the discussion in the Notifications Forum.

Requirements - Environment:

• If invoking from the OpenSocial Container, it must be OpenSocial version 0.8.
• If invoking through the REST API, the container can be either OpenSocial 0.7 or 0.8.

To see whether your OpenSocial application is version 0.8:

• On the MyApps page, find your OpenSocial App, then click the Edit Details link to open the Edit App Information page.
• Scroll to the bottom of the Edit App Information page, to the section called "Other Settings". The dropdown selector labeled "Preferred OpenSocial Version" indicates the version of OpenSocial that your app uses.

How Notifications are Raised

There are two primary ways to send App Notifications to users:

• OpenSocial Container (0.8)
• OAuth REST Endpoint (Server-to-Server; see POST /v1/applications/applicationId/notifications)

Here is a comparison of the two methods:

Use Cases

Playing a Turn Based Game

Tom, a huge chess buff, has just installed the latest Chess app for MySpace. After installing the game, he quickly sends an app invite over to Bob who promptly installs the game and Tom initiates a new game between the two of them. Tom makes his opening move and the game indicates that it's now Bob's turn.

Bob is on his User Home Page and sees that he has a New App Notification indicator. He clicks it and is taken directly to the App Notifications sub folder in the Mail Center where he sees he has a new Chess notification. The notification includes a picture of Tom and informs Bob that it's now his turn to move. Bob clicks the Make My Move button. The notification is automatically deleted and he is taken to the App Canvas where he can determine his next move.

In this case, the Developer created the chess game using the OpenSocial Application Builder. The source code is hosted on MySpace. Only a single User needs to be notified when a player makes a move. The OpenSocial method of App Notifications is the ideal way to send this type of notification.

What if the Developer built a massive multi-player game where large groups of people compete with each other? In this case, the OAuth signed REST endpoint is the ideal method for an application to send batch App Notifications to multiple recipients.

OpenSocial Container

The following will raise a notification in an OpenSocial 0.8 application:

global_viewerId

The recipient of the App Notification.

notification

Includes the body and action button parameters.

raiseNotificationCallback

The response (OpenSocial Callback function) to the notification.

Follow the steps in the next section to create a simple application that will send a notification to yourself. The application source code contains additional documentation.

OAuth REST Endpoint

The majority of this document is focused on the OpenSocial Container method of sending App Notifications. To learn more about how to send server-to-server batch App Notifications, please read the MySpace REST Resources documentation for the App Notifications REST endpoint:

POST /v1/applications/applicationId/notifications

Create a Simple Application to Send an App Notification

This section shows how to code a simple notification application using the OpenSocial Container method. The next section of this document walks you through the sample application.

STEP 1: Set Up a New Application

Follow steps 1-4 of the process to create an application for the Application Platform. Title the application Notification Sample.

STEP 2: Provide the Source of the Application

1. Click the Edit App Source tab of the Application Builder. The default sub-tab shown is for the Canvas Surface.
   
   
2. Copy the application source code from the example below:
   
   EXAMPLE: Notification Sample Source Code

   <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.2.6/jquery.min.js"></script>
   <h1>Notifications Sample</h1>
   <div id="flash" style="width: 50%; height: 50px; background-color: #6795C6; display:none;"></div>
   <form id="notification_form">
   <input type="button" value="Send a notification to myself!" onclick="raiseNotification();" />
   </form>
   <script type="text/javascript">
   var global_viewerId;
   function getViewerCallback(dataResponse) {
       var viewerResp = dataResponse.get('viewer');
       if (!viewerResp.hadError()){
           var viewerData = viewerResp.getData();
           global_viewerId = viewerData.getId().replace("myspace.com:","");
       }
   }
   $(document).ready(function(){
       // determine if app is installed
       if(opensocial.hasPermission(opensocial.Permission.VIEWER)) {
           // fetch the viewer
           var req = opensocial.newDataRequest();
           req.add(req.newFetchPersonRequest(opensocial.IdSpec.PersonId.VIEWER), 'viewer');
           req.send(getViewerCallback);
       }
   }
   );
   function raiseNotification() {
       // create the list of buttons
       var firstButton = MyOpenSpace.newNotificationButton(MyOpenSpace.NotificationButton.UrlTypes.CANVAS, "Click on me!", null);
       var buttons = [firstButton];
       // create the notification parameters
       var param = {
       };
       param[MyOpenSpace.Notification.Field.BODY] = "Notification sent at " +  (new Date().toString());
       param[MyOpenSpace.Notification.Field.BUTTONS] = buttons;
       var notification = MyOpenSpace.newNotification(param);
       // raise the notification
       MyOpenSpace.requestCreateNotification(global_viewerId, notification, raiseNotificationCallback);
   }
   function raiseNotificationCallback(response) {
       if (response.getErrorCode() == opensocial.ResponseItem.Error.UNAUTHORIZED) {
           $("#flash").show();
           $("#flash").html("Unauthorized");
       }
       if(!response.hadError()){
           $("#flash").show()
           $("#flash").html("Success!");
       }
   }
   </script>

3. Paste the source code into the HTML/ JavaScript Source window for the Canvas Surface.
   
   
   
4. Click the Save Application Source button. A SUCCESS message displays at the top of the page.
   
   
   At this point, the Notification Sample application is saved, but unpublished.
   
   

STEP 3: Add the Application to a Developer Profile

Use the following process to add the application while logged into a Developer account:

1. Click the My Apps button in the navigation bar to go to My Applications.
   
   
   
2. Click the logo to the left of the application's name to go the Application Profile.
   
   
   
3. Click the Add the App button towards the top-right of the Application Profile.
   
   
   
4. Click the Add button on the window that appears with options for the installation of the application.
   
   
   

How the "Simple" Sample Application Works

Note: There is a known bug that may require a Developer to start a new browser session prior to using the Beta Sample Application for the first time. This bug will be addressed before the full release of App Notifications.

By clicking on the application's icon in My Apps, the application's Canvas page appears.

1. Click on the Send a notification to myself! button.
   
   The button text is customizable.




2. The notification sent by the application appears in the Mail Center.
   
   
   The above is generated by the raiseNotification() function:

   function raiseNotification() {
       // create the list of buttons
       var firstButton = MyOpenSpace.newNotificationButton(MyOpenSpace.NotificationButton.UrlTypes.CANVAS, "Click on me!", null);
       var buttons = [firstButton];
       // create the notification parameters
       var param = {
       };
       param[MyOpenSpace.Notification.Field.BODY] = "Notification sent at " +  (new Date().toString());
       param[MyOpenSpace.Notification.Field.BUTTONS] = buttons;
       var notification = MyOpenSpace.newNotification(param);
       // raise the notification
       MyOpenSpace.requestCreateNotification(global_viewerId, notification, raiseNotificationCallback);
   }

   MyOpenSpace.requestCreateNotification contains the following:

   • global_viewerId
   • notification - The message body and option buttons.

   
   

3. Click on the Click on me! button.
   
   
   
4. Button features:
   • Parameters can be passed back to the application from the button.
   • The button text is customizable.

   Clicking on the button takes the user to the application's Canvas page.
   

   
   
   

One potential use for this type of functionality would be for a game. Essentially, a game of Chess could be created where a player makes a move, thus triggering an App Notification to be sent to the other player to make a move.

Create an Advanced Notifications Sample Application

This section shows how to code an advanced sample notification application using the OpenSocial Container method. The next section of the document walks you through how the application works.

This sample application demonstrates:

• Customizing the notification body.
• Customizing the buttons.
• Attaching a photo of the sender.
• Passing app parameters through to the canvas page.
• Reading app parameters if they were passed in.

STEP 1: Set Up a New Application

Follow steps 1-4 of the process to create an application for the Application Platform. Title the application Advanced Notification Sample.

STEP 2: Provide the Source of the Application

1. Click the Edit App Source tab of the Application Builder.
   
   
2. Copy the application source code from the example below:
   
   EXAMPLE: Advanced Notifications Sample Source Code

   <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.2.6/jquery.min.js"></script>
   <style type="text/css">
   	body { font-family: Verdana; font-size: 10pt;}
   	input, textarea { padding: 5px; margin: 5px; font-family: Verdana; vertical-align:middle; }
   	fieldset { width: 250px; text-align: center; }
   	h1 { font-size: 14pt; }
   	.flash { width: 100%; height: 50px; display:none; }
   </style>
   </li></ol>
   <h1>Advanced Notifications Sample</h1>
    
   <div id="action" class="flash" style="background-color: magenta; color:white;"></div>
   <div id="flash" class="flash" style="background-color: #6795C6;"></div>
    
   <form id="notification_form">
   	<fieldset>
   	<textarea id="note" name="note" rows="3" cols="20">Send a personal note!</textarea><br />
   	<input type="checkbox" id="include_picture" name="include_picture" checked="checked" /><label for="include_picture">Include a picture of myself</label><br />
   	<input type="button" id="poke_me_button" name="poke_me_button" value="Poke Me" onclick="sendPoke();" />
   		<input type="button" id="hug_me_button" name="hug_me_button" value="Hug Me" onclick="sendHug();" />
   	</fieldset>
   </form>
    
   <p>
   	This sample app demonstrates:
   	<ul>
   		<li>Customizing the notification body</li>
   		<li>Customizing the buttons</li>
   		<li>Attaching a photo of the sender</li>
   		<li>Passing app parameters through to the canvas page</li>
   		<li>Reading app parameters if they were passed in</li>
   	</ul>
   </p>
   <script type="text/javascript">
   	var global_viewerId;
    
   	$(document).ready(function(){
   		// determine if app is installed
   		if(opensocial.hasPermission(opensocial.Permission.VIEWER)) {
   			global_viewerId = gadgets.views.getParams().viewerId;
   		}
    
   		// show the last action that was performed from the appParams
   		var action = gadgets.views.getParams()["action"];
    
   		if(action != null && action.length > 0) {
   			$("#action").show()
               $("#action").html("So you just got a " + action + ", right?");
   			$("#note").text("Thanks for the " + action + ". Let us be friends for life.");
   		}
   	});
    
   	function sendAction(bodyText, buttonText, appParams) {
   		// create the list of buttons 
   		var firstButton = MyOpenSpace.newNotificationButton(MyOpenSpace.NotificationButton.UrlTypes.CANVAS, 
   			buttonText, // dynamic button text
   			appParams); // app parameters to pass to the canvas page
    		var buttons = [firstButton];
    
   		// create the notification parameters
   		var param = {};
   		param[MyOpenSpace.Notification.Field.BODY] = bodyText; 
   		param[MyOpenSpace.Notification.Field.BUTTONS] = buttons;
   		var notification = MyOpenSpace.newNotification(param);
    
   		// attach the picture
   		var mediaItemArray = [];
   		if( $("#include_picture").is(":checked") ) {
   			mediaItemArray.push(opensocial.newMediaItem("", MyOpenSpace.MediaItemHelper.PROFILE_PICTURE));
   		}
   		if(mediaItemArray.length > 0) {
   			param[MyOpenSpace.Notification.Field.MEDIA_ITEMS] = mediaItemArray;
   		}
    
   	    // raise the notification
   		MyOpenSpace.requestCreateNotification(global_viewerId, notification, raiseNotificationCallback); 		
   	}
    
   	function sendPoke() {
   		var bodyText = "You have been POKED!";
   		// add the personal note
   		bodyText += " " + $("#note").val();
   		var buttonText = "Poke back!";
   		// this is a JSON object
   		var appParams =  {"action":"poke"};
   		sendAction(bodyText, buttonText, appParams);
   	}
    
   	function sendHug() {
   		var bodyText = "You have been HUGGED!";
   		// add the personal note
   		bodyText += " " + $("#note").val();
   		var buttonText = "Hug back!";
   		var appParams = {"action":"hug"};
   		sendAction(bodyText, buttonText, appParams);
   	}
    
   	function raiseNotificationCallback(response) {
   		if (response.getErrorCode() == opensocial.ResponseItem.Error.UNAUTHORIZED) {
   			$("#flash").show();
               $("#flash").html("Unauthorized");
           }
    
           if(!response.hadError()){
   			$("#flash").show()
               $("#flash").html("Success!");
           }
   	}
   </script>

3. Paste the source code into the HTML/ JavaScript Source window for the Canvas Surface.
   
   
   
4. Click the Save Application Source button. A SUCCESS message displays at the top of the page.
   
   
   At this point, the Notification Sample application is saved, but unpublished.
   
   

STEP 3: Add the Application to a Developer Profile

Use the following process to add the application while logged into a Developer account:

1. Click the My Apps button in the navigation bar to go to My Applications.
   
   
   
2. Click the logo to the left of the application's name to go the Application Profile.
   
   
   
3. Click the Add the App button towards the top-right of the Application Profile.
   
   
   
4. Click the Add button on the window that appears with options for the installation of the application.
   
   
   

How the "Advanced" Sample Application Works

Note: There is a known bug that may require a Developer to start a new browser session prior to using the Beta Advanced Sample Application for the first time. This bug will be addressed before the full release of App Notifications.

By clicking on the application's icon in MyApps, the application's Canvas page appears.

Send a Notification

1. Click on the Poke Me button.
   
   
   The button text is customizable. A Success message is displayed:
   
   
   




2. The notification sent by the application appears in the Mail Center.
   
   
   
3. Click on the Poke back! button.
   
   
   
4. Button features:
   • Parameters can be passed back to the application from the button.
   • The button text is customizable.

   Clicking on the button takes the user to the application's Canvas page.
   

   
   
   

Take a moment to try out various combinations of the other options available such as "Hug Me" and deselecting the photo checkbox for other results.

Action Buttons

Behavior:

• When clicked, the page will redirect to either the Application Canvas or the Application Profile. Once clicked and redirected, the notification will be deleted from the list in the User's Mail Center.
• Action buttons are limited to redirecting to the application's profile page or the associated app canvas page.

Key elements:

• Customized label of up to 20 characters.
• Developers can pass any number of query string arguments to Application Canvas URL.

Media Items

A media item can be a MySpace image, either a profile image or an album photo.

Note:

• External images are not allowed.
• Media items per notification: 1 item (maximum).

Example: Snippit from the Advanced Notifications Sample Source Code

// attach the picture
		var mediaItemArray = [];
		if( $("#include_picture").is(":checked") ) {
			mediaItemArray.push(opensocial.newMediaItem("", MyOpenSpace.MediaItemHelper.PROFILE_PICTURE));
		}
		if(mediaItemArray.length > 0) {
			param[MyOpenSpace.Notification.Field.MEDIA_ITEMS] = mediaItemArray;
		}

Restrictions

The following are some of the current restrictions to App Notifications:

• Cultures supported: en-US only for launch.
• Supported URLs: friend's profile page and Canvas URL.
• Visible characters for message body: 1 - 150 characters (message body cannot be blank).
• Body parameters must be included when computing the signature, but should be taken out of the POST URL.
• App Notifications can only be received by Users of the app.
• App Notifications will expire after 7 days.
• Users will only see the 5 most recent notifications per app.
• Container notification calls can accept up to 10 recipients at a time.
• REST notification calls can accept up to 1000 recipients at a time.