Największą siłą Facebooka jest olbrzymia baza użytkowników, którzy polecają sobie nawzajem
interesujące aplikacje. W tym artykule dowiemy się jak zaimplementować system zaproszeń, za
pomocą których wieść o naszym dziele rozejdzie się po świecie.
Na pewno każdy użytkownik

Facebooka

miał styczność z zaproszeniami, gdyż większość

popularnych aplikacji udostępnia swoim użytkownikom możliwość ich wysyłania. Otrzymane
zaproszenia można znaleźć na specjalnej

stronie

, tam też mamy możliwość ich przyjęcia lub

usunięcia.

Tworzenie formularza do wysyłania zaproszeń
Dodanie do naszej aplikacji funkcji wysyłania zaproszeń nie jest takie trudne jak mogłoby się
wydawać, ponieważ

Facebook

oferuje kilka gotowych komponentów w postaci znaczników

FBML, które znacznie ułatwią nam to zadanie. Najważniejszym z nich jest fb:request-form,
czyli formularz wysyłania zaproszeń. Trzeba dodać, że jest to jeden z tych znaczników, które trzeba
umieszczać (zgodnie z zaleceniami Facebooka) wewnątrz znacznika fb:serverFbml.
Oczywiście sam formularz nie załatwia sprawy - aby był on w pełni funkcjonalny musimy
wyposażyć go w jakąś metodę wyboru adresatów, co umożliwiają nam znaczniki fb:multi-
friend-selector i fb:friend-selector.
Kod najprostszego formularza do wysyłania zaproszeń może wyglądać na przykład tak:
Kod:

Zaznacz cały

<fb:serverFbml>
<script type="text/fbml">

<fb:fbml>
<fb:request-form

action="http://nasza-domena.pl/skrypt.php"
method="POST"

invite="true"
type="Nazwa aplikacji"

content="Zapraszam do świetnej aplikacji <fb:req-choice
url='http://apps.facebook.com/nasza_aplikacja/' label='Nasza aplikacja'

/>">
<fb:multi-friend-selector style="width: 300px"

showborder="false"
condensed="true"

actiontext="Zaproś swoich znajomych do używania tej
aplikacji." />

<fb:request-form-submit />
</fb:request-form>

</fb:fbml>
</script>

</fb:serverFbml>

Znacznik fb:request-form posiada kilka parametrów, których przeznaczenie może być nie do
końca jasne. Parametr action to adres pliku, do którego zostanie przekierowany użytkownik po
wysłaniu zaproszeń. Ważne jest, że to adres na naszym serwerze, a nie adres aplikacji w serwisie
Facebook. Parametr type to nazwa, która zostanie dodana do tekstu na przycisku wysyłania
zaproszeń - w naszym przykładzie tekst ten będzie brzmiał tak: "Wyślij zaproszenie Nazwa
aplikacji" (oczywiście stały fragment tekstu jest zależny od wybranej wersji językowej). Parametr
content to treść zaproszenia, ale nie tylko. W parametrze tym przekazujemy również znacznik
fb:req-choice, który określa gdzie zostanie przekierowany użytkownik, który zaakceptuje
zaproszenie (adres URL aplikacji w serwisie Facebook). Jeśli pominiemy ten znacznik, zamiast
"Akceptuj" przycisk akceptacji zaproszenia będzie miał opis "Idź do aplikacji Nazwa aplikacji", a

po jego kliknięciu użytkownik zostanie skierowany do strony głównej naszej aplikacji. Trzeba
przyznać, że zostało to rozwiązane w dość dziwny sposób, ale tak to działa, więc trzeba się po
prostu przyzwyczaić. Parametr invite określa czy wysłane przez nas zaproszenie ma być
zaproszeniem. Brzmi dziwnie i jest dziwne, bo jeśli ustawimy wartość tego parametru na false, to
otrzymane przez adresata zaproszenie będzie różnić się tylko standardowym tekstem ("[imię i
nazwisko] zaprosił(a) Cię do aplikacji" zamiast "[imię i nazwisko] wysłał(a) Ci zaproszenie do
aplikacji").
Wewnątrz znacznika fb:request-form znajduje się znacznik fb:multi-friend-
selector, odpowiedzialny za wyświetlenie pól wyboru adresatów zaproszenia. W powyższym
przykładzie skorzystaliśmy z jego wersji skondensowanej (parametr condensed), która jest
bardziej przejrzysta i (co ważniejsze) mniejsza. Wymaga również znacznika fb:request-
form-submit, który wyświetla przycisk służący do wysłania zaproszeń (wersja pełna wyświetla
go domyślnie). Jak widać, wygląd znacznika fb:multi-friend-selector można
modyfikować używając styli.
Efektem zamieszczenia w naszej aplikacji powyższego kodu będzie taki formularz:

Jeśli zmienimy wartość parametru condensed na false lub całkowicie usuniemy go z kodu,
formularz będzie wyglądał tak:

Zamiast fb:multi-friend-selector możemy użyć znacznika fb:friend-selector,
który wyświetli nam pole formularza, w którym możemy wpisać imię i nazwisko użytkownika. Jest
to jednak zdecydowanie mniej wygodne, no i pozwala na jednoczesny wybór tylko jednego
adresata.
Znacznik fb:multi-friend-selector posiada jeszcze kilka parametrów, których nie
użyliśmy w zamieszczonym wyżej przykładzie. Do manipulacji wyglądem formularza służą
atrybuty rows (ilość wierszy na liście wyboru znajomych; od 3 do 10), max (maksymalna liczba
jednocześnie wybranych osób; od 1 do 35), cols (liczba kolumn na liście znajomych; 2, 3 lub 5) i
bypass (określa tekst przycisku pomijającego wysłanie zaproszeń; step, cancel lub skip).
Natomiast do zmiany sposobu działania formularza służą parametry email_invite i
exclude_ids. Parametr email_invite określa czy po wysłaniu zaproszeń ma pojawić się
dodatkowe okno z propozycją wysłania zaproszeń za pośrednictwem poczty e-mail. Warto ustawić
go na false, ponieważ domyślnie jest on włączony. Parametr exclude_ids może zawierać listę
identyfikatorów użytkowników, którzy nie mają być wyświetlani na liście w formularzu wyboru
adresatów zaproszeń. Można tego użyć do wykluczenia osób, które już korzystają z aplikacji lub
osób, które już otrzymały zaproszenia. W obu przypadkach Facebook nie udostępnia żadnych
łatwych do wykorzystania mechanizmów - w pierwszym można skorzystać z danych, które
wyciągniemy za pośrednictwem

FQL

, w drugim niestety trzeba będzie samemu zapisywać gdzieś

identyfikatory użytkowników, którzy otrzymali zaproszenie.

Pobieranie danych za pomocą FQL

FQL

(Facebook Query Language) to interfejs pozwalający na dostęp do danych udostępnianych

przez

Graph API

za pomocą języka zbliżonego do SQLa. Ma on kilka ograniczeń, na przykład

możliwość umieszczenia w klauzuli FROM tylko jednej tabeli, ale ma również wiele zalet, do
których należą między innymi większa szybkość działania w porównaniu do interfejsów

Graph API

oraz możliwość wykonania kilku zapytań

FQL

w jednym wywołaniu API. Nie będę rozpisywał się

na temat FQLa, bo to temat na osobny artykuł - zainteresowani mogą poczytać o nim w

dokumentacji

.

Aby otrzymać listę znajomych, którzy już korzystają z naszej aplikacji, można posłużyć się takim
kodem:
Kod:

Zaznacz cały

// to można pominąć jeśli wcześniej już pobraliśmy dane użytkownika
$me = $facebook->api('/me');

$fql = 'SELECT uid FROM user WHERE uid IN (SELECT uid2 FROM friend WHERE

uid1 = '.$me['id'].') AND is_app_user = 1';
$params = array('method' => 'fql.query',

'query' => $fql,
'callback' => '');

$_friends = $facebook->api($params);
$friends = array();

if (is_array($_friends) && count($_friends))
{

foreach ($_friends as $friend)
$friends[] = $friend['uid'];

}
$friends = implode(',', $friends);

W wyniku działania tego kodu otrzymujemy listę identyfikatorów oddzieloną przecinkami
($friends), którą możemy umieścić w parametrze exclude_ids elementu fb:multi-
friend-selector:
Kod:

Zaznacz cały

<fb:multi-friend-selector style="width: 300px"
exclude_ids="<? echo($friends); ?>"

showborder="false"
condensed="true"

actiontext="Zaproś swoich znajomych do używania tej aplikacji." />
<fb:request-form-submit />

Tym sposobem wyświetlony formularz nie będzie zawierał tych osób, które już korzystają z naszej
aplikacji.

Tworzenie listy wysłanych zaproszeń
Teraz zajmiemy się rzeczą nieco bardziej skomplikowaną, czyli badaniem kto i komu wysyłał
zaproszenia. Możemy to zastosować na przykład do wykluczenia z formularza osób, którym
użytkownik już wysłał zaproszenie albo do stworzenia na potrzeby naszej aplikacji prostego
"programu partnerskiego", bazującego na ilości osób "poleconych" (czyli takich, które zaczęły
używać aplikacji za pośrednictwem zaproszenia od danego użytkownika). Jak już napisałem wyżej,
Facebook nie udostępnia mechanizmów do tego typu zastosowań, tak więc będziemy musieli
napisać sobie własny.
Do przechowywania danych o wysłanych zaproszeniach wykorzystamy bazę danych

MySQL

. W

tym celu stworzymy sobie prostą tabelę o następującej strukturze:
Kod:

Zaznacz cały

CREATE TABLE `fb_invites` (
`sender_id` bigint(20) unsigned NOT NULL,

`recipient_id` bigint(20) unsigned NOT NULL,
`created_time` datetime NOT NULL,

PRIMARY KEY (`sender_id`,`recipient_id`)

);

Jak już wcześniej wspomniałem, parametr action znacznika fb:request-form zawiera adres
URL skryptu, na jaką zostanie przekierowany użytkownik po wysłaniu zaproszeń. Do tego skryptu
metodą $_POST zostanie przekazana między innymi tablica ids, zawierająca identyfikatory
użytkowników, do których zostały wysłane zaproszenia. Na jej podstawie zapiszemy sobie do bazy
potrzebne nam informacje.
Kod:

Zaznacz cały

if(is_array($_POST['ids']) && count($_POST['ids']))

{
foreach($_POST['ids] as $id)

{
// IGNORE na wypadek gdyby z jakichś powodów istniał już taki

rekord
$sql = "INSERT IGNORE INTO fb_invites (sender_id, recipient_id,

created_time) VALUES(".(int)$me['id'].", ".(int)$id.", NOW())";
$result = mysql_query($sql) or die(mysql_error());

}
}

Teraz aby wyciągnąć z bazy osoby, do których użytkownik wysłał już zaproszenia, wystarczy
zrobić coś takiego:
Kod:

Zaznacz cały

$sql = "SELECT recipient_id FROM fb_invites WHERE sender_id = ".(int)
$me['id'];

$result = mysql_query($sql) or die(mysql_error());
$exclude = array();

while($row = mysql_fetch_array($result))
{

$exclude[] = $row['recipient_id'];
}

$exclude = implode(',', $exclude);

Następnie aby wykluczyć te osoby z formularza wysyłania zaproszeń, zmodyfikujemy zawartość
parametru exclude_ids:
Kod:

Zaznacz cały

exclude_ids="<? echo($friends); ?>,<? echo($exclude); ?>"

Tym sposobem mamy listę znajomych, z której zostały usunięte osoby już korzystające z naszej
aplikacji oraz osoby, do których użytkownik już wysłał zaproszenia.
Jak wspomniałem wyżej, nasz prosty mechanizm możemy wykorzystać na przykład do sprawdzenia
ile osób zaczęło korzystać z naszej aplikacji z polecenia konkretnego użytkownika. Możemy
również (po niewielkich modyfikacjach) udostępnić wysyłanie wirtualnych przedmiotów, tak jak
ma to miejsce w licznych grach działających na platformie Facebook. W obu przypadkach musimy
skądś wiedzieć, kto wysłał zaproszenie, przez które użytkownik trafił do naszej aplikacji. Możemy
do tego wykorzystać parametr url znacznika fb:req-choice. Dodamy do niego zmienną
referer_id, która będzie zawierała identyfikator użytkownika wysyłającego zaproszenie:
Kod:

Zaznacz cały

<fb:req-choice url='http://apps.facebook.com/nasza_aplikacja/?referer_id=<?

echo($me['id']); ?>' label='Nasza aplikacja' />

Oczywiście do tego adresu możemy dodać dowolną ilość własnych zmiennych, które później
obsłużymy w naszej aplikacji. Może to być na przykład identyfikator wirtualnego przedmiotu, który
jeden użytkownik "wysłał" drugiemu za pomocą zaproszenia. My jednak na potrzeby niniejszego
artykułu ograniczymy się do oznaczenia zaproszenia w tabeli fb_invites jako wykorzystanego,
dzięki czemu łatwo będziemy mogli określić z czyjego polecenia użytkownik trafił do naszej
aplikacji.
Najpierw dodamy sobie do naszej tabeli fb_invites jedno pole, określające czy dane
zaproszenie zostało "odebrane":
Kod:

Zaznacz cały

ALTER TABLE `fb_invites` ADD `accepted` CHAR(1) NOT NULL DEFAULT 'N';

Następnie dopiszmy kawałek kodu, który zaktualizuje nowe pole w momencie wejścia użytkownika
do naszej aplikacji za pośrednictwem zaproszenia:
Kod:

Zaznacz cały

if(isset($_GET['referer_id']) && !empty($GET['referer_id']))

{
$referer_id = (int)$_GET['referer_id'];

$sql = "UPDATE fb_invites SET accepted = 'Y' WHERE sender_id = ".
$referer_id." AND recipient_id = ".(int)$me['id'];

$result = mysql_query($sql) or die(mysql_error());
}

Oczywiście można (a nawet powinno się) najpierw sprawdzić czy zaproszenie w ogóle istnieje, czy
nie zostało już "wykorzystane" itp., ale nie to jest tematem tego tekstu.
Teraz mamy wszystkie dane niezbędne do określenia ilości osób "poleconych" przez daną osobę lub
prostego rankingu najlepszych "polecających":
Kod:

Zaznacz cały

// ilość "poleconych" użytkowników
$sql = "SELECT COUNT(*) FROM fb_invites WHERE sender_id = ".(int)

$me['id']." AND accepted = 'Y'";

Kod:

Zaznacz cały

// prosty ranking dziesięciu najlepszych "polecających"

$sql = "SELECT sender_id, COUNT(*) AS suma FROM fb_invites WHERE sender_id
= ".(int)$me['id']." AND accepted = 'Y' GROUP BY sender_id ORDER BY suma

DESC LIMIT 10";

Znamy już mechanizm wysyłania zaproszeń i odbierania "przemyconych" w nich danych. Jak
widać na powyższych prostych przykładach, możliwości są ograniczone tylko wyobraźnią twórców.
Warto podejrzeć jak zaproszenia wykorzystują największe aplikacje czy gry działające na
platformie

Facebook

i spróbować zaimplementować ich rozwiązania we własnej aplikacji.

UWAGA! Trzeba pamiętać, że zamieszczone powyżej przykłady mają charakter
poglądowy i nie powinno się ich stosować na zasadzie "kopiuj-wklej" w ogólnie
dostępnych aplikacjach.