Allow Your Users to Invite Their Friends

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!