Facebook AS3 API : The Basics

Repost artikel yg sudah pernah saya tulis di blog yang lama

Dalam tutorial ini saya akan tunjukkan cara pembuatan aplikasi Flash/Flex untuk Facebook dengan menggunakan Facebook AS3 API yang resmi di-support oleh Facebook & Adobe.

Facebook AS3 API adalah library yang memungkinkan kita membuat aplikasi Flash/Flex yang bisa mengakses data dari Facebook tanpa memerlukan skrip di sisi server. Kalo kita mengeset aplikasi kita sebagai aplikasi “Desktop”, kita bisa langsung menjalankan aplikasi di komputer kita. Jadi nggak perlu upload ke server. Selama proses development, umumnya kita banyak berkutat di sisi desktop , nanti kalo aplikasi sudah siap untuk testing baru kita upload ke server.

Set Up

Langkah pertama yang kita lakukan adalah mengunjungi Facebook Developer Home untuk mengeset aplikasi yang akan kita buat. Buka situs tersebut lalu klik tombol Set Up New Application.

Pada form “Essential Information”, kita isikan nama aplikasi yang akan kita buat. Klik “Agree”, lalu “Save Changes”.

Create Application

Create Application

Di halaman “Basic Settings”, catat API Key dan Secret Key.

Secret & API Keys

Secret & API Keys

Selanjutnya, kita klik menu “Advanced”. Di sini untuk “Application Type” kita pilih Desktop karena sementara kita hanya menjalankan aplikasi secara lokal dan kalo kita ingin aplikasi kita bisa dicoba oleh orang lain, non-aktifkan juga modus Sandbox. Klik Save Changes.

Application Type

Application Type

Terakhir, kita unduh Facebook AS3 API di Googlecode . Kita bisa mengunduh dalam bentuk .zip atau .swc, namun .zip lebih baik karena kita bisa melihat sourcecode-nya. Kita unduh juga dokumentasinya. Kalo Anda punya SVN client, saya sarankan Anda melakukan SVN check-out supaya mudah untuk mengikuti update terbaru.

AS3 Project

Kita buat AS3 project di FlexBuilder atau FlashDevelop ( saya menggunakan FlashDevelop ). Jangan lupa tambahkan Facebook AS3 API ke dalam library path atau kopi direktori source/actionscript/com ke dalam source folder.

Download Project

Dalam project ini, kita menggunakan komponen TextArea dan Button dari Flash CS4 untuk menghemat ukuran file. framework.swc kita kopi dari Flex SDK supaya kita bisa menggunakan class ObjectUtil untuk menampilkan objek dalam format yang lengkap (nama instance dan propertinya) supaya debugging lebih gampang. Tambahkan 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 sendiri dari Flex SDK.

Tambahkan Flex SWC

Tambahkan Flex SWC

Direktori Project

Direktori Project

Kalo Anda ingin mengikuti tutorial ini step-by-step, silakan buka file MainDesktopStart.as dan set file ini sebagai Document Class. Caranya, klik kanan lalu klik “Always Compile” dari context menu seperti gambar di bawah ini.

Setting Main Class

Setting Main Class

API & Secret Keys

Pertama 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";

Instansiasi Facebook & Login

Buka file MainDesktopStart.as. Lihat initFacebook() . Di dalam function ini kita lakukan instansiasi objek FacebookSessionUtil dan event handling untuk FacebookEvent.WAITING_FOR_LOGIN dan FacebookEvent.CONNECT. Karena sebelum aplikasi kita bisa mengakses data user di Facebook, user yang menggunakannya harus memberi persetujuan ( otorisasi ) untuk mengakses data, kita panggil 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.

Test Movie 1

Test Movie 1

Pada saat eksekusi _session.login(), _session menyiarkan FacebookEvent.WAITING_FOR_LOGIN yang di-handle oleh onWaitingForLogin() dan browser akan menampilkan popup window seperti gambar di bawah ini setelah Anda login ke Facebook. Ini tandanya aplikasi kita sudah mendapat otorisasi.

Kalo nggak, pastikan API & Secret Key yang Anda masukkan sudah benar dan jangan lupa, kalo Anda punya PopUp Blocker, matikan dulu.

Logged In

Logged In

Sekarang ini, kalo aplikasi Anda dijalankan oleh orang lain atau Anda login ke account lain, bukan account yang Anda gunakan untuk mendaftarkan aplikasi ini, maka Facebook akan menampilkan dialog meminta otorisasi seperti ini, sebelum pemberitahuan seperti gambar di atas:

Allow Access Dialog

Allow Access Dialog

Berikutnya, kita memberi tahu aplikasi bahwa kita sudah login dan aplikasi sudah mendapat otorisasi dengan mengklik tombol “OK” di pojok kanan bawah aplikasi kita.

Kita tambahkan kode untuk validasi login di onLoginBtnClick() sehingga pada saat kita klik OK, _session akan melakukan validasi & koneksi ke Facebook. validateLogin() berguna untuk memastikan bahwa aplikasi sudah mendapat otorisasi, jadi kalo Anda mengklik OK sebelum Facebook bilang You may now close this window …, maka _session.login() otomatis akan dieksekusi lagi. Sebaliknya, kalo aplikasi sudah mendapat otorisasi, maka aplikasi akan melakukan koneksi ke Facebook dan saat aplikasi menerima respons 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 pastikan bahwa respon yang diterima dari Facebook tidak mengandung pesan kesalahan dengan cara menguji properti success dari FacebookEvent. Jika ada kesalahan, properti ini akan bernilai false. Jika tidak, maka properti ini bernilai true, kita akan mendapat session key, dan kita eksekusi getUserInfo().

Kita tambahkan 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();
	
}

Getting User Data

Kita lihat function getUserInfo(). Kita akan gunakan function ini untuk mengambil data user yang menggunakan aplikasi ini. Kita tambahkan 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 berisi data apa saja yang ingin kita ambil dari data user yang bersangkutan. Di sini kita cukup ambil dua buah data yaitu “name” dan “birthday”. Kita bisa memasukkan String ke dalam variabel fields seperti ini :


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

Tapi lebih baik jika kita menggunakan konstanta yang ada di class GetInfoFieldValues untuk menghindari salah tulis.

Variabel call adalah objek bertipe FacebookCall yang merepresentasikan eksekusi Facebook API. Karena kita ingin mengambil data user, maka kita buat objek GetInfo, dan kita beri argumen berupa properti _session.facebook.uid yang berisi id dari user yang menggunakan aplikasi ini dan variabel fields di atas.

Pada saat respons dari Facebook diterima, objek call akan menyiarkan FacebookEvent.COMPLETE yang di-handle oleh onComplete_getUserInfo() yang akan menampilkan nama & tanggal lahir user di Console dan kemudian mengeksekusi getFriendsInfo(). Untuk itu kita tambahkan kode ke dalam function tersebut 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 merepresentasikan useryang sedang menggunakan aplikasi ini. Tipe datanya adalah FacebookUser. Di sini kita perlu melakukan type-casting terhadap data yang dikirim bersama FacebookEvent menjadi GetInfoData yang memiliki properti userCollection. Karena kita hanya meminta data satu orang user, maka user ini berada di posisi index 0 dari userCollection.

Karena userCollection.getItemAt(0) memberikan data bertipe Object maka kita lakukan type-casting ke tipe data FacebookUser. Baris-baris berikutnya menampilkan data user. Baris terakhir mengeksekusi getFriendIDs().

Getting Friends IDs

getFriendIDs() berfungsi untuk meminta daftar semua friends . Jadi di sini, seperti di getUserInfo(), kita buat variabel call yang bertipe FacebookCall. Berbeda dengan getUserInfo(), kita membuat objek GetFriends bukan GetInfo. Kita juga mengeset onComplete_getFriendIDs() sebagai listener untuk FacebookEvent.COMPLETE.

Kita tambahkan 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 lanjutkan ke onComplete_getFriendIDs().

Di sini data yang diterima bersama FacebookEvent.COMPLETE bertipe GetFriendsData. Jadi, pertama kita buat variabel lokal bernama data yang bertipe GetFriendsData dan mengisinya dengan event data yang sudah di-type-cast menjadi GetFriendsData. Empat baris berikutnya, menampilkan banyaknya friends yang bisa kita ketahui dari panjang properti friends.

Baris-baris berikutnya menampilkan semua ID friends, dengan memanfaatkan properti rawResult yang merupakan data bertipe XML. Di sini kita menggunakan sintaks E4X untuk mengakses semua node di dalam XML tersebut.

Baris terakhir, menggabungkan node value yang disimpan di dalam Array menjadi 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 berjalan seperti gambar di bawah ini. Kalo tidak, silakan cocokkan kode yang Anda tulis dengan MainDesktop.as.

Test Movie 2

Test Movie 2

Going Online

Pertama saya sarankan Anda bikin satu account Facebook lagi, khusus untuk simulasi penggunaan aplikasi oleh orang lain. Account ini sangat berguna khususnya waktu kita menguji proses otorisasi & verifikasi karena developer account Anda secara otomatis mengotorisasi aplikasi yang Anda buat sendiri.

Supaya aplikasi kita bisa digunakan/dimuat ke dalam Facebook Canvas, kita perlu sedikit memodifikasi kode. Sebenarnya nggak banyak yang harus diubah, tapi lumayan bikin pusing karena dokumentasi yang nggak lengkap & contoh-contoh aplikasi yang masih menggunakan API versi lama ( versi 2 ).

Ada beberapa cara untuk memuat aplikasi yang kita buat ke dalam Facebook Canvas. Informasi lengkapnya bisa Anda baca sendiri di Facebook Architecture Overview. Di sini, kita pilih cara yang paling gampang, dengan menggunakan 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:



Berikut ini struktur direktori di host saya.

Server Directory

Server Directory

Kembali ke Application Settings di Facebook. Kita ubah tipe aplikasi menjadi “Web” lalu kita buka menu Canvas dan kita masukkan juga URL dari file index.php yang sudah kita buat. Terakhir kita pastikan bahwa Render Method adalah FBML, bukan iFrame.

Application Type : Web

Application Type : Web

Canvas & Render Method

Canvas & Render Method

Verifikasi Session

Pada saat sebuah SWF dimuat ke dalam canvas melalui fb:swf, Facebook akan menginjeksi flashvars. Yang dapat kita gunakan untuk memverifikasi apakah aplikasi sudah mendapat otorisasi untuk mengakses data adalah fb_sig_session_key. Gambar berikut ini menunjukkan isi flashvars yang diinjek oleh Facebook.

Session Key

Session Key

Buka file MainWeb.as, perbedaan dengan MainDesktop.as hanya pada checkSession() yang berfungsi untuk mengecek keberadaan session key.

Kalo session key tidak ditemukan atau bernilai null, berarti user belum pernah menggunakan aplikasi ini sebelumnya, jadi di sini kita perlu memanggil _session.login(). Sebaliknya, kalo session key ditemukan, kita panggil _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 melihatnya dimuat ke dalam Facebook Canvas. Teman Anda juga bisa menggunakan aplikasi ini.

Sebagai perbandingan, silakan coba aplikasi yang saya buat di sini : http://apps.facebook.com/hello-as/

Facebook Application Test

Facebook Application Test

Application List

Application List

Ok, mudah-mudahan tutorial ini bisa membantu Anda memahami Facebook ActionScript API.

Pada bagian berikutnya dari artikel ini, saya akan menjelaskan bagaimana saya membuat aplikasi Flex untuk Facebook yaitu : Fx Friend Browser.

Stay tuned! 🙂

Fx Friend Browser

Fx Friend Browser

Links

Also in this category ...


4 Comments

  1. mas ajarin yang fitur facebook connect pake flex dong mas. mentok nih 🙂

    thx ya

  2. Hi Anggie

    Although I don’t understand the language the post is really nicely presented – good job!

    Looks cool 🙂

    Robert

Comments are closed.