New Design Publisher
From Facebook Developers Wiki
Contents |
[edit] Publisher
The Publisher is the primary feature for users to post information and messages on their own Feed and on their friends' Feeds. Users can use the Publisher to create rich content including posting photos, sharing videos, writing notes, and whatever content ideas applications can provide. The Publisher will be a central focus of communication and sharing in the new profile. It sits right on top of a user's Feed, inviting the user or others to add content. Applications can integrate into the Publisher to provide rich experiences for creating or finding content to post into their own and their friends’ Feeds. And these stories can leverage any of the new Feed story sizes – see below for more details.
This has replaced the old Wall Attachments feature. Now, Wall is just one type of application for creating content (text content), on par with posting links, or uploading photos or videos. For example, to add a video with the Video application, the user no longer creates a Wall attachment and adds the video. Instead, the user posts a video to a friend's Feed just as if she were writing a Wall post. When users use an application integrated in the Publisher, they can add additional text comments along with the content posted through the application. (Applications may disable the text/comment feature as well). Once a story is posted through the Publisher, it appears immediately in the feed.
Above the Publisher box is a series of options for the types of content that the user can create. Clicking one of the options expands the Publisher box inline to the appropriate interface.
Any application that supports the Publisher integration will be eligible to appear in the list presented to a user. Initially, applications will be sorted with default applications first, and then by how recently the application was used to create content or simply used by the user. When viewing a friend's profile, this will also take into account which applications the friend uses and what applications have been used recently to post content on the friends' profile.
The Publisher interface looks similar to the user when viewing her own profile as when viewing a friend's profile, but the content options or publishing interface my differ. Applications will be able to register a different interface for publishing on a profile owner’s profile and for publishing on a friend’s profile. As an example, the photos applications may allow for a user to post a full album to her own profile, but on a friend’s profile, the interface could change to only allow four photos.
When a user creates content in her own profile via the Publisher, it appears as a full Feed story. When a user creates content in a friend’s profile, it appears as a short Feed story with a distinct UI provided by Facebook to indicate someone has posted it (like Wall posts currently). The friend could expand this to a full story if one is provided by the application.
[edit] Integrating Your Applications
Before you can start integrating your application into the Publisher, you need to know the details about the Publisher box. The Publisher box is 500 pixels wide with 40 pixels of padding. The height of the Publisher should not exceed one page (700 pixels) in height.
The Publisher allows a permissive flavor of FBML, automatically playing Flash, and supports onload FBJS.
The Publisher also has two special options. You can include a text box for comments that appears below the publish box, and you can use FBJS to enable/disable the Post button until the user finishes the publish form.
[edit] Using the Publisher
In order to make the Publisher option available for your application, you need to specify an action and a callback URL in the application settings. There are two sets of these options available: one for when a user publishes to his or her own profile (under Publish Content to Self in your application settings) and one for when a user publishes to a friend’s profile (under Publish Content to Friend in your application settings). You can choose to specify either set or both. The action specifies the text that appears for your option (like specifying an attachment action today).
When a user interacts with the Publisher, Facebook sends two requests to your application: the first to render your version of the Publisher interface and the second to request the content for the Feed story that gets generated when the user publishes the content.
Facebook always passes the following parameters in a request when the user interacts with the Publisher:
- fb_sig_api_key: Your application’s API key.
- fb_sig: A signature using your application’s secret key to encrypt the request.
- fb_sig_in_canvas: This parameter is always false or 0 because the Publisher is not a canvas page.
- fb_sig_request_method: This is always a POST method.
- fb_sig_locale: This is the user’s locale.
- fb_sig_time: The time that the request was made.
- fb_sig_added: Indicates whether the user has installed the application.
In addition, Facebook passes the following parameters only if the user has agreed to the Terms of Service for your application:
- fb_sig_user: The ID of the user interacting with the Publisher.
- fb_sig_profile_update_time: The last time the user profile was updated.
- fb_sig_session_key: The user’s session key.
- fb_sig_expires: The time the session key expires.
[edit] Rendering the Publisher to the User
When the Publisher is available for your application and a user elects to publish content with your application, a request is made to the specified callback URL. The callback URL should respond with the data needed to render the interface for the user to publish content to a profile.
In addition to the parameters specified above, when rendering the Publisher interface, Facebook also passes a parameter method, which is set to publisher_getInterface. You must include this method in your response.
[edit] Example JSON Response
| {"content": {"fbml":"Word of the Day<br /><input type='text' value='' name='word' />", "publishEnabled":true, "commentEnabled":true, }, "method":"publisher_getInterface" } |
The parameters for your response are described in the following table.
| Parameter | Description |
|---|---|
| method | This parameter must be set to publisher_getInterface.
|
| content | The data for the actual response. |
| fbml | The FBML that should be rendered in the Publisher. The user interacts with this FBML to create content. |
| publishEnabled | Specifies whether the Post button is enabled immediately in the Publisher. This parameter defaults to false.
If |
| commentEnabled | Specifies whether a standard text box should be rendered in the Publisher to allow a user to make comments with the attachment. This parameter defaults to false.
|
[edit] Creating the Feed Story
Once the user interacts with the Publisher and goes to publish the content (by clicking Post in the Publisher), the application needs to return the content used to create the Feed story. Another request will be made to the same callback URL, passing all the parameters specified above. In addition, Facebook passes two more parameters:
-
method, which is set topublisher_getFeedStory. You must include this method in your response. -
app_params, which is an array of elements that form the content necessary to create a Feed story. The array contains all the data from the form elements in the Publisher interface (like input elements and textareas), similar to the attachments interface today. If a comment text box was made available (that is,commentEnabledis set totrue), the text in the box will be returned inapp_params['comment_text'].
[edit] Example JSON Response
| {"content": {"feed": {"template_id":55555555, "template_data": {"word":"supercalifragilisticexpialidocious"} } }, "method":"publisher_getFeedStory" } |
The parameters for your response are described in the following table.
| Parameter | Description |
|---|---|
| content | The data for the actual Feed story. It’s an array that contains the elements of the Feed story, like template references. |
| method | This parameter must be set to publisher_getFeedStory.
|
[edit] Error Codes
In case an error occurs -- for example, if the user submitted some invalid data in the Publisher interface -- the callback URL can also respond by rendering an error. The following illustrates a JSON-encoded error:
| {"errorCode":1, "errorTitle":"Oops!", "errorMessage":"The word you entered is not in the dictionary" } |
Currently the only error code supported is the value 1, which indicates a validation failure on the application’s behalf.
