Mobile

From Facebook Developers Wiki

Jump to: navigation, search

Contents

[edit] 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 and 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.

[edit] 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 web site (http://m.facebook.com).

[edit] 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.

[edit] 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.

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.

[edit] 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. http://developers.facebook.com/tools.php?fbml

[edit] Facebook Platform for Mobile: SMS

SMS platform provides applications methods to directly interact with Facebook users through SMS interaction. This includes sending messages to the user and responding to messages from the user via text message.

[edit] Policies

  • 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 per user that has opted to receive SMS from the app each day. In response to an MO 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.

[edit] API

[edit] User generated messages

A user can send an application a query directly by issuing a text message of the form : app_canvas_name <query> to the FBOOK shortcode (32665). In addition, if an application previously sent a message and requested a session, any user response to that message will be forwarded to the application directly. This happens through a post method to the 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 per user id that it corresponds to.
  • fb_sig_sms_new_user – set to 1 if the user has just recently added the application through offline sms.

An application will be given a timeout of 1 minute in which to respond to the message, after which period the session will expire.

[edit] Application generated messages

[edit] sms.canSend(uid uid)

Used to determine whether the user identified by "uid" has enabled SMS for this application. Requires an active session, and is only recommended as a basis for design in terms of disabling certain elements or options that are conditional on this capability.

Returns
0 Success
270 Permissions disallow SMS to the user
852 User has met the quota (unsolicited message)
853 User does not accept SMS during this time
854 Application has reached the daily quota


[edit] sms.send(uid uid, string message, i32 session_id, bool req_session)

Send the given message to the user. Does NOT require an active session, can be sent asynchronously.

"session_id" is used to identify whether the application is responding to a user generated message. "req_session" is used to request a session if the application has an expectation that a user may reply to this SMS directly. In this case a session id is generated and passed back to the application for its book keeping. If a session id is not requested, the message is sent to the user through a generic number and any replies to that message will be forwarded along with no guarantee of corresponding to a specific outbound message.
Returns - 0 if successful and req_session is false, or the session_id that was created.

Throws
1 Unknown Exception
270 Permissions disallow SMS to the user
850 Invalid session_id expired session (response message)
851 Invalid SMS length
852 User has met the quota
853 User does not accept SMS during this time (unsolicited message)
854 Application has reached the daily quota (unsolicited message)

[edit] 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 retrives 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.


[edit] 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.

[edit] Additional Resources

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