Ta strona używa ciasteczek (cookies), dzięki którym nasz serwis może działać lepiej. Dowiedz się więcej OK, rozumiem
WebHelp.pl Warsztat Artykuły Facebook - tworzenie aplikacji: zaproszenia

Warsztat / Artykuły i tutoriale

Facebook - tworzenie aplikacji: zaproszenia

Bartosz Romanowski 16 grudnia 2010 komentarze ()

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:

Facebook - zaproszenia

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

Facebook - zaproszenia

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.

Inne artykuły na ten temat

Facebook - tworzenie aplikacji: pierwsza aplikacja Facebook - tworzenie aplikacji: zezwolenia i korzystanie z API Facebook: automatyczne dodawanie wpisów na stronie Facebook - tworzenie aplikacji: real-time updates

Masz pytania lub wątpliwości? Odwiedź nasze forum dyskusyjne.

Bartosz Romanowski

Programista, gadżeciarz, krytyczny miłośnik produktów Apple, fan ciężkich brzmień i niepoprawny pesymista.


Komentarze


HTML CSS JavaScript PHP bazy danych MySQL Flash grafika framework hosting domeny pozycjonowanie wordpress Facebook