Mobile

From Facebook Developer Wiki

Jump to: navigation, search

Contents

Facebook Platform for Mobile

Facebook Platform for Mobile allows applications to integrate with and leverage Facebook's core mobile services. There are two primary areas for mobile integration:

  1. Applications can have a presence on Facebook's XHTML website (m.facebook.com) in the form of profile boxes and canvas pages.
  2. Applications can leverage Facebook's SMS service to directly interact with users via text messaging.

Users will be able to interact with applications that they have installed as well as add new applications from both the XHTML site and via SMS.

This feature is country dependent. It does not work in Spain, for instance.


Facebook Platform for Mobile: XHTML

FBML allows applications to integrate with the Facebook website in profile boxes and canvas pages. The fb:mobile tag provides integration into the mobile XHTML version of the Facebook website (http://m.facebook.com).

XHTML Profile Pages

The mobile site features a limited version of the profile page, designed for optimized viewing on a mobile device. Applications may integrate into this profile via use of the fb:mobile tag.

When evaluating profile FBML, any content inside a fb:mobile tag will be rendered exclusively on m.facebook.com. This content will not be displayed on the regular site. Further, profile content outside of the fb:mobile tag will not be displayed on the mobile site.

XHTML Canvas Pages

Facebook enables application developers using FBML to build pages optimized for the mobile device by signaling when a mobile device may be in use and providing the option for the application developer to use an XHTML frame.

In order to use an XHTML frame instead of the standard Facebook frame, an application implementing canvas pages in FBML should wrap the canvas page FBML in opening and closing fb:mobile tags. The fb:mobile tag must be the outermost tag in the FBML markup. When this is specified, the mobile XHTML frame is used, visually consistent with the m.facebook.com site. Check out the list of allowed HTML and FBML tags.

In order to help developers identify when a mobile device may be in use, Facebook may optionally send an additional header with the canvas page request. When Facebook recognizes a browser agent likely to be mobile, a POST parameter fb_sig_mobile is sent with a value of 1. Note that this is purely informative. Control over which frame is used is left up to the developer. The application may choose to ignore the fb_sig_mobile parameter, and the normal frame will be used. Similarly, applications are also free to use the fb:mobile tag even when Facebook has not identified the agent as a mobile device.

XHTML Best Practices

In order to guarantee proper rendering on mobile devices with limited processing/bandwidth capability and/or alternate browser implementations, content inside the fb:mobile tag is limited to a subset of the full FBML markup. Most notably, all FBJS and Mock AJAX constructs are unavailable.

Mobile applications should avoid heavy use of images, tables, and advanced CSS. The Openwave XHTML Mobile Profile documentation is available for consultation and examples at http://developer.openwave.com/documentation/xhtml_mp_css_reference/.

The developer FBML test console can be used to test rendering of fb:mobile content. Note that the fb:mobile tag must be included when using the test console in mobile mode. Content outside of fb:mobile will not be rendered, as previously described.

Facebook Platform for Mobile: SMS

The Facebook Platform for Mobile provides applications with methods to directly interact with Facebook users through SMS (Short Message Service) interaction. This includes sending messages to the user and responding to messages from the user via text message.

Policies

  • 1. Explicit user opt-in to receive SMS from the application.
    • a. Online opt-in through the extended permissions authorization page. In order to enable SMS support for a user, the application would direct the user to http://www.facebook.com/authorize.php?api_key=YOUR_API_KEY&v=1.0&ext_perm=sms.
    • b. Offline opt-in through SMS directly, by sending a query to an application which they have not already installed as described below in the user generated messages section. If the user is not already registered for Facebook Mobile or the application, the request is cached and forwarded when the user validates the action.
  • 2. Design Restrictions:
    • a. An application has to explicitly register for SMS capabilities. This is identified by "mobile capabilities" indicators on the application properties section.
    • b. Single- v. Multiple-User Routing: Facebook prohibits multiple user-routing. Each message must be sent to one user only.
    • c. Throttling: Facebook has implemented the following throttling restrictions on the ability of applications to send SMS. Applications will be limited to a global limit that equals the sum of 1 MT (Mobile Terminated, or a message sent to a mobile phone) per user that has opted to receive SMS from the app each day. In response to an MO (Mobile Originated, or a message sent by a mobile phone) sent directly to the application a response of 1 MT is allowed to which this limit does not apply.
    • d. Application messages are subject to all user defined global restrictions on SMS notifications such as time of day and daily limiting. These restrictions do not apply in the case of a response to a user generated message.
    • f. Application-generated SMS messages are only allowed to refer to m.facebook.com based urls.
  • 3. Opt-out:
    • a. Users can disable SMS for an app at any time from the Facebook Mobile Control Panel or the application's Edit Settings page.
    • b. Users can also disable SMS entirely by any of the following methods:
      • 1) replying "Stop" or "Off" in response to any message originating from a Facebook application.
      • 2) Turning Mobile Texts to "Off" from the Facebook Mobile Control panel or
      • 3) Removing the Facebook Mobile Application.

API

Receiving User Generated Messages

A user can send your application a query directly by issuing a text message of the form to the FBOOK shortcode (32665):

app_canvas_name <query>

In addition, if your application previously sent that user a message and requested a session, any user response to that message will be forwarded to your application directly. This happens through a POST method to your application's callback URL with the following parameters:

  • fb_sig_sms - set to 1 to indicate this is an SMS callback
  • fb_sig_user - the user ID that triggered the callback
  • fb_sig_message - the message string (stripped of the header mentioned above)
  • fb_sig_sms_sid - the session ID to be used if the application wishes to respond to the message. A session ID is only unique in the context of its corresponding user ID.
  • fb_sig_sms_new_user - set to 1 if the user has just recently added the application through offline SMS.

Your application then has a window 1 minute in length in which it can respond to the message. After the minute times out, the session expires.

Sending Application Generated Messages

In order for your application to send an SMS message, the user must grant your application the sms extended permission.

Then call sms.canSend to verify whether the user has enabled SMS for your application.

To send the message, call sms.send.

Workflow

  • "Notification"
    • App invokes SMS.send without requesting a session
    • Message sent to user
  • "Conversation"
    • App invokes SMS.send and requests a session
    • Message is sent to the user
    • App retrieves session id to be used to track future state
    • User may or may not respond to message, and cycle continues
  • User Query
    • User sends message to application by app_canvas_name <query> to FBOOK (32665).
    • Message is posted to application callback url with session id
    • Application replies within the timeout using the given session id
    • Message sent to user
  • Installation
    • User sends a message to an application that they have either not already installed, or for which they have not authorized SMS access
    • Message is cached and the user is sent a confirmation SMS
    • If the user confirms the action, the cached message is forwarded to the application and the application is installed and enabled for SMS for the user, otherwise no action takes place.


Developer Guidelines for Mobile

  • Developers should consult the guidelines developed by the Mobile Marketing Association (MMA) to protect users from unwanted business practices. Please reference this documentation for comprehensive information about these guidelines
  • Developers that violate the Developer Terms of Service (http://developers.facebook.com/terms.php) will be reviewed for termination from participation in the Facebook Platform.


Additional Resources

Retrieved from "http://wiki.developers.facebook.com/index.php/Mobile"
reference