Allow Your Users to Invite Their Friends
February 20, 2008
Invite forms are one of many opportunities available in the Facebook Platform that enable application growth. They allow users to share applications with their friends who might not have otherwise known about them. Because invitations are enacted by users (as opposed to the application or Facebook itself), friends receiving these invites are likely to view each invite request, providing them an opportunity to be converted into an application user as well.
A Bit of Invite History
Inviting friends has been a controversial spot amongst Facebook application developers. The act of inviting friends is not specifically what all the controversy is about; instead, it’s how some developers have chosen to integrate their invite forms. In an attempt to create a multitude of application invitations in hopes of drawing many new users, numerous developers have made it mandatory for new users to invite a minimum number of friends to an application before the user can even interact with the application themselves. Clicking the “Skip” button on the invite form simply returned the user to the invite form once again until they either invited the minimum number of friends, or left the application altogether.
Because Facebook applications are relatively new, this technique has proven successful. Many did not realize (and some still do not realize) that this is not the way Facebook’s invite form was intended to be used, and as a result, many applications found a large number of users by implementing this design. However, over time, it resulted in a backlash from much of the Facebook community, as such a design can generally be considered to result in a poor user experience. After many complaints in various forms — including a Facebook group entitled “No, I will NOT invite 20 friends just to add your application!” that garnered much attention — Facebook has modified its platform policy such that forced invites are strictly forbidden from use.
Parts of an Invite Form
Creating an invite form consists of several key pieces. First, you must create an fb:request-form, which is processed in order to create an HTML form that is used to invite friends. Second, an fb:multi-friend-selector is needed. This is used to render the interface that enables the end user to select his or her friends that they’d like to receive an application invitation. Finally, at least one fb:req-choice is required. This creates an action button that is used by the recipient to determine what should occur (e.g. adding the application).
Basic Invite Form Implementation
The following is a very basic invite form. Please note that $facebook represents the initialized Facebook API client object, and $user represents the user ID of the currently logged in user.
<?php
// Prepare the invitation text that all invited users will receive.
$content = <<<FBML
<fb:name uid="$user" firstnameonly="true" shownetwork="false"/> wants to know what your Favorite Games are!
<fb:req-choice url="{$facebook->get_add_url()}" label="Add Favorite Games to your profile!"/>
FBML;
?>
<fb:request-form action="http://apps.facebook.com/myapp/" method="POST" invite="true" type="Favorite Games" content="<?php echo htmlentities($content);?>">
<fb:multi-friend-selector max="20" actiontext="Here are your friends who haven't added Favorite Games to their profile. Invite them to share their Favorite Games today!" showborder="true" rows="5"></fb:request-form>
The above code creates the following output.
And, once your user clicks the “Send Invitation” button, they’ll be presented with a window similar to the following, which demonstrates how the invite request will appear when their friends receive it. Take note of the data (specifically the messages defined within the code) being populated within the form and invitation itself.
But He Already Uses This App!
If your users are going out of their way to invite their friends to use your application, it would be mutually beneficial for them to only invite friends who aren’t already using the application. Since Facebook limits the number of daily invites a user can send to friends, it would be a waste for them to invite existing users.
In order to prevent this scenario, you can take advantage of the fb:multi-friend-selector’s exclude_ids attribute. This attribute accepts a comma-delimited list of user ID’s. Any ID’s that are provided will not be available for selection to the user within the invite form.
To take advantage of this field, you’ll need to capture the list of friends who have already added the application to their profiles. This can be done with a simple FBML call, as per the following example.
<?php
// Retrieve array of friends who've already added the app.
$fql = 'SELECT uid FROM user WHERE uid IN (SELECT uid2 FROM friend WHERE uid1='.$user.') AND has_added_app=1';
$_friends = $facebook->api_client->fql_query($fql);
// Extract the user ID's returned in the FQL request into a new array.
$friends = array();
if (is_array($_friends) && count($_friends)) {
foreach ($_friends as $friend) {
$friends[] = $friend['uid'];
}
}
// Convert the array of friends into a comma-delimeted string.
$friends = implode(',', $friends);
?>
...
<fb:multi-friend-selector exclude_ids="<?php echo $friends;?>"></fb:multi-friend-selector>
...
Once we combine this new code with the previous example, we’ll have a complete invite form that allows users to invite their friends without having to worry if their inviting current application users.
<?php
// Retrieve array of friends who've already added the app.
$fql = 'SELECT uid FROM user WHERE uid IN (SELECT uid2 FROM friend WHERE uid1='.$user.') AND has_added_app = 1';
$_friends = $facebook->api_client->fql_query($fql);
// Extract the user ID's returned in the FQL request into a new array.
$friends = array();
if (is_array($_friends) && count($_friends)) {
foreach ($_friends as $friend) {
$friends[] = $friend['uid'];
}
}
// Convert the array of friends into a comma-delimeted string.
$friends = implode(',', $friends);
// Prepare the invitation text that all invited users will receive.
$content = <<<FBML
<fb:name uid="{$user}" firstnameonly="true" shownetwork="false"/> wants to know what your Favorite Games are!
<fb:req-choice url="{$facebook->get_add_url()}" label="Add Favorite Games to your profile!"/>
FBML;
?>
<fb:request-form action="http://apps.facebook.com/myapp/" method="POST" invite="true" type="Favorite Games" content="<?php echo htmlentities($content);?>">
<fb:multi-friend-selector max="20" actiontext="Here are your friends who haven't added Favorite Games to their profile. Invite them to share their Favorite Games today!" showborder="true" rows="5" exclude_ids="<?php echo $friends;?>"></fb:request-form>
Voila! Your users can now invite their friends to try out your application!
Comments
91 Responses to “Allow Your Users to Invite Their Friends”
Got something to say?
Nice write-up Matt :-)
Thanks for the examples I’ve been needing one of these for a long time. However I’m still a little stuck.
On line 4 of your last example [ $_friends = facebook->api_client->fql_query($fql); ] throws me a rather strange error, as follows:
Parse error: syntax error, unexpected T_OBJECT_OPERATOR in ….
Any suggestions?
Thanks!
First off Matt great job….
But I get that same error OMAR mentioned, I am brand new to this stuff so could you please help with that erroe …
Hey guys, sorry about that. I missed a $ before the facebook variable name. I’ve corrected the code in this tutorial. The line should be changed to this:
Hi, good write.
I gett an error code on line 20
Parse error: syntax error, unexpected ‘(’, expecting ‘}’ in on line 20
A question: Does the content have overflow problems in IE (esp. ver 7)? In my testing, the IE version will ‘crop’ the inner content of that modal-style popup that comes up after you hit the invite button. Can anyone corroborate this or tell me a fix?
[Noob Alert!] I just did a direct cut-n-paste from the plain view of the first example into a file and I’m getting an error:
Fatal error: Call to a member function get_add_url() on a non-object on line 5
Line 5 is where the call is made within the req-choice.
When I just re-formatted the PHP section by indenting the lines, I get, instead:
Parse error: syntax error, unexpected $end on line 10
Line 10 is the last line in the file.
Am I missing something really basic?
Thanks!
James - Make sure you define $facebook before trying any of the examples in this tutorial. Also, with regards to the $end error you’re receiving, make sure you don’t have any whitespace characters after
<<<FBML, and make sure you have no whitespace characters beforeFBML;.Thanks for the pointers, Matt! It’s working now!!
Thanks for this, it’s really helped a lot
I’m getting the following errors when I paste the code into my app:
$fql = ‘SELECT uid FROM user WHERE uid IN (SELECT uid2 FROM friend WHERE uid1=’.$user.’) AND has_added_app = 1′; $_friends = $facebook->api_client->fql_query($fql); $friends = array(); if (is_array($_friends) && count($_friends)) { foreach ($_friends as $friend) { $friends[] = $friend[’uid’]; } } $friends = implode(’,', $friends); $content = <<
Errors while loading page from application
Parse errors:
FBML Error (line 1112): unknown tag “FBML”
David, check out my comment above from February 23rd, 2008 7:26 am to see if that helps at all.
Matt, Thanks. My problem is that I’m picking up development on an existing app, and do not know if/where they would have defined the $facebook variable. Any thoughts on how to track that down.
David - I can’t give you the specifics on this since it depends on whether you’re using Windows, Linux or a Mac, but you’ll just want to search through the source files for $facebook.
I use TextPad on Windows myself, and when I perform a “Find In Files”, it displays the line from each file that my search string appears on. It’s very convenient, and if you have that as an option, it will certainly help you to find where $facebook is being set very quickly.
Thanks. The only like reference I can find is: $this->facebook = new Facebook($appapikey, $appsecret);
Unfortunately, I do not think the prior developers followed the recommended FB structure.
That’s typically what the Facebook API client declaration looks like. $appapikey and $appsecret should reflect the values found on the Facebook Developers apps page.
Matt, Thanks. Except for the basic fb:request-form, I can’t get it to work. Anything in the PHP section just blows up. Not sure what the problem is.
Thanks for this Matt, unfortunatly it gives me errors everytime I fix one. It gave me a line 4 error, where a ; as missing, and after fixing that, it gave me another error, it just never worked.
Any clue on why it wont work?
any idea how to track Accepted invitation?
if I would want to redirect the person that I have invited to a page in my apps how would i do that or where should i put in the url for that ?
correction :
any idea how to track Accepted invitation?
if I would want to redirect the person that I have invited to a page in my apps after they have accept and add the app how would i do that or where should i put in the url for that ?
Its very nice and usefull for me to do invite friend module, i thank a lot for your module.
Thank you very much.
I dont understand on line 18. Starting with $content = <<<FBML
What is this tag actually? Do we have to embed the FBML startup tag
matt i’m using ur code to construct the invite page but error occured again
FBML static error: Failed to fetch required static file
Help me
It’s also worth mentioning that if you have the means, you should track the user invites in a database somewhere. That way, if a user uses the invite form twice, you have the option of removing people from the list that have already been invited.
Matt, you may want to touch on this a little - with app developers trying desperately to not get blocked by people who feel they are ’spammed’ by applications, being considerate of the user experience will (hopefully) result in more genuinely interested users.
hey matt ,
how i can run this code in php4?
how about giving a php4 tutorial for this?
this code doesn’t work in my api and i don’t see anything when i try it .
how can i connect invite.php to my application .. i dunno how .. please help me .. i need it. thanks in advance
i dunno how to run this code together my own application
thanks for sharing
i tried using this but errors keeps flowing
please any one could help me doing it
thx
thanks it is very helpful but i have one doubt that How many invitation can i send per day by selecting the friends in friends list in invite friends page
i put the maximum invite application was 20, when i invite my friends i only invite 16 of my friends. why? anyone can help me … i want my max length of my invitation is 25 this is my code :
<fb:multi-friend-selector max=”20″ actiontext=”Invite your friends to use My Mini Application.” showborder=”false” exclude_ids=”" >
sorry it’s 20 not 25 .. thanks in advance :)
Create your own Facebook Application …
The other day I found a Facebook app that I was interested in putting on my profile but unfortunately it was defunct.. broken, and I was disappointed because it would be a really great app if it worked and would attract those with the same inter…
nice one, it really helpful ,
nice one, its really helpful ,
but i want ask u one more query that if i want display the score of game so ,i used friend list and app added user to and there respective score, but most important ,how include our self in that score list
help out please….
This is perfect,
I found a code before, but it had some errors, like after sending invitation, it lead to a page not found , and when clicking skip will do the same, this code is perfect man, thanx alot.
NOTE: Guys who copy the code from here, i got few errors first, till i went to all of the lines, and deleted all white spaces after lines, when u copy code from here and past to ur editor, almost all lines will have white spaces after them, so make sure its all deleted and all will work.
Matt, Ur the man
Matt
Im new to these things, any ideas for making the application famous? i see alot of things as viewing things in joiners profiles, and so on, or showing application in my own profile.
wish u can provide any idea, another thing, is there away to make application wider? or in ful screen? here is my application link: http://apps.new.facebook.com/arab-chat/
and another thing, i saw that facebook implemented new interface, and new fields shown in the settings of application after updates, if u can explain them pls.
last thing, my application was accepted in the directory, usually what category it goes? have any idea?
thanx in advance, and sorry for alot of questions
regards
Still no answers to the above?
Hello
Do u i have to change any thing with my application for the new facebook interface?
thanx
[…] Application Development - Getting Started part 1Creating your first Facebook ApplicationAllow Your Users to Invite Their FriendsFacebook […]
i upload an application named magicspell. but i need to invite my friends to view this application. i need to know where i need to put the code to execute…
ajay
Hi Matt, Great Code - Nice Job
i have put your code above into a fresh .php file named invite, changed the bits needed for my add (just text and wording) and uploaded it to my server (where the callback url points to), but i try to use it from my app i get this error;
Parse error: syntax error, unexpected T_SL in /home/benhulla/public_html/facebook-platform/client/sgforum/invite.php on line 18
looking throught the code, line 18 states:
$content = <<<FBML
any ideas? i can send the invite.php file to you if required, not a problem.
Thanks,
Ben
Hi, I’m getting this error
“Parse error: syntax error, unexpected $end in /home/fhlinux169/u/unicyclepics.co.uk/user/htdocs/FB/Chapter12/index.php on line 41″
my code looks like this.
“require_frame();
// $user = $facebook->require_login();
// $user = $facebook->require_add();
?>
Hello world.
api_client->fql_query($fql);
// Extract the user ID’s returned in the FQL request into a new array.
$friends = array();
if (is_array($_friends) && count($_friends)) {
foreach ($_friends as $friend) {
$friends[] = $friend[’uid’];
}
}
// Convert the array of friends into a comma-delimeted string.
$friends = implode(’,', $friends);
// Prepare the invitation text that all invited users will receive.
$content = <<<FBML
wants to know what your Favorite Games are!
get_add_url()}” label=”Add simplestuff to your profile!”/>
FBML;
?>
<fb:request-form action=”http://apps.facebook.com/simplestuff/” method=”POST” invite=”true” type=”simplestuff” content=”">
<fb:multi-friend-selector max=”20″ actiontext=”Here are your friends who haven’t added simplestuff to their profile. Invite them to share their simplestuff today!” showborder=”true” rows=”5″ exclude_ids=”">”
an ideas?
@Ben - This is due to an issue with whitespace pertaining to your use of the Token for Shift Left (T_SL) operator, which appears in PHP as the double less-than (<<). This error often occurs as a result of unclean heredoc syntax (<<<), in which whitespace (any space or tab) follows the identifier opener or closer.
In your code, make sure you don’t have any spaces at the end of your line of code reading “$content = <<<FBML” or at the beginning/end of your line of code reading “FBML;”
any ideas on what’s causing the error i’m getting?
“Parse error: syntax error, unexpected $end in /home/fhlinux169/u/unicyclepics.co.uk/user/htdocs/FB/Chapter12/index.php on line 41″
Where are you meant to send the submit button on the invitation panel, I sent it to the default app page but it says
“The URL http://facebook.ne14hockey.com/facebook.php returned HTTP code 200 and no data.”
You don’t mention anything about what to do after?
@pete - An error regarding $end is typically the result of something like an unclosed bracket. Essentially, PHP is looking for a matching bracket (or perhaps a matching “FBML;” to go with your “<<
@Simon - The URL you posted here doesn’t return any data. You need to have your page output something in order for something to display.
as far as i can see there are no missing brackets, the code i am using is taken from this site. all my code is listed a few post above.
please help! :)
How does one go about setting it up to where it also excludes users whom have already been invited? Can we get some code for that? Else users may get annoyed with multiple invites and complain about your app/game to Facebook. Thanx!
I’d like to know if it’s possible to have a minimum limit of invitations.
I’d like to limit to 2 minimum.
Is it possible?
Thanks and sorry my poor english.
Hi,
Using this method I can send invites to existing app users ok, but if I try to send to friends who do not already have the app they never receive the invite.
Any idea why this might be?
Thanks!
Hi Matt. Great tutorial !
Just needed some help.
Heres my code: http://pastebin.com/f3bccf20c
Errors on line 7 and line 23. Could you just check the 2 lines and tell me abt the problem?
Thanks a lot.
Hey Matt this is a great tutorial, it’s been really helpful.
I’m more of a designer than developer and aren’t quite up on my php so i was wondering if you could clear something up for me? (or anyone else if could).
I’m getting this error
Fatal error: Call to a member function fql_query() on a non-object in /home/fhlinux135/t/theseednetwork.co.uk/user/htdocs/media/facebook_application/page2.php on line 13
line 13 is this..
$_friends = $facebook->api_client->fql_query($fql);
Looking at other comments I’m guessing this is because i haven’t defined $facebook so here it goes.. i’m a noob i don’t know how to define this. Is this something to do with the api key?
What do i have to do to define $facebook and how do i go about this?
Any help would be great,
Thanks
Keith
I am having an issue with this line:
$_friends = $facebook->api_client->fql_query($fql);
I am a student and my teacher is having the same issue. I was wondering if you could help me to decipher the error that I am getting, Here is the error:
Fatal error: Cannot instantiate non-existent class: isterxmlsimplexmlimpl in /homepages/33/d175364365/htdocs/cs/students/jessica/Facebook/GiveAFlower/facebookapi_php4_restlib.php on line 1501
Thank you for your time and patients.
Jessica Uhl
This has been implemented successfully on http://www.probook.ca
Sign up and see “my account” page and click on the Facebook button on the right.
Since the code is right in the HTML, you can “view source” and copy it.
I signed up at ProBook.ca but the page has Facebook connect integration and has other links like reciver xml file.
Couls you please copy the code and post it to http://www.pastebin.com and post the link here.
Thanks.
Matt, could u help me please?
I reported this error:
Parse error: syntax error, unexpected T_STRING in D:\Inetpub\webs\savetherabbitnet\fbapps\appello.php on line 19
line 19 is: ($friends[] = $friend[’uid’];)
Tks so much! Best
$user_id = $facebook->require_login();
$query = ‘SELECT uid FROM user_id WHERE is_app_user = 1 AND uid IN (SELECT uid2 FROM friend WHERE uid1= $app_user)”;
$result = $facebook->api_client->fql_query($query);
$friends = array();
if (is_array($result) && count($result)) {
foreach ($result as $friend) {
$friends[] = $friend[’uid’];
}
}
$friends = implode(’,', $friends);
$content = <<<FBML
wants to know what your Favorite Games are!
get_add_url()}” label=”Add Favorite Games to your profile!”/>
FBML;
?>
<fb:request-form action=”http://apps.facebook.com/myapp/” method=”POST” invite=”true” type=”Favorite Games” content=”">
<fb:multi-friend-selector max=”20″ actiontext=”Here are your friends who haven’t added Favorite Games to their profile. Invite them to share their Favorite Games today!” showborder=”true” rows=”5″ exclude_ids=”">
?>
Matt, I really appreciate your tutorial and code! I’m getting the following:
Uncaught exception ‘FacebookRestClientException’ with message ‘Parser error: unexpected ‘)’ at position 70.’ in /home/lusciou/public_html/medneck/facebookapi_php5_restlib.php:2403″
That line pertains to the following code:
if (is_array($result) && isset($result[’error_code’])) {
throw new FacebookRestClientException($result[’error_msg’],
$result[’error_code’]);
Any ideas?
Form making is good but can any tell me about invitation code?
I follow your code suggestion. It works fine!
Thanks very much
However, since my application is in Chinese,
I would like to use Chinese in the invitation.
When I put in Chinese phrases in the displayed messages,
it results in wrong coding.
Can I know where I can set the charset?
I have set the language of the app to be Chinese in Developers already.
I have tried adding a line
in the code also, but it doesn’t work either.
Do you have any idea in solving the problem?
Thanks so much.
Where i can find a detailed post about how to update my application to work with new facebook?
after update my application FMBL do not show on users profile.
I wish i can make it show again.
Tanx
Great! Works like a charm! Thanx Matt
Very interested in controlling the styles (bgcolor, font color, etc.–everything) of the elements in the multi-friend selector. So far I have been discouraged. People seem to think it’s not possible to style this wonderful little component. I’m betting it can be done. Any ideas?
Hi Friends
require_frame();
$user = $facebook->require_login();
if(isset($_POST[”ids”]))
{
echo “Thank you for inviting “.sizeof($_POST[”ids”]).” of your friends on “.$app_name.”.\n”; echo “Click here to return to “.$app_name.”.”;
}
else
{
// Retrieve array of friends who’ve already authorized the app.
$fql = ‘SELECT uid FROM user WHERE uid IN (SELECT uid2 FROM friend WHERE uid1=’.$user.’) AND is_app_user = 1′;
$_friends = $facebook->api_client->fql_query($fql);
// Extract the user ID’s returned in the FQL request into a new array.
$friends = array();
if (is_array($_friends) && count($_friends))
{
foreach ($_friends as $friend)
{
$friends[] = $friend[’uid’];
}
}
// Convert the array of friends into a comma-delimeted string.
$friends = implode(’,', $friends);
// Prepare the invitation text that all invited users will receive.
//$content = “<<<FBMLhas started using “.$app_name.” and thought it’s so cool even you should try it out!\n”.”get_add_url().”\” label=\”Put “.$app_name.” on your profile\”/>FBML”;
$content = <<<FBML wants to know what your Favorite Games are! get_add_url()}” label=”Add Favorite Games to your profile!”/> FBML;
?>
<fb:request-form action=”http://apps.facebook.com/carbonbank/” method=”POST” invite=”true” type=”Favorite Games” content=”">
//——-this is my code part———
i expected user invitation window that not going to happened
whats the wrong with this app.
Thank y
aruna
I captured this error.
Fatal error: Uncaught exception ‘FacebookRestClientException’ with message ‘Parser error: unexpected ‘)’ at position 70.’
Any idea??
Hai All,
I need to find the online users of an specific application running in facebook. How do i get this???? Do we have any particular table to refer application Id.
Ex: There may be 1k of users playing “Texas HoldEm Poker game”. I need these 1k ID’s
Check : “Guess the sketch challenge” application there are two buttons. WORLD and FRIENDS. WORLD will display all the users online in the game.(Which is similar to mine)
Thanks!!!
I am giving thanks to all members of the face book
hi, do you have a version for iframe app?
Hiya Matt,
Are you availale for some development work?
This code is not working, there must be a given that I missed. Might there be a better explanation available?
Great job dear!!!
Module code seems to work… thanks so much for this. One question - I see in the code where you can adjust the number of rows. Can I adjust the number of COLUMNS to 3? Thanks in advance.
i dont know where i did wrong but this code doesnt work for me. i get the same error code as faith and vincenzo. the one on this page works just fine though:
http://wiki.developers.facebook.com/index.php/Fb:request-form
I have never got any of these to work correctly
Where do I put the script for the php invite code shown here
http://wiki.developers.facebook.com/index.php/Fb:request-form
Also cant copy the code its all out of line when doing a copy and paste
منتدى العرب يرØب بكم _ البوابة
Great article….
hi
Is there possible I redirect to different url (that is not connectiing url) after connecting my site with face book
nice code..i try to implement..but i got dis error..1 more…i need to put all the code at 1 file or need to seperate it? thanks..
Parse error: syntax error, unexpected T_SL in /home/forestin/public_html/yourzodiacone/invite.php on line 6
matt..i get error at this code..y?
$content = <<<FBML
[…] Facebook Invite Friends code […]
Thank you, I learned a lot from your tutorial. Do you have any other tutorials?
some good code there matt, worked like a charm. I was wondering if there is a way you could change the line
$fql = ‘SELECT uid FROM user WHERE uid IN (SELECT uid2 FROM friend WHERE uid1=’.$user.’) AND has_added_app = 1′;
to use Pages_isFan instead, and set a page_id somehow… basically i want the string to pick out the users who are fans of a specific page (instead of the app) and exclude in the code after that.
also, if you have any tutorials on how to track the users that invites were sent to, that would be awesome…
Hi,
i’ve try it, process running, but invitation never arrive at wall of other friend.
how could be?
thanks :)
[…] b) a Facebook invite Friends code. (here is a great article explaining how to create an Invite Facebook Friends code) […]
I am a novice here
Thanks for the code,
The code worked till the page is porperly displayed and prompt to send invites comes without errors. But, no invite actually goes to friends :(
Do I need to do something for that or am I missing something?
Frds,
Even I am facing the same problem which Sidharth is facing…
The code worked till the page is properly displayed and prompt to send invites comes without errors. But, no invite actually goes to friends :(
Do we need to do something for that or are we missing something?
-Venu
grate tutorial, it helps me very much!!
thanks a lot!!
I saw that you told someone to define $facebook before using the code. How do I do that? Thanks!
-Taylor
Thanks a lot! Above code was of great help.
From where can i get the library files to run this… i get an error when i run it.. similar to James dated 22nd Feb..
Can anyone help me out?
P.S. Also, how can we adjust the box to the new 520 pixel limit?