Niniejszy artykuł jest pierwszym z cyklu tekstów poświęconych tworzeniu aplikacji
zintegrowanych z platformą

Facebook

z wykorzystaniem

PHP

i

JavaScript

.

Facebook sukcesywnie zdobywa popularność w Polsce i coraz więcej twórców aplikacji decyduje
się na integrację swoich serwisów z tą platformą lub tworzenie zupełnie nowych projektów, w pełni
wykorzystujących potencjał jaki daje udostępniane przez amerykańskiego giganta API oraz rosnąca
z dnia na dzień baza użytkowników. W cyklu poświęconym tworzeniu aplikacji "facebookowych"
postaram się omówić większość zagadnień związanych z wykorzystaniem tej platformy w sposób
(mam nadzieję) przystępny nawet dla średnio zaawansowanego programisty.

Rejestracja aplikacji
Pierwszym krokiem, jaki musimy zrobić na długiej drodze do własnej działającej aplikacji, jest jej
rejestracja w serwisie Facebook. Służy do tego specjalna

strona

, na której musimy podać kilka

podstawowych informacji dotyczących naszego dzieła. Zaczynamy od wybrania nazwy dla naszej
aplikacji oraz potwierdzenia naszej zgody na przestrzeganie zasad Facebooka.

Po utworzeniu aplikacji zostaniemy przeniesieni na stronę, na której będziemy mogli dokonać
szczegółowej konfiguracji. Warto poświęcić chwilę na przestudiowanie poszczególnych pól
formularzy, bo niektóre z nich okażą się później dosyć istotne.
W zakładce "Informacje" znajdziemy podstawowe dane dotyczące naszej aplikacji. Większość pól
formularza nie wymaga szczegółowego omówienia. Wyjątkiem jest sekcja "Twórcy aplikacji", którą
jednak zajmiemy się nieco później. Warto również podać odpowiednie adresy w polach "Adres
Polityki Prywatności" i "Warunki usługi URL" - będą one wyświetlane użytkownikowi w
okienkach z prośbami o dodatkowe zezwolenia.
Najważniejszym parametrem naszej nowej aplikacji jest Application ID, czyli unikalny
identyfikator, za pomocą którego będziemy "przedstawiać się" facebookowemu API. Jest on jawny
(widać go na przykład w adresie profilu aplikacji) i nie ma potrzeby ani sensu go ukrywać. Drugim,
nie mniej istotnym parametrem, jest Application Secret. Ten unikalny ciąg znaków służy do
autoryzacji aplikacji na platformie Facebook. Nie należy go nikomu podawać, umieszczać w kodzie

HTML

czy

JavaScript

, ani w plikach tekstowych na serwerze - jeśli ktoś go pozna, bez większego

trudu będzie mógł podszyć się pod naszą aplikację. Generalnie znać go powinniśmy my, nasza
aplikacja i Facebook - nikt więcej. Oba parametry służące do identyfikacji naszej aplikacji
znajdziemy w zakładkach Web Site i Facebook Integration.
Dalsze czynności zależą od tego, w jaki sposób nasza aplikacja ma zostać zintegrowana z
Facebookiem. Można to ogólnie rzecz biorąc zrobić na dwa sposoby, które nie różnią się
szczególnie z punktu widzenia konstrukcji samej aplikacji, ale działają nieco inaczej z punktu
widzenia użytkownika. Pierwsza metoda zakłada, że aplikacja działa w ramach serwisu Facebook i
ma adres typu apps.facebook.com/nazwa_aplikacji/. Nie działa ona jednak na serwerach Facebooka,
a jest jedynie ładowana do ramki (IFrame), która znajduje się na stronie aplikacji. Gdy użytkownik
otwiera stronę aplikacji, Facebook ładuje aplikację z naszego serwera, dokładając do jej adresu
URL kilka własnych zmiennych. Wygląda to mniej więcej tak:
Kod:

Zaznacz cały

http://nasza-domena.pl/aplikacja/?
fb_sig_in_iframe=1&fb_sig_locale=pl_PL&fb_sig_in_new_facebook=1&fb_sig_time

=1288986321.9187&fb_sig_added=0&fb_sig_country=pl&fb_sig_api_key=202fd34e01
7bd9d3fe222a8127e31d23&fb_sig_app_id=109678625711111&fb_sig=aa26ead21b7e40c

3186e1aa4a13a36a1

Druga metoda zakłada, że integrujemy zewnętrzną aplikację z platformą Facebook bez
"podpinania" jej pod sam serwis. Integracja taka daje nam niemal takie same możliwości jak
integracja pierwszą metodą, ale wymaga nieco innej konfiguracji. Warto dodać, że aplikacja
zintegrowana pierwszą metodą powinna działać również po bezpośrednim wywołaniu z
pominięciem Facebooka. Co więcej, tą samą aplikację możemy udostępniać na oba sposoby (za
przykład niech posłuży popularna gra Mafia Wars, dostępna pod dwoma adresami:
http://apps.facebook.com/inthemafia/ i http://mafiawars.com).

Jeśli chcemy, aby nasza aplikacja działała w ramach serwisu Facebook musimy przejść do zakładki
Facebook Integration i ustawić kilka istotnych parametrów. Canvas Page to unikalny adres naszej
aplikacji w serwisie. W polu Canvas URL podajemy adres URL naszej aplikacji na naszym
serwerze (jak już wspomniałem wcześniej, będzie ona ładowana do ramki na stronie aplikacji).
Parametr Canvas Type określa sposób, w jaki nasza strona będzie ładowana przez Facebooka.
Wybieramy "Pływająca ramka" (czyli wspomniana wcześniej IFrame). Warto przy okazji
wspomnieć, że zgodnie z

wpisem

na blogu dla deweloperów, aplikacje FBML będą akceptowane

tylko do końca 2010 roku, tak więc pominę je w niniejszym tekście całkowicie, mimo że temat
samego FBML omówię nieco później. Parametr Rozmiar IFrame może przyjąć dwie wartości:
Show scrollbars i Auto-resize. W przypadku wybrania pierwszego z nich, ramka będzie miała stały
rozmiar, niezależnie od wielkości dokumentu do niej załadowanego. W przypadku wybrania drugiej
możliwości, ramka będzie dostosowywała swój rozmiar do rozmiaru załadowanego dokumentu.
Polecam wybrać drugą opcję. Pozostałe pola nie są dla nas w tym momencie istotne.

Jeśli chcemy zintegrować zewnętrzną aplikację z Facebookiem (druga z omówionych wyżej
metod), musimy zajrzeć do zakładki Web Site. Tam wypełniamy pole Site URL, w którym
powinniśmy wpisać adres strony, na której chcemy korzystać z integracji z Facebookiem. Jeśli
nasza aplikacja korzysta z subdomen, konieczne będzie również wypełnienie pola Site Domain.
Gdy podamy tam nazwę naszej domeny, użytkownicy, którzy zalogowali się przy użyciu
Facebooka, pozostaną zalogowanymi również na stronach znajdujących się w subdomenach
domeny głównej.
Pozostała nam jeszcze tajemnicza zakładka Advanced. Znajdują się w niej (jak sama nazwa
wskazuje) nieco bardziej zaawansowane opcje, z których części na pewno skorzystamy. Na
początek jednak interesuje nas tylko jedna z nich: Sandbox Mode. Jeśli przełączymy naszą
aplikację w tryb Sandbox (wybierzemy opcję Zezwól), to tylko użytkownicy dodani jako twórcy
aplikacji będą mogli się do niej zalogować (lub w ogóle wejść na jej stronę - jeśli działa w ramach
serwisu Facebook). Ma to na celu ukrycie tworzonej właśnie aplikacji przed nieupoważnionymi
użytkownikami. Aby dodać odpowiednie osoby do grupy twórców musimy przejść do zakładki
Informacje, na której dole znajduje się sekcja Twórcy aplikacji. Niestety, dodawać możemy tylko
osoby, które znajdują się na liście naszych znajomych, co jest szczególnie uciążliwe w przypadku
kont testowych.

Konta testowe
Skoro już jesteśmy przy kontach testowych, to warto napisać na ich temat kilka słów. Każde zwykłe
konto w serwisie Facebook można oznaczyć jako konto testowe (służy do tego specjalna

strona

),

co wiąże się automatycznym przypisaniem tego konta do sieci Facebook Platform Developer Test
Accounts.

Kont takich możemy założyć dowolną ilość, co przydaje się na przykład do testowania procesu
wysyłania zaproszeń. Trzeba jednak pamiętać, że konta testowe nie mają dostępu do aplikacji firm
zewnętrznych ani do rzeczywistych kont użytkowników. Nie mogą również tworzyć aplikacji, tak
więc aby wykorzystać je do testów należy dodać je do grupy twórców, co również nie jest takie
proste, ponieważ konta testowe nie widzą rzeczywistych aplikacji. Aby to zrobić należy wykonać
następujące działania (znalezione na

forum

dla twórców aplikacji):

1. Założyć konto testowe, ale nie oznaczać go jeszcze jako testowego. Jeśli konto testowe już

istnieje, zmienić je na konto rzeczywiste (czyli opuścić sieć Facebook Platform Developer
Test Accounts).

2. Dodać to konto do listy znajomych.
3. Dodać to konto do listy twórców aplikacji.
4. Ustawić konto jako konto testowe.
5. Usunąć je z listy znajomych.

Ponieważ nasza aplikacja znajduje się w trybie Sandbox, nikt poza osobami dodanymi do grupy
twórców nie będzie miał do niej dostępu. Dodam gwoli ścisłości, że wcale nie ma obowiązku
korzystania z kont testowych. Są one ułatwieniem dla deweloperów, którzy nie mają dostępu do
wystarczającej do testów ilości kont rzeczywistych (pamiętajmy, że jedna osoba może założyć tylko
jedno konto w serwisie Facebook).
Po zapisaniu wszystkich wprowadzonych zmian pora na stworzenie właściwej aplikacji, która
zostanie zintegrowana z Facebookiem. Zakładam, że masz co najmniej podstawową wiedzę z
zakresu programowania w

PHP

i

JavaScript

- jeśli jest inaczej, to czytanie dalszej części tego tekstu

może nie mieć większego sensu. Musisz również posiadać dostęp do jakiegoś serwera, na którym
umieścisz swoją aplikację. Prawdopodobnie do celów testowych wystarczy jakiś darmowy, ale jeśli
planujesz udostępnić swoją aplikację publicznie, to raczej powinieneś wybrać ofertę komercyjną
(przegląd ofert znajdziesz na przykład w naszym dziale

Hosting i domeny

).

Graph API i REST API
Facebook udostępnia interfejs programistyczny

Graph API

, który umożliwia dostęp do niemal

wszystkich danych publikowanych przez użytkowników w serwisie. Daje również możliwość
zamieszczania przez aplikację różnego rodzaju wpisów, a także interakcji pomiędzy użytkownikami
(na przykład za pomocą zaproszeń). Wciąż dostępne jest także stare

REST API

, głównie dlatego, że

jeszcze nie wszystkie jego funkcjonalności zostały przeniesione do Graph API, a także przez
wzgląd na działające aplikacje korzystające ze starszych interfejsów. Na koniec 2010 roku

planowane jest wyłączenie

niektórych metod REST API, ale nie są to metody kluczowe z punktu

widzenia twórców aplikacji.

Pierwsze kroki z SDK
W

repozytorium

Facebooka znaleźć możemy SDK dla różnych języków programowania, dzięki

którym możemy korzystać z API serwisu w praktycznie dowolnej aplikacji działającej na niemal
dowolnej platformie. Nas interesuje

PHP SDK

, które pobrać możemy

stąd

. W archiwum znajduje

się przykładowy skrypt korzystający z API (w katalogu "examples") oraz najistotniejszy dla nas
plik - facebook.php (w katalogu "src"). Należy go skopiować na serwer do katalogu, w którym
chcemy utworzyć nasz projekt. Teraz w tym samym katalogu utworzymy plik index.php, który
zawierać będzie następujący kod:
Kod:

Zaznacz cały

require('facebook.php');

$facebook = new Facebook(array(
'appId' => 'nasze_application_id',

'secret' => 'nasz_application_secret',

'cookie' => true,
));

W tym fragmencie naszej nowej aplikacji tworzymy obiekt $facebook, za pomocą którego
będziemy komunikować się z API Facebooka. Oczywiście należy pamiętać o podaniu poprawnych
wartości parametrów 'appId' i 'secret' (zostały one opisane wcześniej). Teraz pora na
pobranie informacji o użytkowniku, który właśnie przegląda naszą stronę.
Kod:

Zaznacz cały

// pobieramy informacje o sesji
$session = $facebook->getSession();

$me = null;

if ($session) {
try {

// pobieramy informacje o użytkowniku
$uid = $facebook->getUser();

$me = $facebook->api('/me');
} catch (FacebookApiException $e) {

error_log($e);
}

}

// zobaczmy jakie dane użytkownika dostaliśmy
var_dump($me);

Najpierw musimy sprawdzić, czy użytkownik jest zalogowany do naszej aplikacji. Przez
"zalogowanie" rozumiemy umożliwienie aplikacji dostępu do podstawowych danych użytkownika -
czyli coś, o co pyta praktycznie każda facebookowa aplikacja podczas pierwszego jej użycia. Do
tego sprawdzenia posłuży nam metoda getSession(), która zwraca informacje o sesji
użytkownika. Jeśli użytkownik nie logował się wcześniej do naszej aplikacji lub jego sesja jest
uszkodzona, metoda zwraca NULL. Jeśli dostaliśmy dane sesji, możemy pobrać informacje o
samym użytkowniku. Metoda getUser() zwraca identyfikator użytkownika, który będziemy
trzymać w zmiennej $uid (przyda nam się później). Natomiast do zmiennej $me trafią dane
użytkownika, do których mamy aktualnie dostęp.
Tutaj zatrzymamy się na chwilę aby omówić dwie kwestie. Po pierwsze zwróćmy uwagę na
zmienną $me. Będzie nam ona służyła w dalszej części aplikacji do sprawdzania czy użytkownik
jest zalogowany, a co za tym idzie czy możemy wywoływać dla niego funkcje API. Wprawdzie jeśli
wywołamy jakąś funkcję dla niezalogowanego użytkownika, to zostanie po prostu rzucony wyjątek,
który możemy przechwycić, ale znacznie szybciej jest po prostu nie wywoływać tej funkcji w
ogóle. Po drugie zwróćmy uwagę na metodę api(). Jak nietrudno się domyślić, metoda ta służy
do wywoływania funkcji API. Warto dodać, że działa ona zarówno dla Graph API, jak i dla
starszego REST API. Różnice w sposobie korzystania z obu interfejsów omówimy sobie później.

Logowanie użytkownika
Oczywiście przy pierwszym załadowaniu naszej aplikacji nie dostaniemy żadnych danych
użytkownika (w tym wypadku naszych), bo jeszcze nie zezwolił on aplikacji na dostęp do nich.
Trzeba więc w jakiś sposób umożliwić zalogowanie do aplikacji. Możemy to zrobić na kilka
sposobów, z których najwygodniejsze są dwa: stworzenie odpowiedniego linku z wykorzystaniem
PHP SDK lub stworzenie odpowiedniego przycisku z wykorzystaniem JavaScript SDK i
XFBML.
Aby utworzyć link do zalogowania z wykorzystaniem PHP SDK wystarczy skorzystać z metody

getLoginUrl().
Kod:

Zaznacz cały

<?
// stworzenie linku do logowanie z wykorzystaniem PHP SDK

if (!$me) {
$loginUrl = $facebook->getLoginUrl();

}
?>

<a href="<? echo($loginUrl); ?>">zaloguj</a>

Warto dodać, że jeśli chcemy, aby użytkownik musiał zalogować się zanim dostanie dostęp do
naszej aplikacji, to możemy go od razu przekierować pod URL otrzymany z funkcji
getLoginUrl() z parametrem 'next', w którym powinien znaleźć się adres, na jaki zostanie
przekierowany zalogowany użytkownik:
Kod:

Zaznacz cały

$loginUrl = getLoginUrl(array('next' =>

'http://apps.facebook.com/nasza_aplikacja'));

Jeśli chcemy używać JavaScript SDK, to najpierw musimy zainicjować samo SDK, a dopiero
potem możemy z niego skorzystać.
Kod:

Zaznacz cały

<!doctype html>

<html xmlns:fb="http://www.facebook.com/2008/fbml">
<head>

<title>Nasza aplikacja</title>
</head>

<body>
<div id="fb-root"></div>

<script>
window.fbAsyncInit = function() {

// inicjalizacja JavaScript SDK
FB.init({

appId : '<? echo($facebook->getAppId()); ?>',
session : <? echo(json_encode($session)); ?>,

status : true,
cookie : true,

xfbml : true // włączamy parsowanie XFBML
});

// jeśli użytkownik zaloguje się, odświeżamy stronę

FB.Event.subscribe('auth.login', function() {
window.location.reload();

});
};

(function() {

var e = document.createElement('script');
e.src = document.location.protocol +

'//connect.facebook.net/pl_PL/all.js';
e.async = true;

document.getElementById('fb-root').appendChild(e);
}());

</script>

<!-- stworzenie przycisku do logowania z wykorzystaniem JS SDK i XFBML
-->

<? if (!$me) : ?>

<fb:login-button></fb:login-button>
<? endif; ?>

Na pierwszy rzut oka druga metoda wymaga znacznie większej ilości kodu, ale to mylne wrażenie.
Jak można zauważyć, większość miejsca zajmuje inicjalizacja JavaScript SDK oraz (trochę
nietypowy) nagłówek HTML. Samo utworzenie na stronie aplikacji przycisku do zalogowania to
tak naprawdę wynik działania znacznika <fb:login-button>. JavaScript SDK daje spore
możliwości, tak więc możemy używać go do wielu innych rzeczy, nie tylko do tak trywialnych
zadań jak tworzenia przycisku logowania. Dodam jeszcze dla jasności, że w funkcji FB.init()
nie trzeba korzystać z danych pobranych przez PHP SDK - można podać appID tak samo jak w
przypadku tworzenia obiektu $facebook w PHP i pominąć parametr 'session' (zostanie
utworzona nowa sesja).
Warto również zadbać o odpowiednią wersję językową SDK, która jest podawana w URLu, z
którego ładowane są skrypty JS. Wystarczy podmienić pl_PL na zawartość odpowiedniej
zmiennej. Jeśli stworzyliśmy aplikację działającą w IFrame, to język użytkownika przekazywany
jest przez URL w zmiennej fb_sig_locale. Niezależnie od tego język zalogowanego do
aplikacji użytkownika dostajemy razem z jego danymi (w naszym przypadku będzie to zmienna
$me['locale']).
Gwoli wyjaśnienia kilka słów na temat FBML i XFBML. Facebook udostępnia specjalne
znaczniki, dające dostęp do danych użytkownika, a także renderujące całe elementy strony, takie jak
na przykład formularz do wysyłania zaproszeń. Warto dodać, że Facebook optymalizuje pobieranie
danych dla tych znaczników, grupując je w tle i wysyłając tylko jedno żądanie do serwera. Nieco
szerzej zajmiemy się tym tematem w kolejnych artykułach.
Możemy również stworzyć link do logowanie korzystając z samego JavaScript SDK.
Kod:

Zaznacz cały

<!-- stworzenie przycisku do logowania z wykorzystaniem JS SDK -->
<a href="#" onclick="javascript:FB.login(function(response)

{ });">zaloguj</a>

Równie proste, prawda? Oczywiście zakładamy, że wcześniej został zainicjowany JavaScript SDK
(tak samo jak to miało miejsce w poprzednim przykładzie). Funkcja FB.login() daje nam
dodatkowo możliwość zareagowania na wszystkie możliwe działania użytkownika, co pokrótce
obrazuje poniższy przykład.
Kod:

Zaznacz cały

FB.login(function(response) {

if (response.session) {
if (response.perms) {

// użytkownik jest zalogowany i nadał wymagane uprawnienia
} else {

// użytkownik jest zalogowany, ale nie nadał wymaganych uprawnień
}

} else {
// użytkownik nie jest zalogowany

}
});

Możemy również założyć, że niezalogowany użytkownik nie ma w ogóle dostępu do naszej
aplikacji i po prostu przekierowywać go automatycznie do strony logowania, ale to mało eleganckie
rozwiązanie.

Niezależnie od tego, w jaki sposób umożliwimy użytkownikowi zalogowanie się do naszej
aplikacji, w końcu może on tego dokonać, a my możemy dobrać się do jego danych. Ponieważ
domyślnie użytkownik udostępnia nam tylko dane, które są widoczne publicznie, nie mamy zbyt
wielkiego pola do popisu. Możemy na przykład umieścić na stronie naszej aplikacji jego imię i
nazwisko oraz awatar. Jak zwykle, można to zrobić na kilka sposobów.
Kod:

Zaznacz cały

// wyświetlanie danych pobranych za pomocą PHP SDK
echo($me['name']);

echo($me['first_name']);

Kod:

Zaznacz cały

<!-- wyświetlanie danych za pomocą XFBML -->

<fb:name uid="loggedinuser"></fb:name>
<fb:name uid="<? echo($uid); ?>"></fb:name>

Możemy również pobierać odpowiednie dane za pomocą JavaScript SDK
Kod:

Zaznacz cały

FB.api('/me', function(response) {
alert(response.name);

});

Można również korzystać z niektórych funkcji Graph API bezpośrednio. Na przykład aby
wyświetlić na stronie zdjęcie profilowe użytkownika o znanym ID lub nazwie wstawiamy
następujący kod HTML:
Kod:

Zaznacz cały

<img src="https://graph.facebook.com/{ID użytkownika}/picture">

<img src="https://graph.facebook.com/{nazwa użytkownika}/picture">

Podsumowanie
Podsumujmy więc to, czego do tej pory się dowiedzieliśmy, i stwórzmy pierwszą prostą aplikację,
która poprosi użytkownika o zalogowanie się, a następnie wyświetli kilka informacji na jego temat.
Kod:

Zaznacz cały

require('facebook.php');

$facebook = new Facebook(array(

'appId' => 'nasze_application_id',
'secret' => 'nasz_application_secret',

'cookie' => true,
));

$session = $facebook->getSession();

$me = null;

if ($session) {
try {

// pobieramy informacje o użytkowniku

$uid = $facebook->getUser();

$me = $facebook->api('/me');
} catch (FacebookApiException $e) {

error_log($e);
}

}
?>

<!doctype html>
<html xmlns:fb="http://www.facebook.com/2008/fbml">

<head>
<meta http-equiv="Content-type" content="text/html; charset=utf-8" />

<title>Nasza aplikacja</title>
</head>

<body>
<div id="fb-root"></div>

<script>
window.fbAsyncInit = function() {

// inicjalizacja JavaScript SDK
FB.init({

appId : '<? echo($facebook->getAppId()); ?>',
session : <? echo(json_encode($session)); ?>,

status : true,
cookie : true,

xfbml : true // włączamy parsowanie XFBML
});

// jeśli użytkownik zaloguje się, odświeżamy stronę

FB.Event.subscribe('auth.login', function() {
window.location.reload();

});
};

(function() {

var e = document.createElement('script');
e.src = document.location.protocol +

'//connect.facebook.net/pl_PL/all.js';
e.async = true;

document.getElementById('fb-root').appendChild(e);
}());

</script>

<? if ($me) : ?>
Witaj, <? echo($me['first_name']); ?>

<img src="https://graph.facebook.com/<? echo($uid); ?></picture">
<? else : ?>

<p>Aby korzystać z tej aplikacji musisz się zalogować</p><br />
<fb:login-button></fb:login-button>

<? endif; ?>
</body>

</html>

Domyślnie użytkownik daje naszej aplikacji dostęp tylko do swoich publicznych danych, takich jak
imię i nazwisko czy zdjęcie profilowe. Każdy użytkownik może decydować o tym, które z jego
danych są udostępniane publicznie, tak więc zestaw informacji, jakimi dysponuje na tym etapie
nasza aplikacja, może być dla każdego użytkownika inny. Co więc w przypadku gdy nasza
aplikacja wymaga do działania danych, których użytkownik nie udostępnia publicznie? Albo gdy
chce zaoferować użytkownikowi automatyczne umieszczanie wpisów na jego tablicy? Wtedy
musimy poprosić użytkownika o dodatkowe zezwolenia.
W drugim z serii artykułów postaram się przybliżyć nieco temat zezwoleń, jakich udziela
użytkownik naszej aplikacji. Omówię również najczęściej wykorzystywane metody Graph API.