One
benefit of using Facebook Platform is the potential reach you have when
Facebook users share content from your app or website with their
friends. Because of the strength of a friend’s endorsement,
communication through Facebook Platform can help high-quality products
grow tremendously. This document provides an overview of the available
channels, so you can choose the ones which make the most sense for your
user experience. Unless noted, all channels will work for Websites,
mobile and Apps on Facebook.com.
Feed Dialog: Prompt Users to Publish
The recommended way to publish to the stream is with the Feed Dialog. Without requiring users to log into your application or grant any special permission, you can prompt users to publish stories about what they are doing in your application. If a user chooses to publish, the story will appear on the user’s profile and may appear to the user’s friends’ News Feeds.
Stories published from your application will include a link to your application, and can optionally include a rich attachment. Here is a basic example of how to prompt a user to publish a story:
The code above prompts the user with this dialog:
Feed Graph Object: Publish via the Graph API
There are some cases when you may want to provide a customized experience for publishing to the user's news feed. You can publish via the Graph API for users who have authorized your application and who have granted you the ‘publish_stream’ permission. The available fields are the same as the feed dialog fields. The following POST action will render the same story as in the example above.
For example, you can publish to a user's wall by issuing a POST request to
Like button
The Like button lets your users easily share interesting content from your application or website back to Facebook. Like stories appear on users’ Wall and their friends’ News Feeds.
In addition, if you specify meta information via the Open Graph protocol, your pages becomes equivalent to Facebook Pages. This means when a user clicks a Like button on your page, a connection is made between your page and the user. Your page will appear in the "Likes and Interests" section of the user's profile, and you have the ability to publish updates to the user’s News Feed.
There are two Like button implementations: XFBML and Iframe. The XFBML version is more versatile, but requires use of the JavaScript SDK.
There are two types of requests that can be sent from an app:
If you prefer to have your app send requests directly to the user (an App-generated request), you post a request to the
Once sent, new requests a user has received are visible as a counter on your application's bookmark and it also increments the counter next to the appropriate Dashboard.
When the user clicks on the bookmark to load your Canvas or Mobile Web application, we are passed two parameters in the URL querystring:
When the user accepts your request via the dashboard, we pass the request id that they are acting on via the
A good common practice for Canvas Apps is to detect if a user has any requests pending when your application loads and then prompt the user to complete the actions associated with the requests before continuing. This way users don't have to process your requests out of the context of your app. You can determining all the pending requests for a given user by accessing the
The following PHP example demonstrates how to access the pending requests for a user and then delete the requests once you have completed any associated actions:
Bookmarks
Bookmarks enable users to easily navigate back to your application from within Facebook. If your app has a Canvas URL set, a bookmark will appear in the left column of the homepage as well as on the top right of a Canvas page itself. If your app has a Mobile Web URL set, a bookmark will appear within the navigation of Facebook's iOS and Android native apps, as well as on m.facebook.com. If your app has an iOS bundle set, and your iOS app is enabled with Facebook SSO, the bookmark within Facebook's iOS app will provide distribution to your iOS native app directly.
Notifications
Notifications on Facebook are meant to provide prominent but lightweight heads-up about interesting changes to content relevant to users. Requests send from within your Canvas, Mobile Web or native mobile app may trigger a notification to users who will find it relevant.
Dashboards
Apps on Facebook.com (Canvas apps) have the opportunity to appear on one of two dashboards -- the Apps Dashboards and the Games Dashboard. Dashboards appear as bookmarked links on Facebook's homepage and shows users outstanding requests, apps they've recently used and apps their friends have recently used. The Application Directory is also accessible from the Dashboard.
Usage Stories
Many actions on Facebook are shared with friends. Similarly, a variety of feed stories may be published to share with users the popular Canvas applications their friends are using. These stories are typically targeted at people who have not used your application to provide a way for new users to discover your application.
Search
When over 10 people have used your application, it will automatically be submitted to Facebook's search index. This allows new users who have heard of your application to find it, and gives existing users a quick way to get back to your app again.
News Feed
The News Feed is shown immediately to users upon logging into Facebook, making it core to the Facebook experience. There are several ways you can publish content to the stream: Feed Dialog, Feed Graph object and Like Button.Feed Dialog: Prompt Users to Publish
The recommended way to publish to the stream is with the Feed Dialog. Without requiring users to log into your application or grant any special permission, you can prompt users to publish stories about what they are doing in your application. If a user chooses to publish, the story will appear on the user’s profile and may appear to the user’s friends’ News Feeds.
Stories published from your application will include a link to your application, and can optionally include a rich attachment. Here is a basic example of how to prompt a user to publish a story:
<html>
<head>
<title>My Great Website</title>
</head>
<body>
<div id="fb-root"></div>
<script src="http://connect.facebook.net/en_US/all.js">
</script>
<script>
FB.init({
appId:'YOUR_APP_ID', cookie:true,
status:true, xfbml:true
});
FB.ui({ method: 'feed',
message: 'Facebook for Websites is super-cool'});
</script>
</body>
</html>
The code above prompts the user with this dialog:
Feed Graph Object: Publish via the Graph API
There are some cases when you may want to provide a customized experience for publishing to the user's news feed. You can publish via the Graph API for users who have authorized your application and who have granted you the ‘publish_stream’ permission. The available fields are the same as the feed dialog fields. The following POST action will render the same story as in the example above.
For example, you can publish to a user's wall by issuing a POST request to
https://graph.facebook.com/<username>/feed:curl -F 'access_token=...' \
-F 'message=Facebook for Websites is super-cool.' \
https://graph.facebook.com/<username>/feed
Like button
The Like button lets your users easily share interesting content from your application or website back to Facebook. Like stories appear on users’ Wall and their friends’ News Feeds.
In addition, if you specify meta information via the Open Graph protocol, your pages becomes equivalent to Facebook Pages. This means when a user clicks a Like button on your page, a connection is made between your page and the user. Your page will appear in the "Likes and Interests" section of the user's profile, and you have the ability to publish updates to the user’s News Feed.
There are two Like button implementations: XFBML and Iframe. The XFBML version is more versatile, but requires use of the JavaScript SDK.
Requests
If you have built a Canvas or Mobile Web application, Requests are a great way to enable users to invite their friends to use your app. Requests integrate with Facebook notifications and dashboards, ensuring that a user will see the requests from their friends whenever they are on Facebook. You can also use requests to have a user notify their friends to take a specific action in your app, such as accepting a gift or helping the user complete a quest.There are two types of requests that can be sent from an app:
- User-generated requests: These requests are confirmed by a user’s explicit action on a request dialog. These requests update the bookmark count for the recipient. You send requests by using the Request Dialog.
- App-generated requests: These requests can be initiated and sent only to users who have authorized your app. Developers can send these requests using the Graph API. You should use these requests to update the bookmark count to encourage a user to re-engage in the app (e.g., your friend finished her move in a game and it’s now your turn).
<html>
<head>
<title>My Great Canvas app</title>
</head>
<body>
<div id="fb-root"></div>
<script src="http://connect.facebook.net/en_US/all.js">
</script>
<script>
FB.init({
appId:'YOUR_APP_ID', cookie:true,
status:true, xfbml:true
});
FB.ui({ method: 'apprequests',
message: 'Here is a new Requests dialog...'});
</script>
</body>
</html>
If you prefer to have your app send requests directly to the user (an App-generated request), you post a request to the
apprequest connection of the User Graph object:<?php
$app_id = YOUR_APP_ID;
$app_secret = YOUR_APP_SECRET;
$token_url = "https://graph.facebook.com/oauth/access_token?" .
"client_id=" . $app_id .
"&client_secret=" . $app_secret .
"&grant_type=client_credentials";
$app_access_token = file_get_contents($token_url);
$user_id = THE_CURRENT_USER_ID;
$apprequest_url ="https://graph.facebook.com/" .
$user_id .
"/apprequests?message='INSERT_UT8_STRING_MSG'" .
"&data='INSERT_STRING_DATA'&" .
$app_access_token . "&method=post";
$result = file_get_contents($apprequest_url);
echo("App Request sent?", $result);
?>
Once sent, new requests a user has received are visible as a counter on your application's bookmark and it also increments the counter next to the appropriate Dashboard.
When the user clicks on the bookmark to load your Canvas or Mobile Web application, we are passed two parameters in the URL querystring:
ref and count (i.e. ref=bookmarks&count=1). The ref parameter contains the value "bookmark". The count parameter will contain the total count set on the bookmark.When the user accepts your request via the dashboard, we pass the request id that they are acting on via the
request_ids parameter.
A good common practice for Canvas Apps is to detect if a user has any requests pending when your application loads and then prompt the user to complete the actions associated with the requests before continuing. This way users don't have to process your requests out of the context of your app. You can determining all the pending requests for a given user by accessing the
apprequests connection of the User Object in the Graph API.The following PHP example demonstrates how to access the pending requests for a user and then delete the requests once you have completed any associated actions:
<?php
$app_id = 'YOUR_APP_ID';
$app_secret = 'YOUR_APP_SECRET';
$token_url = "https://graph.facebook.com/oauth/access_token?" .
"client_id=" . $app_id .
"&client_secret=" . $app_secret .
"&grant_type=client_credentials";
$access_token = file_get_contents($token_url);
$signed_request = $_REQUEST["signed_request"];
list($encoded_sig, $payload) = explode('.', $signed_request, 2);
$data = json_decode(base64_decode(strtr($payload, '-_', '+/')), true);
$user_id = $data["user_id"];
//Get all app requests for user
$request_url ="https://graph.facebook.com/" .
$user_id .
"/apprequests?" .
$access_token;
$requests = file_get_contents($request_url);
//Print all outstanding app requests
echo '<pre>';
print_r($requests);
echo '</pre>';
//Process and delete app requests
$data = json_decode($requests);
foreach($data->data as $item) {
$id = $item->id;
$delete_url = "https://graph.facebook.com/" .
$id . "?" . $access_token;
$delete_url = $delete_url . "&method=delete";
$result = file_get_contents($delete_url);
echo("Requests deleted? " . $result);
}
?>
Automatic Channels
To drive more traffic to Facebook Platform applications and websites, in addition to the channels above, we enable some distribution automatically as people use your applications. You do not need to do anything extra to enable this distribution. Each automatic channel is designed to help engage users and our algorithms help surface the best content for each user. As Facebook evolves as a product, expect these channels to change and improve. The current automatic channels include:Bookmarks
Bookmarks enable users to easily navigate back to your application from within Facebook. If your app has a Canvas URL set, a bookmark will appear in the left column of the homepage as well as on the top right of a Canvas page itself. If your app has a Mobile Web URL set, a bookmark will appear within the navigation of Facebook's iOS and Android native apps, as well as on m.facebook.com. If your app has an iOS bundle set, and your iOS app is enabled with Facebook SSO, the bookmark within Facebook's iOS app will provide distribution to your iOS native app directly.
Notifications
Notifications on Facebook are meant to provide prominent but lightweight heads-up about interesting changes to content relevant to users. Requests send from within your Canvas, Mobile Web or native mobile app may trigger a notification to users who will find it relevant.
Dashboards
Apps on Facebook.com (Canvas apps) have the opportunity to appear on one of two dashboards -- the Apps Dashboards and the Games Dashboard. Dashboards appear as bookmarked links on Facebook's homepage and shows users outstanding requests, apps they've recently used and apps their friends have recently used. The Application Directory is also accessible from the Dashboard.
Usage Stories
Many actions on Facebook are shared with friends. Similarly, a variety of feed stories may be published to share with users the popular Canvas applications their friends are using. These stories are typically targeted at people who have not used your application to provide a way for new users to discover your application.
Search
When over 10 people have used your application, it will automatically be submitted to Facebook's search index. This allows new users who have heard of your application to find it, and gives existing users a quick way to get back to your app again.
No comments:
Post a Comment