Facebook Cookbook

how to send notifications and emails

sending notifications and emails are very important features of a facebook app. now i’m going to show how you will send notifications and emails to users.

there are two types of notifications: user-to-user and application-to-user

• a user-to-user notification is sent on behalf of one user to one or more other users
• application-to-user notifications are sent on an application’s behalf and do not require an active session.

case 1: suppose you have an application question/answer type. let user  ‘x’ sent a question to user ‘y’. so how will you notify user ‘y’ that he received a question. you can send a notification to user ‘y’ from user ‘x’ and also you could send an email to user ‘y’ from user ‘x’.

solution: for sending notification you could write this code

/*------- sends a notification or request to a set of users. notifications are items sent by an application to a user's notifications page in response to some sort of user activity within an application ----------*/
// $facebook->api_client->notifications_send(ids, notificationmessage, notificationtype);

$facebook->api_client->notifications_send('654321890', "you've received a msg from <fb:name uid='7464635353' />", 'user_to_user');

this notification is sent from user to user, that’s why you’ve to mention notification type as ‘user_to_user’

another imortant thing is that, you could send same notifications to more than one users as a single api call. just specify the ids as a comman separated list like

$facebook->api_client->notifications_send('654321890,656565654, 49393939', "msg", 'user_to_user');

case 2: let you also want to send an email to user ‘y’ from user ‘x’ in the situation of case 1.

solution: you could only send emails to the users, who have both authorized your application and granted it the email extended permission. so how will you ask the user for accepting extended permission for email. here is the way. write the below code in your view page or layout:

<fb:prompt-permission perms="email">Would you like to receive email from our application?</fb:prompt-permission>

this will render this link in your view page:

when user will click this link, a dialog box will open and show user a message  to accept receive emails permission. if user accept this permission, then this link will not shown to that user in future.

here is the api call that you have to use to send email:

//$facebook->api_client->notifications_sendEmail('recipients', 'mail_subject', "tex", 'fbml');
$facebook->api_client->notifications_sendEmail('73737373', 'you received a question', "", "hi user <fb:name uid='47363633' /> has sent you a message");

remember the parameters:

• recipients: a comma-separated list of recipient IDs. you can email up to 100 people at a time.
• subject: the subject of the email message. as of 10/28/2008, the subject will accept a limited set of fbml tags, including names, and tags related to internationalization.
• text: the plain text version of the email content. you must include a non-empty value for at least one of either the fbml or text parameters. the fbml input takes precedence, but if the given fbml value is invalid or cannot be rendered, then the text will be used instead. there is currently no character limit on the length of either the text or fbml body.
• fbml: the fbml version of the email. you must include a non-empty value for at least one of either the fbml or text parameters. the fbml parameter is a stripped-down set of fbml  that allows only html/fbml tags that result in text, links, linebreaks, as well as tags related to internationalization.

references:

• http://wiki.developers.facebook.com/index.php/Notifications.sendEmail
• http://wiki.developers.facebook.com/index.php/Notifications.send
• http://wiki.developers.facebook.com/index.php/Fb:prompt-permission

friends selection custom component

for 1 of my facebook application, i was  needed a custom friends selector. the purpose was, i’ve a page from where i’ve to select multiple friends and then i’ll submit those selected friend ids using ajax call without refreshing the page.

then i searched the documentation of fbml. in facebook component, there are 2 types of friends selector

1. http://wiki.developers.facebook.com/index.php/Fb:multi-friend-selector
2. http://wiki.developers.facebook.com/index.php/Fb:multi-friend-selector_(condensed)

but both of these are totally controlled by facebook and these components are used to send invitation or request to friends. i need a component like figure 2. the fbml code for the second component is below:

<fb :request-form method=”post” action=”http://yourdomain.com/submit.php” content=”Select Friends” type=”gifts” invite=”true”>
<div class=”clearfix” style=”padding-bottom: 10px;”>
<fb :multi-friend-selector condensed=”true” selected_rows=”0? style=”width: 220px;” />
</div>
<fb :request-form-submit />
</fb>

but I was needed a component that would be fully controlled by me. so,  I developed a friends selection component and I’m sharing it.

Read more

fbml rendering in iframe application

before proceeding the main topic, at first i want to describe how to develop iframe based facebook application. i assume that, the reader have minimum knowledge of how to develop canvas based facebook application. if you never develop any facebook application please visit: http://wiki.developers.facebook.com/index.php/creating_your_first_application

steps of developing iframe based facebook application:

1. when you setup a new application in facebook, choose “use iframe” for canvas page url.
2. now set the authentication code, at your bootstrap file:

<?php
include “facebook.php”;
$facebook = new facebook(’api_key’, ’secret_key’);
$user = $facebook->require_login();

//catch the exception that gets thrown if the cookie has an invalid session_key in it
try {
if (!$facebook->api_client->users_isappadded()) {
$facebook->redirect($facebook->get_add_url());
}
}
catch (exception $ex) { //this will clear cookies for your application and redirect them to a login prompt
$facebook->set_user(null, null);
$facebook->redirect(callback_url);
}
?>

3. and don’t forget to place the necessary facebook php library. http://wiki.developers.facebook.com/index.php/php

now i’m describing the main topic, that is how to render xfbml or fbml in your iframe based application.

1. first create a file called xd_receiver.htm
2. place xd_receiver.htm in the root directory. suppose your application base directory is: http://myapp.com/iframeapp . then place xd_receiver.htm in iframeapp folder. now add the following html code to xd_receiver.htm .

<!doctype html public “-//w3c//dtd xhtml 1.0 strict//en” “http://www.w3.org/tr/xhtml1/dtd/xhtml1-strict.dtd”>
<html xmlns=”http://www.w3.org/1999/xhtml” >
<head>
<title>cross-domain receiver page</title>
</head>
<body>
<script src=”http://static.ak.facebook.com/js/api_lib/v0.4/xdcommreceiver.debug.js” type=”text/javascript”></script>
</body>
</html>

now in your view file, or may be layout file, place this code. here i’m showing the layout files format for iframe application.

<!doctype html public “-//w3c//dtd xhtml 1.0 strict//en” “http://www.w3.org/tr/xhtml1/dtd/xhtml1-strict.dtd”>
<html xmlns=”http://www.w3.org/1999/xhtml” xmlns:fb=”http://www.facebook.com/2008/fbml”>

<head>
<script src=”http://static.ak.facebook.com/js/api_lib/v0.4/featureloader.js.php” type=”text/javascript”></script>

</head>

<body>

<!– here is the fbml code in iframe application –>

<fb:serverfbml>
<script type=”text/fbml”>
<fb:fbml>

<fb:request-form action=”<url for post invite action, see wiki page for fb:request-form for   details>” method=”post” invite=”true” type=”xfbml” content=”this is a test invitation from xfbml test app <fb:req-choice url=’see wiki page for fb:req-choice for details’ label=’ignore the connect test app!’ />  ” >  <fb:multi-friend-selector showborder=”false” actiontext=”invite your friends to use connect.”>  </fb:request-form>
</fb:fbml>
</script>
</fb:serverfbml>

<!– here is the xfbml code –>

this is <fb:name uid=”<?=$this->userid?>” useyou=’false’> </fb:name>
my photo <fb:profile-pic uid=”<?=$this->userid?>” > </fb:profice-pic>

<!– remember all xfbml tags should be placed before below javascript code –>

<script type=”text/javascript”>
fb_requirefeatures(["xfbml"], function(){
fb.facebook.init(”place here the api key of your application“, “xd_receiver.htm”);
});
</script>

</body>

</html>

** remember xfbml is nothing but a subset of fbml that are supported for iframe application.

<fb:serverfbml> : this tag is used to renders the fbml on a facebook server inside an iframe. details of this tag is here: http://wiki.developers.facebook.com/index.php/fb:serverfbml

references:

1. http://wiki.developers.facebook.com/index.php/xfbml
2. http://wiki.developers.facebook.com/index.php/cross-domain_communication_channel
3. http://wiki.developers.facebook.com/index.php/php
4. http://wiki.developers.facebook.com/index.php/creating_your_first_application