Facebook AS3 API : The Basics

Repost artikel yg sudah per­nah saya tulis di blog yang lama

Dalam tutorial ini saya akan tun­jukkan cara pem­buatan aplikasi Flash/Flex untuk Facebook dengan meng­gunakan Facebook AS3 API yang resmi di-support oleh Facebook & Adobe.

Facebook AS3 API adalah library yang memung­kinkan kita mem­buat aplikasi Flash/Flex yang bisa meng­ak­ses data dari Facebook tanpa memer­lukan skrip di sisi server. Kalo kita meng­eset aplikasi kita seba­gai aplikasi “Desk­top”, kita bisa lang­sung men­jalankan aplikasi di kom­puter kita. Jadi nggak perlu upload ke server. Selama proses development, umum­nya kita banyak ber­kutat di sisi desk­top , nanti kalo aplikasi sudah siap untuk tes­ting baru kita upload ke server.

Set Up

Lang­kah per­tama yang kita lakukan adalah meng­un­jungi Facebook Developer Home untuk meng­eset aplikasi yang akan kita buat. Buka situs ter­sebut lalu klik tom­bol Set Up New Application.

Pada form “Essen­tial Infor­mation”, kita isikan nama aplikasi yang akan kita buat. Klik “Agree”, lalu “Save Changes”.

Di halaman “Basic Set­tings”, catat API Key dan Secret Key.

Selan­jut­nya, kita klik menu “Advan­ced”. Di sini untuk “Application Type” kita pilih Desk­top karena semen­tara kita hanya men­jalankan aplikasi secara lokal dan kalo kita ingin aplikasi kita bisa dicoba oleh orang lain, non-aktifkan juga modus San­dbox. Klik Save Changes.

Ter­akhir, kita unduh Facebook AS3 API di Googlecode . Kita bisa meng­un­duh dalam ben­tuk .zip atau .swc, namun .zip lebih baik karena kita bisa melihat sourcecode-nya. Kita unduh juga dokumen­tasinya. Kalo Anda punya SVN client, saya sarankan Anda melakukan SVN check-out supaya mudah untuk meng­ikuti update terbaru.

AS3 Project

Kita buat AS3 project di FlexBuilder atau FlashDevelop ( saya meng­gunakan FlashDevelop ). Jangan lupa tam­bahkan Facebook AS3 API ke dalam library path atau kopi direk­tori source/actionscript/com ke dalam source folder.

Download Project

Dalam project ini, kita meng­gunakan kom­ponen TextArea dan But­ton dari Flash CS4 untuk meng­hemat ukuran file. framework.swc kita kopi dari Flex SDK supaya kita bisa meng­gunakan class ObjectUtil untuk menam­pilkan objek dalam for­mat yang leng­kap (nama instance dan proper­tinya) supaya debug­ging lebih gam­pang. Tam­bahkan kedua .swc ke dalam project library ( di FlashDevelop : klik kanan swc → Add To Library ).

Saya tidak memasukkan framework.swc ke dalam project file di atas, jadi silakan Anda kopi sen­diri dari Flex SDK.

Kalo Anda ingin meng­ikuti tutorial ini step-by-step, silakan buka file MainDesktopStart.as dan set file ini seba­gai Document Class. Caranya, klik kanan lalu klik “Always Com­pile” dari con­text menu seperti gam­bar di bawah ini.

API & Secret Keys

Per­tama kita set API Key & Secret Key yang kita dapat dari Facebook. Buka file Constants.as, isikan kedua key tersebut.

public static const API_KEY:String = "YOURAPIKEY";
public static const SECRET_KEY:String = "YOURSECRETKEY";

Instan­siasi Facebook & Login

Buka file MainDesktopStart.as. Lihat initFacebook() . Di dalam fun­ction ini kita lakukan instan­siasi objek FacebookSessionUtil dan event han­dling untuk FacebookEvent.WAITING_FOR_LOGIN dan FacebookEvent.CONNECT. Karena sebelum aplikasi kita bisa meng­ak­ses data user di Facebook, user yang meng­gunakan­nya harus mem­beri per­setujuan ( otorisasi ) untuk meng­ak­ses data, kita pang­gil juga login() milik class FacebookSessionUtil.

private function initFacebookSession():void {

	_session = new FacebookSessionUtil(Constants.API_KEY, Constants.SECRET_KEY, this.root.loaderInfo);
	_session.addEventListener(FacebookEvent.WAITING_FOR_LOGIN, onWaitingForLogin);
	_session.addEventListener(FacebookEvent.CONNECT, onFacebookConnect);

	_session.login();

}

Sekarang kita lakukan Test Movie.

Pada saat eksekusi _session.login(), _session menyiarkan FacebookEvent.WAITING_FOR_LOGIN yang di-handle oleh onWaitingForLogin() dan browser akan menam­pilkan popup win­dow seperti gam­bar di bawah ini setelah Anda login ke Facebook. Ini tan­danya aplikasi kita sudah men­dapat otorisasi.

Kalo nggak, pas­tikan API & Secret Key yang Anda masukkan sudah benar dan jangan lupa, kalo Anda punya PopUp Bloc­ker, matikan dulu.

Sekarang ini, kalo aplikasi Anda dijalankan oleh orang lain atau Anda login ke account lain, bukan account yang Anda gunakan untuk men­daf­tarkan aplikasi ini, maka Facebook akan menam­pilkan dialog meminta otorisasi seperti ini, sebelum pem­beritahuan seperti gam­bar di atas:

Ber­ikut­nya, kita mem­beri tahu aplikasi bahwa kita sudah login dan aplikasi sudah men­dapat otorisasi dengan meng­klik tom­bol “OK” di pojok kanan bawah aplikasi kita.

Kita tam­bahkan kode untuk validasi login di onLoginBtnClick() sehingga pada saat kita klik OK, _session akan melakukan validasi & koneksi ke Facebook. validateLogin() ber­guna untuk memas­tikan bahwa aplikasi sudah men­dapat otorisasi, jadi kalo Anda meng­klik OK sebelum Facebook bilang You may now close this win­dow …, maka _session.login() otomatis akan diek­sekusi lagi. Sebalik­nya, kalo aplikasi sudah men­dapat otorisasi, maka aplikasi akan melakukan koneksi ke Facebook dan saat aplikasi menerima res­pons balik dari Facebook, _session akan menyiarkan FacebookEvent.CONNECT yang di-handle oleh onFacebookConnect().

private function onLoginBtnClick(e:Event):void {
	_console.appendText("\n\n---\nValidating...");

	//validate login and connect to FB
	_session.validateLogin();

}

Di dalam onFacebookConnect() kita pas­tikan bahwa res­pon yang diterima dari Facebook tidak meng­an­dung pesan kesalahan dengan cara meng­uji properti success dari FacebookEvent. Jika ada kesalahan, properti ini akan ber­nilai false. Jika tidak, maka properti ini ber­nilai true, kita akan men­dapat ses­sion key, dan kita eksekusi getUserInfo().

Kita tam­bahkan beberapa baris kode seperti berikut :

private function onFacebookConnect(e:FacebookEvent):void {

	//if connection fails, reinitiate login
	if (!e.success) {

		_console.appendText("\n\n---\nCannot connect to Facebook!");
		_console.appendText("\n\n---\n" + ObjectUtil.toString(e.error));				

		_session.login()

		return;
	}

	_console.appendText("\n\n---\nYou are now connected to Facebook!");
	_console.appendText("\nYour session key : " + _session.facebook.session_key);

	//hide login btn
	_loginBtn.visible = false;

	getUserInfo();

}

Get­ting User Data

Kita lihat fun­ction getUserInfo(). Kita akan gunakan fun­ction ini untuk meng­am­bil data user yang meng­gunakan aplikasi ini. Kita tam­bahkan beberapa baris ke dalam getUserInfo() seperti ini:

private function getUserInfo():void {
	_console.appendText("\n\n---\nGetting your info");

	var fields:Array = [GetInfoFieldValues.NAME, GetInfoFieldValues.BIRTHDAY];
	var call:FacebookCall = _session.facebook.post(new GetInfo([_session.facebook.uid], fields ));
	call.addEventListener(FacebookEvent.COMPLETE, onComplete_getUserInfo);

}

Variabel fields ber­isi data apa saja yang ingin kita ambil dari data user yang ber­sang­kutan. Di sini kita cukup ambil dua buah data yaitu “name” dan “bir­thday”. Kita bisa memasukkan String ke dalam variabel fields seperti ini :

var fields:Array = ["name","birthday"];

Tapi lebih baik jika kita meng­gunakan kon­stanta yang ada di class GetIn­foFieldValues untuk meng­hin­dari salah tulis.

Variabel call adalah objek ber­tipe FacebookCall yang merep­resen­tasikan eksekusi Facebook API. Karena kita ingin meng­am­bil data user, maka kita buat objek GetInfo, dan kita beri argumen ber­upa properti _session.facebook.uid yang ber­isi id dari user yang meng­gunakan aplikasi ini dan variabel fields di atas.

Pada saat res­pons dari Facebook diterima, objek call akan menyiarkan FacebookEvent.COMPLETE yang di-handle oleh onComplete_getUserInfo() yang akan menam­pilkan nama & tang­gal lahir user di Con­sole dan kemudian meng­ek­sekusi getFriendsInfo(). Untuk itu kita tam­bahkan kode ke dalam fun­ction ter­sebut seperti di bawah ini:

private function onComplete_getUserInfo(e:FacebookEvent):void {

	if (!e.success) {
		_console.appendText("\n\n---\nERROR : " + ObjectUtil.toString(e.error));
		return;
	}

	var user:FacebookUser = GetInfoData(e.data).userCollection.getItemAt(0) as FacebookUser;
	_console.appendText("\n\n---\nHello " + user.name + "!");
	_console.appendText(" You were born on " + user.birthday);

	getFriendIDs(_session.facebook.uid);

}

Variabel user merep­resen­tasikan user­yang sedang meng­gunakan aplikasi ini. Tipe datanya adalah FacebookUser. Di sini kita perlu melakukan type-casting ter­hadap data yang dikirim ber­sama FacebookEvent men­jadi GetInfoData yang memiliki properti userCollection. Karena kita hanya meminta data satu orang user, maka user ini ber­ada di posisi index 0 dari userCollection.

Karena userCollection.getItemAt(0) mem­berikan data ber­tipe Object maka kita lakukan type-casting ke tipe data FacebookUser. Baris-baris ber­ikut­nya menam­pilkan data user. Baris ter­akhir meng­ek­sekusi getFriendIDs().

Get­ting Friends IDs

getFriendIDs() ber­fungsi untuk meminta daf­tar semua friends . Jadi di sini, seperti di getUserInfo(), kita buat variabel call yang ber­tipe FacebookCall. Ber­beda dengan getUserInfo(), kita mem­buat objek GetFriends bukan GetInfo. Kita juga meng­eset onComplete_getFriendIDs() seba­gai lis­tener untuk FacebookEvent.COMPLETE.

Kita tam­bahkan kode ke getFriendIDs() seperti berikut:

private function getFriendIDs(uid:String):void {

	var call:FacebookCall = _session.facebook.post(new GetFriends(null, uid ));
	call.addEventListener(FacebookEvent.COMPLETE, onComplete_getFriendIDs);

}

Kita lan­jutkan ke onComplete_getFriendIDs().

Di sini data yang diterima ber­sama FacebookEvent.COMPLETE ber­tipe GetFriendsData. Jadi, per­tama kita buat variabel lokal ber­nama data yang ber­tipe GetFriendsData dan meng­isinya dengan event data yang sudah di-type-cast men­jadi GetFriendsData. Empat baris ber­ikut­nya, menam­pilkan banyak­nya friends yang bisa kita ketahui dari pan­jang properti friends.

Baris-baris ber­ikut­nya menam­pilkan semua ID friends, dengan meman­faatkan properti rawResult yang merupakan data ber­tipe XML. Di sini kita meng­gunakan sin­taks E4X untuk meng­ak­ses semua node di dalam XML tersebut.

Baris ter­akhir, meng­gabungkan node value yang disimpan di dalam Array men­jadi sebuah String dan menampilkannya.

private function onComplete_getFriendIDs(e:FacebookEvent):void {

	if (!e.success) {
		_console.appendText("\n\n---\nERROR : " + ObjectUtil.toString(e.error));
		return;
	}

	var data:GetFriendsData = GetFriendsData(e.data);
	if (data.friends.length > 0) {
		_console.appendText(". You have " + data.friends.length + " friends.");
	}else {
		_console.appendText(". You have no friends.");
		return;
	}

	var xml:XML = new XML(data.rawResult);
	var ids:Array = [];

	for each( var x:XML in xml.*) {
		ids.push(x);
	}

	_console.appendText("Their IDs are : \n"+ ids.join(' , ') +"\n");
}

Sekarang kita coba jalankan aplikasi. Kalo semuanya benar, Anda akan lihat aplikasi ber­jalan seperti gam­bar di bawah ini. Kalo tidak, silakan cocokkan kode yang Anda tulis dengan MainDesktop.as.

Going Online

Per­tama saya sarankan Anda bikin satu account Facebook lagi, khusus untuk simulasi peng­gunaan aplikasi oleh orang lain. Account ini sangat ber­guna khusus­nya waktu kita meng­uji proses otorisasi & verifikasi karena developer account Anda secara otomatis meng­otorisasi aplikasi yang Anda buat sendiri.

Supaya aplikasi kita bisa digunakan/dimuat ke dalam Facebook Can­vas, kita perlu sedikit memodifikasi kode. Sebenar­nya nggak banyak yang harus diubah, tapi lumayan bikin pusing karena dokumen­tasi yang nggak leng­kap & contoh-contoh aplikasi yang masih meng­gunakan API versi lama ( versi 2 ).

Ada beberapa cara untuk memuat aplikasi yang kita buat ke dalam Facebook Can­vas. Infor­masi leng­kap­nya bisa Anda baca sen­diri di Facebook Architecture Overview. Di sini, kita pilih cara yang paling gam­pang, dengan meng­gunakan salah satu tag FBML yaitu fb:swf.

Kita upload dulu file SWF aplikasi yg kita buat ke server. Terus kita buat file “index.php” yg isinya seperti ini:

Ber­ikut ini struk­tur direk­tori di host saya.

Kem­bali ke Application Set­tings di Facebook. Kita ubah tipe aplikasi men­jadi “Web” lalu kita buka menu Can­vas dan kita masukkan juga URL dari file index.php yang sudah kita buat. Ter­akhir kita pas­tikan bahwa Ren­der Method adalah FBML, bukan iFrame.

Verifikasi Ses­sion

Pada saat sebuah SWF dimuat ke dalam can­vas melalui fb:swf, Facebook akan meng­in­jeksi flashvars. Yang dapat kita gunakan untuk memverifikasi apakah aplikasi sudah men­dapat otorisasi untuk meng­ak­ses data adalah fb_sig_session_key. Gam­bar ber­ikut ini menun­jukkan isi flashvars yang diin­jek oleh Facebook.

Buka file MainWeb.as, per­bedaan dengan MainDesktop.as hanya pada checkSession() yang ber­fungsi untuk meng­ecek keberadaan ses­sion key.

Kalo ses­sion key tidak ditemukan atau ber­nilai null, ber­arti user belum per­nah meng­gunakan aplikasi ini sebelum­nya, jadi di sini kita perlu memang­gil _session.login(). Sebalik­nya, kalo ses­sion key ditemukan, kita pang­gil _session.verifySession() yang kemudian akan melakukan koneksi dengan Facebook.

private var _flashvars:Object;
private function initFacebookSession():void {

	_flashvars = this.root.loaderInfo.parameters;

	_console.appendText("\n\n---\Flashvars : " + ObjectUtil.toString(_flashvars));

	_session = new FacebookSessionUtil(Constants.API_KEY, Constants.SECRET_KEY, this.root.loaderInfo);
	_session.addEventListener(FacebookEvent.WAITING_FOR_LOGIN, onWaitingForLogin);
	_session.addEventListener(FacebookEvent.CONNECT, onFacebookConnect);

	checkSession();

}

/**
 * check the flashvars
 * if there's no session key, initiate a login process
 */
private function checkSession():void {

	_console.appendText("\n\n---\nChecking session key...");

	if (_flashvars.fb_sig_session_key != null) {
		_session.verifySession();
	}else {
		_session.login();
	}
}

Silakan akses aplikasi Anda melalui URL : http://apps.facebook.com/nama-aplikasi-anda/. Kalo semua sudah benar, Anda bisa melihat­nya dimuat ke dalam Facebook Can­vas. Teman Anda juga bisa meng­gunakan aplikasi ini.

Seba­gai per­ban­dingan, silakan coba aplikasi yang saya buat di sini : http://apps.facebook.com/hello-as/

Ok, mudah-mudahan tutorial ini bisa mem­bantu Anda memahami Facebook Action­Script API.

Pada bagian ber­ikut­nya dari artikel ini, saya akan men­jelaskan bagaimana saya mem­buat aplikasi Flex untuk Facebook yaitu : Fx Friend Browser.

Stay tuned!

Links

• Project file : → HelloAS3.rar
• Adobe Developer Con­nection : Facebook
• Facebook Action­Script API
• Facebook Developer Home

Also in this category …

• » Scat­tered Gallery
• » Trac­king Aplikasi Flash dengan Google Analytics
• » Bekerja dengan FlashDevelop, Flex SDK, dan Flash
• » Auto-scroll Text Area
• » Factory Pattern

4 Responses to “Facebook AS3 API : The Basics”

1. hari e says:

   May 5, 2009 at 5:33 pm

   mas ajarin yang fitur facebook con­nect pake flex dong mas. men­tok nih

   thx ya
2. Robert says:

   May 6, 2009 at 1:30 pm

   Hi Ang­gie

   Although I don’t unders­tand the language the post is really nicely presen­ted — good job!

   Looks cool

   Robert
3. Anggie Bratadinata says:

   May 6, 2009 at 8:18 pm

   @hari e
   Facebook Con­nect nanti menyusul. Aku juga belum gitu ngerti

   @Robert
   Thanks for the kind words!
4. Rishi Tandon says:

   May 14, 2009 at 5:25 am

   Ang­gie, I was looking for something like this.
   Thanks for your time
   –Rishi