The App Accelerator allows you to customize your friend invitations and News Feed stories for Facebook and Bebo.

Boring vs. Interesting News Feed Story

Table of Contents

Viral Settings Tab

The Viral Settings tab is where you customize your friend invitations and News Feed stories.

Viral Settings Screenshot The custom friend invites and News Feed stories that you set up in the Viral Settings Tab will make use of the newsfeed special values described below.

News Feed Special Values

Widgetbox offers various special values for use within custom invitations and News Feed stories. The syntax: ${some.value}. The values:

Parameter Meaning
fbapp.addLink URL to the "Add This App" page.
fbapp.canvasPage URL to canvas page, where widget is displayed.
fbapp.managePage URL of manage page, where profile owner can edit widget.
fbapp.profilePage URL to the current profile page.
fbapp.apiKey The app's API key.
fbapp.loggedInUser The ID of the logged in Facebook user.
fbapp.appOwnerId The ID of the owner of the current profile.
fbapp.thumbnail URL of the base widget's thumbnail.
fbapp.randomTermOfEndearment Chooses randomly from a set of lighthearted, informal terms of endearment. Examples: dude, bro, homie.
fbapp.randomTermMeaningConfigured Chooses randomly from a set of lighthearted, informal terms synonymous with "configured". Examples: pimped out, tricked out, polished up.
widget.id The internal Widgetbox ID of the Facebook application.
widget.name The name of the application as set in Widgetbox.

Example:
Say you want a News Feed story saying "It rocks. Get it now!". And the "Get it now!" links to the app's installation page in Facebook. It would look like this:

It rocks. <a href="${fbapp.addLink}">Get it now!</a>

Notifications API

Widgetbox provides a Javascript and Flash API that you can use inside your widget to:
  • Send stories to the Facebook News Feed.
  • Send events to your app's profile box.

This API can be used in your existing Flash and HTML/Javascript widgets. It will not break the widget when the widget is used outside of Facebook.

Function Description
WbxAppWidget.getFbSigUser Get the id of the logged in user.
Inputs: None
Returns: The id of the logged in user viewing the app.
WbxAppWidget.getAppOwnerId Get the id of the app owner.
Inputs: None
Returns: The id of the owner of the app being viewed.
WbxAppWidget.goToAppOwnerProfile Call this to cause the user's browser to navigate to the owner's profile page.
Inputs: None
Returns: Nothing
WbxAppWidget.updateCallback Define this function to execute when the call to update() returns.
Inputs:
     obj:XMLHttpResponse
Returns: Nothing
WbxAppWidget.update Called when you want to process the following actions/updates. This is generally the last call in your update code.
Inputs: None
Returns: Nothing
WbxAppWidget.sendActionToProfile Updates the users profile with FBML.
Inputs:
     headerFBML:String - Displays above all the actions.
     footerFBML:String - Displays below all the actions.
     actionFBML:String - FBML for one action to be added to the profile.
     maxShown:int - The max number of actions displayed on the profile?
Returns: Nothing
WbxAppWidget.sendActionToFeed Updates the user's minifeed with FBML.
Inputs:
     feedTitleFBML:String - FBML string for the title of the feed entry.
     feedContentFBML:String - FBML string for the content of the feed entry.
     feedImages:String - Up to 4 URLs to images (comma separated)
                  Facebook automatically resizes images to 75px/75px
Returns: Nothing
WbxAppWidget.updateAnnouncementRef Updates the space atop of your widget with an annoucement.
Inputs:
     fbml:String - FBML defining the announcement to post
Returns: Nothing

News Feed Example:
If you have a game widget, you could send a News Feed story after the game is played:

API News Feed Example

Profile Box Example:
You can also post events to your app's profile:

API Profile Example

API Limitations:
Flash widgets can only use this API on the canvas page. This is because Facebook doesn't allow Flash on the profile to access Javascript.

Hello World Example The following example is of a Magic 8 Ball Widget. When clicked, it:

  1. Displays an answer to the user.
  2. Sends a Facebook News Feed story about the answer.
  3. Modifies the app's profilebox to show that the user got an answer.
<!-- This Magic 8 Ball is just a DIV that says "Click me!" -->
<div id="eightball" onClick="askQuestion()">Click for answer.</div>

<script type="text/javascript">

//
// Display answer to question
//
function askQuestion() {
	// The answers
	var answers = new Array(3)
	answers[0] = "Yes.";
	answers[1] = "No.";
	answers[2] = "Maybe.";
	
	// Pick an answer
	var answerIndex = Math.round(Math.random() * (answers.length -1));
	var answer = answers[answerIndex];

	// Display answer to user
	document.getElementById("eightball").innerHTML = answer;

	// Send notifications to Facebook
	sendFacebookNotifications(answer);
}

//
// Send notifications to Facebook
//
function sendFacebookNotifications(answer) {
    var debug = true;
    try {
        //
        // Outputs debugging on a successful sending of the News Feed.
        //
        if (debug) {
            parent.WbxAppWidget.updateCallback = function(obj) {
                alert("done: " + obj.responseText);
            }
        }

        //
        // Create action for the Facebook News Feed
	// The feed will read something like: "Pam has been answered:  "Yes." 
	// Get your own answer!"
        //
        var feedTitle = "has been answered: \"" + answer + "\"";
        var feedBody = "<strong>Get your answer!</strong>";
        var feedImages = "http://domain.com/someImage.png";
        parent.WbxAppWidget.sendActionToFeed(feedTitle, feedBody, feedImages);

        //
        // Create action for the profile owner's profilebox
        // The profilebox will now contain something like:  
        // [Pam's image] Pam has been answered: "Yes!"
	//
	var uid = parent.WbxAppWidget.getFbSigUser();  // ID of the current user
        var fbml += "<fb:profile-pic uid=\"" + uid + "\"/>";
        fbml += "<fb:name uid=\""+ uid +"\" />";
        fbml += " has been answered: " + answer;

	// The max # actions to display in the profilebox.  
	// After the widget sends 5 actions, the oldest is dropped
	var maxActions = 5; 
		
	// Displays above all the actions
        var header = "<hr />";

	// Displays below all the actions
        var footer = ""; 

        parent.WbxAppWidget.sendActionToProfile(header, footer, fbml, maxActions);
       
        //
        // Actually send both actions
        //
        parent.WbxAppWidget.update();

    } catch (e) {
        if (debug) {
            alert("Error sending Facebook notification: " + e);
        }
    }
}
</script>

Example of Using API in Flash
The notifications API can be used in a Flash widget via ActionScript. Here's a sample widget that puts captions on photos:

Useful Facebook Tools

Some useful Facebook tools for working with newsfeed stories:

Feed Preview Console Facebook's console for testing your feeds.

Feed API Doc Facebook's API documentation for publishActionOfUser, the event that Widgetbox sends out on application installs and edits.

Useful Newsfeed Button Images

One useful technique for newsfeed stories is to use a button image. Example:

Newsfeed Story With Button

Here are some buttons you can use: