Connect/Building a Publisher

From Facebook Developer Wiki

Jump to: navigation, search

Contents

Benefits

The Publisher is a great way for Facebook users to share rich content with their friends quickly and easily. The Publisher is at the top of every Facebook profile,and home page, so users can easily share a link, photo/video, or more with their friends.

Integrating your Facebook Connect site into the Publisher has many significant benefits.

  • It lets users share your site's content directly on Facebook, from their home pages, their own profiles, and from their friends' profiles.
  • It's another avenue for your site to get distribution on Facebook, from any user's profile.
  • By allowing users to create content that appears in their Facebook streams, you can increase traffic back to your site as users click on the posts they see in their streams.

How It Works

The Publisher appears on the home page and profile for every Facebook user. You integrate with the Publisher by creating an attachment that the Publisher can use. The Publisher displays attachment links for default Facebook applications: Photos, Videos, Events, and Links.

In addition, the Publisher can display a menu of Publisher integrations for applications and sites the user has authorized or most recently interacted with. The more often a user interacts with your site, the more likely it is to appear in the menu. Your Publisher integration is also more likely to appear if the user has interacted with your site recently.

So, in short, your users can publish content directly to Facebook through your Publisher whenever the user visits:

  • His or her own profile or home page, and the user has connected with your site.
  • A friend's profile, and the either the user or the friend has connected with your site.

Note: At this time, Facebook Connect sites cannot integrate a Publisher on a Facebook Page.

Case Study: The Run Around

To help illustrate how the Publisher works, we'll focus on The Run Around, a sample Facebook Connect site.

  1. The user visits your Facebook Connect site, sees the link to your Publisher, then clicks it.

    Or, a user who has connected accounts with your site is browsing Facebook and decides to share something through the Publisher.
  2. The user interacts with the Publisher. Here, the user is posting a run to his profile.
  3. After the user clicks Share, the post appears on his profile and in his friends' streams.

Implementation

To get started, you need to build a Publisher, following the instructions in the Publisher article.

Your Publisher code resides in files on your site. You need one file containing the code for the Publisher that appears on the user's profile, and one file containing the code for the Publisher that a user sees when viewing a friend's profile.

For example, here's the code for the Publisher for the Run Around that appears on a user's own profile. The content is in http://www.somethingtoputhere.com/therunaround/handlers/self_publisher.php.

<?php /** * Facebook Publisher -- this is an optional feature that allows users to * "Add Runs" directly from Facebook using the Publisher feature. This * feature can be used by any Connect site. */ define(MAIN_PATH, realpath('..')); include_once MAIN_PATH.'/init.php'; // Since this is the self_publisher, this is the user/profile owner $uid = facebook_client()->get_loggedin_user(); $user = User::getByFacebookUID($uid); // Render the UI for the publisher if ($_POST['method'] == 'publisher_getInterface') { $fbml = render_publisher_css(); $fbml .= render_publisher_js(); $fbml .= '<form>'; $fbml .= render_add_run_table_fields($user); $fbml .= '</form>'; $content = array('fbml' => $fbml, 'publishEnabled' => true, 'commentEnabled' => true); // Render the Feed story after the user publishes } else if ($_POST['method'] == 'publisher_getFeedStory') { $params = parse_http_args($_POST['app_params'], array('miles', 'route', 'date_month', 'date_day', 'date_year')); $run = new Run($user, $params); if (!$run->save()) { error_and_exit('Invalid Input', 'An invalid field was supplied.'); } $attachment = array('name' => 'Pete Bratach went for a run.', 'href' => 'http://www.somethingtoputhere.com/therunaround/', 'caption' => '{*actor*} went for a ' . $params['miles'] . ' run at ' . $params['route'] . '.', 'properties' => array('miles' => $params['miles'], 'route' => $params['route'], 'date' => $params['date_month'] . '/' . $params['date_day'] . '/' . $params['date_year'])); $content = array('attachment' => $attachment); } else { error_log("Unsupported method: ".$_POST['method']); exit; } // Send response back to Facebook $data = array('method' => $_POST['method'], 'content' => $content); echo json_encode($data); /** * CSS styling for Publisher. */ function render_publisher_css() { return " <style> .add_run_table .editor_key { text-align: right; width: 170px; } .add_run_table .editor_key label { padding-right: 10px; } .add_run_table .editor_value { float: left; margin: 2px 0px; overflow: hidden; } .add_run_table .editor_value .inputtext { width: 215px; } .add_run_table .editor_value .datefield { width: auto; } </style>"; } /** * FBJS necessary for publisher. */ function render_publisher_js() { return " <script> function populate_date(month, day, year) { document.getElementById('date_month').setValue(month); document.getElementById('date_day').setValue(day); document.getElementById('date_year').setValue(year); } </script>"; } /** * Helper function to send back an error and then exit in case of input error. */ function error_and_exit($error_title, $error_message) { $data = array('errorCode' => 1, 'errorTitle' => $error_title, 'errorMessage' => $error_message); echo json_encode($data); exit; }

Specifying Application Settings

Once you've finished coding your Publisher, edit the settings for your site in the Facebook Developer application.

  1. Go to the Facebook Developer application. Select your site in the left column, then click Edit Settings.
  2. In the application settings editor, make sure you specify:
    • An icon: On the Basic tab, upload an icon, which appears in the story on Facebook. The icon automatically links back to your application profile Page. You can upload a JPG, GIF, or PNG file. If the image is larger than 16x16 pixels, it gets resized and converted.
    • Links to your Publisher: On the Profiles tab, specify the URL for the Publisher on the user's own profile and on the user's friend's profile in the Self-Publish Callback URL and Publish Callback URL fields. Include the text that appears in the Publisher dropdown menu in the Self-Publish Text and Publish Text fields. For example, the Run Around publish text says "Add Run."
    • Note: The Run Around uses only the Publisher on the user's own profile. There is no Publisher for a friend's profile.
  3. Click Save Changes to save your settings.

Referencing the Publisher on Your Site

You can include a link to your Publisher on your site. Add the following code where you want the link to the Publisher to appear. When a user clicks the link, the user gets returned to his or her profile, where he or she can interact with the Publisher, and post content directly onto his or her profile.

<fb:serverfbml> <fb:publisher-link uid="$user">Add a run on Facebook.</fb:publisher-link> </fb:serverfbml>

Best Practices

You should consider the following best practices as you design your Publisher integration.

Make the Layout Fluid

You should build a fluid layout that can scale any width between 370px and 538px, because the Publisher lives on multiple pages at varying widths. This also makes your Publisher flexible so it can accommodate future design decisions Facebook might make regarding the home and profile pages.

You can do this with your Publisher's CSS. The Run Around code sample above contains the CSS for the Publisher. Note that some elements use auto width; those with specified widths are much narrower than the 370 pixels.

Alternately, you can put your Publisher layout in an HTML table.

Disable the Share Button

You can use FBJS to enable/disable the Share button until the user finishes the publish form.

When rendering the Publisher, set publishEnabled to false, then call the FBJS method Facebook.setPublishStatus(true) to enable the button again after the user finishes interacting with the Publisher interface.

Reference

  • Publisher: This article contains more information about the Publisher, including the parameters that Facebook sends when a user interacts with the Publisher.
  • fb:publisher-link: This FBML tag lets you render a Publisher link.
  • fb:serverfbml: This XFBML tag lets you render FBML tags (like fb:publisher-link) on external websites.
Retrieved from "http://wiki.developers.facebook.com/index.php/Connect/Building_a_Publisher"
reference