Changing profile content
From Facebook Developers Wiki
Contents |
[edit] Introduction
Applications that a user has added may add content to the user's profile page. [insert note about profile item insertion checkbox during add app process]
Your widget can't make a request with every profile load: all markup inserted by your API call will be cached (a 'push' model). However, if the user interacts with your widget (e.g. submits a form) you can trigger a content change, and may use mock ajax to do so.
Flash applications will not start automatically.
You can either:
- Make a call that updates an individual user's profile content (direct)
- Insert a 'reference handle' into the user's profile, for which you'll provide the markup in another call (indirect).
The indirect method is better when multiple users have the same content, because you can give them all the same handle.
[edit] Direct
[edit] profile.setFBML( markup: <markup>, uid: <uid> )
setFBML() lets you directly insert FBML into the profile widget. You need an infinite session key to do this, but it doesn't have to be the session key of the user whose page you wish to update. Your own key will do. Markup is restricted and will be cached. For more information, see setFBML
PHP:
old - $facebook->api_client->profile_setFBML( $markup, $uid ); new - $facebook->api_client->profile_setFBML( $uid, $fbml_markup, $profile_action, $fbml_mobile);
Perl:
old - $facebook->profile->set_fbml( profile => $markup, uid => $uid ); new - $facebook->profile->set_fbml( profile => $markup, uid => $uid, profile_main => $main_markup ); # CAVE: only works with api.new.facebook.com as of 7/23
[edit] Indirect
[edit] Usage Example
You have 1,000 users. Each gets listings of upcoming concerts according to their city. Using profile_setFBML, when your listings update, you'd have to make 1,000 calls to set the content for each user. On the other hand, if you set a handle like "city_boston" on the user's profile when they add your app, you can update the profile widget for every user in Boston with one API call.
[edit] <fb:ref handle="UNIQUE_HANDLE_HERE" />
Using the direct method, above, place one or more <fb:ref handle> tags on the user's profile. Now each time you want to update the user's profile, you just need to set the value of the handle.
Handy Hint: This method's beauty is in using non-unique handles. Place a global and a unique handle on everyone's page and you have the ability to set a global message at any time you want to.
<fb:ref handle="global_announcement" /><fb:ref handle="$user_id" />
You could also distinguish groups of users and add a handle for that group. Then every time you want to update everyone in that group, you have a handle.
Each app has its own handle namespace.
[edit] Updating the handle
To update the handle, you once again need an infinite session. Use your own.
facebook.fbml.setRefHandle( handle: <handle>, markup: <markup> )
This will update the profile of every user that has the given <handle> and replace the fb:ref tag with the <markup> (Note: It will not remove content placed by other handles)
PHP:
$facebook->api_client->fbml_setRefHandle($handle, $markup);
Perl
$facebook->fbml->set_ref_handle( handle => $handle, fbml => $markup );
[edit] <fb:ref url="http://www.mysite.com/update.php?handle=UNIQUE_HANDLE_HERE" />
The alternate to using a handle, is to set the FBML as above, but with a callback URL. Then, using refreshRefUrl(), you can have Facebook call your URL to create the FBML.
Handy Hint: This option is particularly useful if you already have an interface for setting the profile code on your canvas page. That interface can be re-used to answer to this call.
[edit] Updating the handle
To update the handle, you once again need an infinite session. Use your own.
facebook.fbml.refreshRefUrl( url: <url> )
PHP:
$facebook->api_client->fbml_refreshRefUrl("http://www.mysite.com/update.php?handle=UNIQUE_HANDLE_HERE")
Perl:
$facebook->fbml->refresh_ref_url( url => "http://www.mysite.com/update.php?handle=UNIQUE_HANDLE_HERE")
[edit] Setting Profile Content on Pages
You can use the same techniques to update the profile box on Pages, but instead of a user id you will need to pass in a page id. When your application is viewed by the administrator of a page which has added your application, the page's id is appended to the URL of your canvas page. http://apps.facebook.com/YOURAPPLICATION/?fb_page_id=XXXXXXXXXX.
You can access it via the $_GET/$_REQUEST variables in PHP, like so:
PHP:
if (array_key_exists('fb_page_id', $_REQUEST)) {
$page_id = $_REQUEST['fb_page_id'];
$facebook->api_client->profile_setFBML($markup, $page_id);
}
