http://facebook-friends.com/ Facebook Docs. All In One Place.

Allow Your Users to Invite Their Friends

Written by Matt Huggins on facebook-developer.net

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).
http://facebook-friends.com/ Facebook Docs. All In One Place.

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.

1. <?php
2. // Prepare the invitation text that all invited users will receive.
3. $content = <<<FBML
4. <fb:name uid="$user" firstnameonly="true" shownetwork="false"/> wants to know what your Favorite Games
are!
5. <fb:req-choice url="{$facebook->get_add_url()}" label="Add Favorite Games to your profile!"/>
6. FBML;
7. ?>
8. <fb:request-form action="http://apps.facebook.com/myapp/" method="POST" invite="true" type="Favorite
Games" content="<?php echo htmlentities($content);?>">
9. <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.

http://facebook-friends.com/ Facebook Docs. All In One Place.

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.

1. <?php
2. // Retrieve array of friends who've already added the app.
3. $fql = 'SELECT uid FROM user WHERE uid IN (SELECT uid2 FROM friend WHERE uid1='.
$user.') AND has_added_app=1';
4. $_friends = $facebook->api_client->fql_query($fql);
5.
6. // Extract the user ID's returned in the FQL request into a new array.
7. $friends = array();
8. if (is_array($_friends) && count($_friends)) {
http://facebook-friends.com/ Facebook Docs. All In One Place.

9. foreach ($_friends as $friend) {

10. $friends[] = $friend['uid'];
11. }
12. }
13.
14. // Convert the array of friends into a comma-delimeted string.
15. $friends = implode(',', $friends);
16. ?>
17. ...
18. <fb:multi-friend-selector exclude_ids="<?php echo $friends;?>"></fb:multi-friend-
selector>
19. ...

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.

1. <?php
2. // Retrieve array of friends who've already added the app.
3. $fql = 'SELECT uid FROM user WHERE uid IN (SELECT uid2 FROM friend WHERE uid1='.
$user.') AND has_added_app = 1';
4. $_friends = $facebook->api_client->fql_query($fql);
5.
6. // Extract the user ID's returned in the FQL request into a new array.
7. $friends = array();
8. if (is_array($_friends) && count($_friends)) {
9. foreach ($_friends as $friend) {
10. $friends[] = $friend['uid'];
11. }
12. }
13.
14. // Convert the array of friends into a comma-delimeted string.
15. $friends = implode(',', $friends);
16.
17. // Prepare the invitation text that all invited users will receive.
18. $content = <<<FBML
19. <fb:name uid="{$user}" firstnameonly="true" shownetwork="false"/> wants to know
what your Favorite Games are!
20. <fb:req-choice url="{$facebook->get_add_url()}" label="Add Favorite Games to your
profile!"/>
21. FBML;
22. ?>
23. <fb:request-form action="http://apps.facebook.com/myapp/" method="POST"
invite="true" type="Favorite Games" content="<?php echo htmlentities($content);?>">
http://facebook-friends.com/ Facebook Docs. All In One Place.

24. <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!

Thanks to Mat and facebook-developer.net

Get more related articles at: http://facebook-friends.com/

Cheers!