Mobile Web App Tutorial
Mobile web apps are built using web technologies including HTML5, Javascript and CSS. You can build once and deploy everywhere, including on iPhone, iPad and Android.
This tutorial guides you through the key steps to build, test, and launch social integration in your mobile web app. It's a comprehensive walk through building basic social features into your web app. The code used in this tutorial is available below in the sample apps section as "Hello World". On your phone or tablet, you can play with the live
sample at www.facebookmobileweb.com/hello/.
iOS and Android tablets and phones are supported. Users interact with your web apps on m.facebook.com, as well as within the Facebook native app on iOS (iPhone, iPad, and iPod).
If you'd like jump right into a demo that showcases what's possible, visit www.facebookmobileweb.com/hackbook/ on your phone or tablet.
Getting started
1. Register your web app
2. Implement the Facebook SDK
3. Log the user in
Adding social context and payments
4. Use the Graph API
5. Integrate with Social Channels
6. Add payments
Deploying your social mobile web app
7. Display your app properly on devices
8. Test your integration
9. Set icons
Getting Started
Step 1: Register your web app
To begin integrating with Facebook Platform, go to Apps on the dev site, click 'Create New App', and then enter your app's basic information. If you already have a Facebook app and you're building a mobile version of your app, do not create a new app. Instead, use the same App ID so users don't have to authorize your app again.
Now, you should be looking at your new app's settings page. Fill in 'App Domain', then click on 'Mobile Web' under 'Select how your app integrates with Facebook'. Under that, fill in your 'Mobile Web URL'. The resulting form should look similar to the screenshot below.
Now submit the updated settings. You app is now set up and you’re ready to begin integrating with Facebook!
Note that if you want to hide your web app from friends until you launch (from search, News Feed, Requests and other Social Channel), you'll need to enabled Sandbox Mode. You can find this setting on the Advanced tab.
Step 2: Implement the Facebook SDK
Mobile web apps use the same API and dialog calls as apps on Facebook.com and websites on the desktop.
First, create a new file called 'index.html' and paste this HTML boilerplate code into the file. Then, upload it to your web server.
<html>
<head>
<title>Hello World</title>
</head>
<body>
</body>
</html>
First, we need to enable the Facebook Javascript SDK in order to start integrating social functionality into your mobile web app. This is the same SDK you use when integrating with your website or an app on Facebook.com.
To add the SDK, paste the following code into <body></body> section of your index.html.
<div id="fb-root"></div>
<script>
(function() {
var e = document.createElement('script'); e.async = true;
e.src = document.location.protocol + '//connect.facebook.net/en_US/all.js';
document.getElementById('fb-root').appendChild(e);
}());
</script>
The above code will load the JavaScript SDK asynchronously so that the user will be able to access your web app as quickly as possible.
Now that you have the SDK added to your website, you can start creating a social experience.
Step 3: Log the user in
The next step is to get the Facebook user’s access token in order to personalize the experience for them. If your app only wishes to use the News Feed for Request dialog and doesn't require the user to login you can skip directly to Social Channels.
Login before landing on your web app
Authenticated referrals is a new authentication mode for Facebook applications that ensures all referral traffic from Facebook to your application is already connected with Facebook. This means that visitors arrive on your app already "logged in" and with whatever data permissions (email, likes and interests, etc.) you requested in the Required Permissions section. You can use this information to provide a personalized experience for Facebook visitors the moment they land on your app, and if you are using open graph, users will already have authorized your app to publish open graph actions on your behalf.
Authenticated referrals works by showing the app permissions dialog on Facebook (immediately after clicking on any links to your app) so you should be sure to configure this dialog to properly show off the best features of your app, and what actions will be added to their profile. Once they are authenticated, they are sent directly to your Mobile Web URL.
For web apps, this new authentication mode should dramatically increase the number of Facebook connected users of your site, and help you design a more personalized experience. We encourage all mobile web apps to enable this mode to encourage sharing and discovery of your app content.
You can specify the permissions you would like to ask for by setting them in the App Settings for your app. To understand what you can ask for, check out the Permission doc.
Navigate to your app settings and click on the 'Authentication' tab in order to enable this functionality and set the permissions you would like to ask for. You should see the dialog below.
This is what the user will see before being redirected to your web app, once you turn on Authenticated Referrals. For now, let's add the permission 'email'.
Once the user lands on your mobile web app, you need to identify them in order to make API calls on their behalf.
First, let's add the following code in the <body></body> section of your web app.
Please remember to replace 'YOUR_APP_ID' with your app's id from the App Settings.
<script>
window.fbAsyncInit = function() {
FB.init({ appId: 'YOUR_APP_ID',
status: true,
cookie: true,
xfbml: true,
oauth: true});
FB.Event.subscribe('auth.authResponseChange', handleResponseChange);
};
</script>
In the code above, init() is called in order to initialize the Facebook JS SDK. For more information on init(), check out the JavaScript SDK docs. Next, we need to know whenever a Facebook has authenticated with your app, so we subscribe to the auth.statusChange event. Then, we define the handleResponseChange callback function to handle the response. This function will be called whenever the user's authenticates.
Now, let's paste this code, right below the fbAsyncInit code.
<script>
function handleReponseChange(response) {
document.body.className = response.authResponse ? 'connected' : 'not_connected';
if (response.authResponse) {
console.log(response);
}
}
</script>
This is the function that will be triggered when the user authenticates. If the function gets a response (the user is logged into Facebook and they've logged into your app), the <body> class name will be changed to connected. If a response isn't returned (because the user hasn't logged into your app or is logged out of Facebook), the <body> class name will be not_connected. We're also logging the response to the console for debug purposes.
Now, let's test this flow. On your Android or iOS device, go to m.facebook.com and search for your app. Once you tap the result, it will invoke the auth dialog with the set of permissions you asked for. You should then be redirected to your web app and see a response in your browser's debug console. Depending on the browser you're using, you may not be able to see the full Object. If you'd like to see the full Object, we recommend testing in your desktop browser, while spoofing your User Agent. More info on that is below, in testing.
This is what you should be seeing in your debug console.
Login when landing directly on your web app
If a user doesn't come to your web app via Facebook, they will not see this auth dialog. For example, if you're running an ad campaign and directly linking to your web app. In this case you should show the user the login button to enable them to login using Facebook.
Let's paste the code below into the <body></body>.
<div id="login">
<p><button onClick="loginUser();">Login</button></p>
</div>
<div id="logout">
<p><button onClick="FB.logout();">Logout</button></p>
</div>
<script>
function loginUser() {
FB.login(function(response) { }, {scope:'email'});
}
</script>
First, we're displaying a login and logout button to the user. The first button calls the loginUser() function when clicked, which calls FB.login(). This prompts the user with the login dialog, asking them for basic permissions and email (since we specify scope: 'email'). For more information on this flow, see login button docs. Note that, typically you should prompt the same permissions that you're asking for in Authenticated Referrals.
Once the user has interacted with the dialog, you'll receive a response back, just like the response you received when a user authenticates. Since we already have code that handles the response (handleReponseChange), we don't need to do anything when the response is sent back here, so can leave the callback function empty.
Now, try loading your index.html. You'll notice that both the login and logout buttons are displayed. Remember that we're setting the <body> class to reflect if the user has authenticated or not. So to fix this problem, let's add the following code into the bottom of index.html.
<style>
body.connected #login { display: none; }
body.connected #logout { display: block; }
body.not_connected #login { display: block; }
body.not_connected #logout { display: none; }
</style>
This CSS stylesheet will display the <div id="login"> when the user is logged in and the <div id="logout"> when the user is not logged in.
For more information on logging a user into your app, go to the authentication documentation.
When viewing on a phone, you'll notice that all of the content is zoomed out is hard to tap. To fix that problem, just paste the code below into the <head></head> of index.html.
<head>
<title>Hello World</title>
<meta name="viewport" content="initial-scale=1,minimum-scale=1,maximum-scale=1,user-scalable=no" />
</head>
This will make sure the user is zoomed to 100% and is locked, so that the content appears correctly on the device. Try navigating to index.html to see the result.
Adding social context
Step 4: Use the Graph API
Now that the user is logged in, we're ready to start making their experience social.
Get the user's information
First, let's display the user's profile picture and name.
Go back to the handleReponseChange function we already defined. In the if (response.authResponse) section, let's add updateUserInfo(response);. So it should look like this.
<script>
function handleResponseChange(response) {
document.body.className = response.authResponse ? 'connected' : 'not_connected';
if (response.authResponse) {
console.log(response);
updateUserInfo(response);
}
}
</script>
Now, paste this code at the bottom of index.html.
<div id="user-info"></div>
<script>
function updateUserInfo(response) {
FB.api('/me', function(response) {
document.getElementById('user-info').innerHTML = '<img src="https://graph.facebook.com/' + response.id + '/picture">' + response.name;
});
}
</script>
This new function, updateUserInfo, is called whenever a user authenticates, meaning they're logged into Facebook and your app. Since we have the user's access token, we can now make API calls on their behalf.
In this function, we're changing the inner HTML of the user-info div to the user's picture and name.
Here's what you should see when you've logged into your web app (with your name and profile picture).
Get the user's friends' information
Now, let's grab the user's friends information and display it to them. Paste this code at the bottom of your index.html.
<a href="#" onclick="getUserFriends();">Get friends</a><br>
<div id="user-friends"></div>
<script>
function getUserFriends() {
FB.api('/me/friends&fields=name,picture', function(response) {
console.log('Got friends: ', response);
if (!response.error) {
var markup = '';
var friends = response.data;
for (var i=0; i < friends.length && i < 25; i++) {
var friend = friends[i];
markup += '<img src="' + friend.picture + '"> ' + friend.name + '<br>';
}
document.getElementById('user-friends').innerHTML = markup;
}
});
}
</script>
First, we're displaying a link, "Get Friends". When clicked, it will call getUserFriends(). Next, we're calling the FB.api function, and the Graph API method '/me/friends/'. This will return an array of all of the user's friends. Since we specified '&fields=name,picture', you'll get their friends' profile pictures and names.
Once we have the response, we loop through it, create the HTML markup, and insert it into the div with the id 'friends'.
Now, refresh your web app, click 'Get friends' and you should see something like this.
This is what it will look like in your browser's debug console.
There are many more things you can do with the Graph API. Check out Hackbok in the sample apps section to get a better idea. Also, read the Graph API docs for more info and check out the Graph API Explorer.
Step 5: Integrate with Social Channels
Social Channels enable users to post to their friends' News Feed or send a Request to their friends. Read more about both products in the social channels section of the main mobile doc.
Requests
Requests are a great way to enable users to invite their friends to your mobile web app or to take specific action like accepting a gift. Your mobile web app can send requests by using the Request dialog. If the user’s device supports it, they will receive a Push Notification via the Facebook native app whenever a friend sends them a request, in addition to the notification they normally get within Facebook.
The following example shows how to display this dialog within your mobile web page:
<a href="#" onclick="sendRequest();">Send request</a><br>
<script>
function sendRequest() {
FB.ui({
method: 'apprequests',
message: 'invites you to learn how to make your mobile web app social',
},
function(response) {
console.log('sendRequest response: ', response);
});
}
</script>
When defining 'message', it should follow the format of <verb> <action to take>. In this example, it will read as "Matt invites you to learn how to make your mobile web app social'.
Now, open index.html and tap 'Send request'. This is the flow that you should see.
When you send a request and your friend picks it up, this is what your friend will see. First, they'll see that the notifications jewel is lit up. Once tapped, they'll see your request notification.
These also show up as counters on the app’s bookmark (more on that below). The counter is updated when there is an outstanding request.
Also, if the friend has the native iPhone Facebook app installed, they will receive a push notification, like below.
If you need to show specific friends in the suggestions list, just set “suggestions” and pass a JSON array.
Here’s an example.
FB.ui({
method: 'apprequests',
message: 'You should try out this awesome app.',
suggestions: [uid1, uid2, uid3]
},);
Where uid1, uid2, uid3 are the Facebook user ids of the user's friends. This is a comma delimited list. The suggestions parameter only works on mobile.
Here are some additional notes you should keep in mind.
- The 'message' parameter has a limit of 60 characters. If it's over 60 characters, the dialog will display an error.
- If the user isn’t logged into Facebook or hasn’t authorized your app yet, this Requests dialog will appear as a new window within their browser, rather than inline within the same page.
- By default, dialogs will be pre-cached for performance reasons. If you would like to disable that for debugging reasons, set the "useCachedDialogs" flag to "false" in init().
- The parameters 'filters', 'exclude_ids', 'max_recipients', and 'data' are currently not supported on mobile, but they will be available soon.
- Please ensure that your Facebook App has been migrated to Requests 2.0. You can find this setting in App Settings on the "Advanced" tab. It's called "Upgrade to Requests 2.0".
There are several more use cases for Requests. See them in action in the Hackbook sample app on your phone or tablet.
Timeline and Open Graph
Historically, Facebook has managed this graph and has expanded it over time as we launch new products (photos, places, etc.). In 2010, we extended the social graph, via the Open Graph protocol, to include 3rd party web sites and pages that people liked throughout the web. We are now extending the Open Graph to include arbitrary actions and objects created by 3rd party apps and enabling these apps to integrate deeply into the Facebook experience.
After a user adds your app to their Timeline, app specific actions are shared on Facebook via the Open Graph. As your app becomes an important part of how users express themselves, these actions are more prominently displayed throughout the Facebook Timeline and News Feed. This enables your app to become a key part of the user's and their friend's experience on Facebook.
Timeline is coming to mobile soon. In preparation, you can start integrating now.
To learn more about how you can integrate your app into Open Graph and Timeline, learn more or dive right into the tutorial.
News Feed
The News Feed is shown immediately to users upon logging in to Facebook, making it core to the Facebook experience. Your mobile web app can post to the user's news feed by using the Feed Dialog.
FB.ui() is the method that allows you to trigger this and other dialogs. For example:
Let's add the following code to the very bottom of your existing code, within <body></body>.
<a href="#" onclick="publishStory();">Publish feed story</a><br>
<script>
function publishStory() {
FB.ui({
method: 'feed',
name: 'I\'m building a social mobile web app!',
caption: 'This web app is going to be awesome.',
description: 'Check out Facebook\'s developer site to start building.',
link: 'http://developers.facebook.com/mobile',
picture: 'http://www.facebookmobileweb.com/getting-started/img/facebook_icon_large.png'
},
function(response) {
console.log('publishStory response: ', response);
});
return false;
}
</script>
Now, open index.html and tap 'Publish feed story'. This is the flow that you should see.
If you navigate to your profile you should see the story appear on your Wall, like the screenshot below. This story will also show up in your friends' News Feeds.
Sending the user to the right experience
If you already have an App integration on Facebook.com, ensure that the base domain used in link parameter has the base domain ‘http://apps.facebook.com/’. For example, http://apps.facebook.com/your-app?page=1.
When users click on links, Facebook will automatically direct them to your desktop or mobile experience. If the user is on mobile, we will redirect to your Mobile Web URL. For example, http://m.mobilewebapp.com/?page=1.
If the user is on desktop, we will redirect them to the apps.facebook.com URL, as in http://apps.facebook.com/your-app?page=1.
Here are some additional notes you should keep in mind.
- If the user isn’t logged into Facebook or hasn’t authorized your app yet, this News Feed dialog will appear as a new window within their browser, rather than inline within the same page.
- This dialog was made lightning fast for mobile. By default, dialogs will be pre-cached for this reason. If you would like to disable that for debugging reasons, set the "useCachedDialogs" flag to "false" in init().
- The parameter 'display' isn't supported on mobile. The SDK automatically detects the browser's user agent and will display the correct dialog.
For more information on this dialog, see the Feed Story docs.
You can also write on a friend's wall. See it in action in the Hackbook sample app on your phone or tablet.
Social Plugins
Currently, only the Like button is supported in mobile web apps, but more social plugins will be coming soon.
To implement the like button, add this code to the bottom of <body></body>. This will allow the user to like the current page you're on.
<fb:like></fb:like>
Also, make to include these meta tags in the <head></head> section of index.html so that, when the user likes the page, the page's info is displayed properly on Facebook.
<meta property="og:title" content="Hello world" />
<meta property="og:type" content="website" />
<meta property="og:site_name" content="Hello World" />
<meta property="og:description" content="Hello World! This is my mobile web sample app." />
<meta property="og:image" content="http://www.facebookmobileweb.com/start/img/facebook_icon_large.png"/>
Open up index.html and you should see the Like button appear. Once liked, a new post on the user's profile will appear.
For more information on the Like button, including customization options, see the Like button docs. Also, Open Graph docs are available.
Search and Bookmarks
Your web app will automatically be indexed in search once you have ten active users. You can search for your app on m.facebook.com by tapping on the top left bookmarks button and tapping "Search".
Once a user has authenticated with your web app, it will show up as a bookmark for them on m.facebook.com, like the screenshot below. They can access the bookmark by tapping the top left bookmarks button.
Step 6: Add payments
If you sell digital goods or services from within your mobile web app, Facebook Credits allows you to accept payments from users.
See the Credits API doc for information on how to integrate Credits into your mobile web app. Note that Credits is not supported in web apps running within the Facebook iOS app.
Deploying your social mobile web app
In order to deploy your mobile web app on Facebook, you just need to ensure that sandbox mode is disabled in App Settings and get ten friends to login to your app. You can point them to http://m.facebook.com/apps/[YOUR_APP_ID] or have them navigate directly to your web app's URL.
Then, your web app will start showing up for all Facebook users in all of the Social Channels mentioned above, including search.
Before doing that, we recommend that you follow the steps below.
Step 7: Display your app properly on devices
It's important that your web app can render correctly on any device.
You can hide the bottom navigational bar in the Facebook native app. To do this, add the following meta tag to the <head></head> section of your web app.
<meta name="apple-mobile-web-app-capable" content="yes" />
Note that this has some auxiliary effects on iOS. You can read more about them in Apple's Safari docs.
It's also recommend that you automatically scroll away the address bar in order to get as much real estate for your web app as possible. To do that, change the <body> element of you web app to this.
<body onload="setTimeout(function() { window.scrollTo(0, 1) }, 100);"></body>
Step 8: Test your integration
It's important that you test your web app before deploying it.
Testing in a mobile browser
It's highly recommended that you enable the debug console on Safari and Android in order to debug any issues your web app may be having.
For more information for doing that on iOS, see the Apple debug console docs.
For more information for doing that on Android, see the official debug console docs.
Testing in a desktop browser
In order to test the mobile experience in your desktop browser, you will have to change the user agent so that m.facebook.com renders the proper mobile version.
In Safari, navigate to “Developer” -> “User Agent” and choose “Safari iOS 4.1 – iPhone”.
The following links contain information on how to spoof properly in other browsers.
Once you set up spoofing in these browsers, use the User Agent “Mozilla/5.0 (iPhone; U; CPU like Mac OS X; en) AppleWebKit/420+ (KHTML, like Gecko) Version/3.0 Mobile/1A543a Safari/419.3”. This will trick the Facebook dialogs and your website into thinking your desktop browser is an iPhone, which will render the proper mobile content.
Step 9: Add icons
Before you deploy your mobile web app, you should set icons so that it appears properly within Facebook. You'll need a 75x75 and 16x16 icon (the latter will be used for your bookmark).
Icons can be set on the main page of your app's settings page.
Finished!
Congrats, you've built and deployed your social mobile web app. One of the key benefits of building a web app is that it works just about anywhere.
Note that this tutorial covers most of the functionality offered to mobile web apps. Some features that are available on desktop aren't support on mobile yet. For an overview of those features, see the feature support page.
Sample social web apps
Hello World
Live demo: www.facebookmobileweb.com/hello/
Source code (Github): https://github.com/facebook/platform-samples
This is complete version of the tutorial in this guide.
Hackbook
Live demo: www.facebookmobileweb.com/hackbook/
Source code (Github): https://github.com/facebook/platform-samples
A mobile web app that samples all of the Facebook Platform functionality that's available. Check this out to see what's possible with our Platform APIs.
Updated about 5 months ago