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
38 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?