2012年11月5日 星期一

[宅] facebook開發筆記 - javascript SDK(下)

除了前面兩篇()所提到的FB的三個core method,另外也有幾個不介紹不行的好用method:

FB.Event.subscribe & FB.Event.unsubscribe

用來listen相關facebook事件,當特定事件出現時就執行callback function
FB.Event.subscribe(event, callback function)
讓我們來看一段程式碼:
FB.Event.subscribe('auth.sessionChange', function(response) {
     if (response.session) {
        alert(response.authResponse.accessToken);
        //使用者登入,資料寫入cookies裡
     } else {
        alert("Ohoh");
        //使用者登出,cookies被清掉
     }
});

除了範例中所提到的,我們還能訂閱以下的事件:

  • auth.login - fired when the auth status changes to connected
  • auth.logout - fired when your app notices that there is no longer a valid user
  • auth.authResponseChange - fired when the authResponse changes
  • auth.statusChange - fired when the status changes (see FB.getLoginStatus for additional information on what this means)


而傳給callback function的參數"response"長得像這樣:
{
  status: "",         /* Current status of the session */
  authResponse: {          /* Information about the current session */
    userID: ""          /* String representing the current user's ID */
    signedRequest: "",  /* String with the current signedRequest */
    expiresIn: "",      /* UNIX time when the session expires */
    accessToken: "",    /* Access token of the user */
  }
}

而至於unsubscribe的部分則是subscribe的相反,就是取消listen特定事件,可以自己試試看。


FB.login

顧名思義,就是以facebook登入所在網站。前提是你必須先用FB.init設定了SDK環境、設定appId。
FB.login(callback function, permissions scope)
來,讓我們再欣賞一段程式碼範例:
FB.login(function(response) {
   if (response.authResponse) {
     console.log('Welcome!  Fetching your information.... ');
     FB.api('/me', function(response) {
       console.log('Good to see you, ' + response.name + '.');
     });
   } else {
     console.log('User cancelled login or did not fully authorize.');
   }
}, {scope: 'user_about_me,email,user_likes'});
這邊要注意的是第二個參數是一個object,只有一組key:value,key一定是"scope",value是一連串以permission組成的String,中間以逗號分開。
scope中所指定的就是要從使用者那拿到的授權,要看詳細清單可以看facebook的官方文件


FB.getLoginStatus

基本上在一個facebook應用中我們需要判斷使用者是以下三個狀態中的哪一種:
  • 使用者登入了facebook也授權給你的應用程式 (connected)
  • 使用者登入了facebook但還沒授權給你的應用程式 (not_authorized)
  • 根本沒登入 (unknown)

這時我們就可以使用FB.getLoginStatus來搞清楚使用者的狀態
FB.getLoginStatus(callback function, force)
force是一個boolean,會強制reload使用者的登入狀態(預設為false)
我們再來偷一段程式碼來搞清楚他的用法:
FB.getLoginStatus(function(response) {
  if (response.status === 'connected') {
    // the user is logged in and has authenticated your
    // app, and response.authResponse supplies
    // the user's ID, a valid access token, a signed
    // request, and the time the access token 
    // and signed request each expire
    var uid = response.authResponse.userID;
    var accessToken = response.authResponse.accessToken;
  } else if (response.status === 'not_authorized') {
    // the user is logged in to Facebook, 
    // but has not authenticated your app
  } else {
    // the user isn't logged in to Facebook.
  }
 });

response object:
{
    status: 'connected',
    authResponse: {
        accessToken: '...',
        expiresIn:'...',
        signedRequest:'...',
        userID:'...'
    }
}


總結

基本上用facebook javascript SDK開發中常用的、必用的大致上都在這三篇提過了。但是真的要用得很熟練還是要多翻facebook的官方文件。希望這三篇教學筆記能幫助路過的facebook入門開發者。

[宅] facebook開發筆記 - javascript SDK(中)


FB(object)

FB是javascript SDK主要提供服務的物件,在載入函式庫時就會被建立在window底下(FB等於window.FB)。
FB提供很多功能,其中最核心的function有三種:
  • FB.api
  • FB.init
  • FB.ui

前面其實已經使用過FB.init()這個funtion,我們知道它主要是用來初始化SDK環境。為了更了解FB這個object還有些什麼attribute和function,我把它給parse一遍,印出來讓大家能一目了然:
_callbacks: object
api: function
getLoginStatus: function
getAuthResponse: function
getAccessToken: function
getUserID: function
login: function
logout: function
Auth: object
-->getLoginStatus: function
-->fetchLoginStatus: function
-->setAuthResponse: function
-->getAuthResponse: function
-->parseSignedRequest: function
-->xdResponseWrapper: function
Canvas: object
-->isTabIframe: function
-->setSize: function
-->setAutoGrow: function
-->getPageInfo: function
-->scrollTo: function
-->setDoneLoading: function
-->startTimer: function
-->stopTimer: function
-->hideFlashElement: function
-->showFlashElement: function
-->getHash: function
-->setHash: function
-->setUrlHandler: function
-->Prefetcher: object
CanvasInsights: object
-->setDoneLoading: function
share: function
publish: function
addFriend: function
Data: object
-->query: function
-->waitOn: function
-->process: function
Event: object
-->subscribers: function
-->subscribe: function
-->unsubscribe: function
-->monitor: function
-->clear: function
-->fire: function
EventProvider: object
-->subscribers: function
-->subscribe: function
-->unsubscribe: function
-->monitor: function
-->clear: function
-->fire: function
Frictionless: object
-->init: function
-->isAllowed: function
init: function
JSON: object
-->stringify: function
-->parse: function
UA: object
-->nativeApp: function
ui: function
XFBML: object
-->parse: function
-->RecommendationsBar: object

接著我們要介紹幾個重要的function


FB.api

在上一篇提到的API,除了以網址的方式來query資料,我們也能用FB.api()來執行facebook API。(主要是FQL及graph API,login的部分有FB.login()來處理,而REST API已經被捨棄了)
FB.api最多需要四個參數,分別是url、method、提供給API的參數(object)、callback函式:

姓名類型簡介
pathStringthe url path
methodStringthe http method (default "GET")
paramsObjectthe parameters for the query
cbFunctionthe callback function to handle the response



這邊就以FQL來舉個例子,先來看FQL中friends表單的欄位:

可索引姓名類型簡介
*uid1intThe user ID of the first user in a particular friendship link.
*uid2intThe user ID of the second user in a particular friendship link.


今天我們想從FQL中的friends表單中找出使用者的好友,寫成FQL語句就會是這樣:
SELECT uid2 FROM friend WHERE uid1=me()

如果要使用FB.api的話就要寫成這樣:
FB.api(
    "/fql", //path
    {q:"SELECT uid2 FROM friend WHERE uid1=me()"}, //parameter
    function(d) {window.d = d;} //callback function
 );

你可能會發現上面是沒有傳入method的,那是因為如果沒有傳值進去method會預設為GET,所以還是可以正常運作。所以在GET的方法下我們當然也可以寫成:

FB.api(
    "/fql?q=SELECT+uid2+FROM+friend+WHERE+uid1=me()", //path
    function(d) {window.d = d;} //callback function
 );


到了這邊大家可能會發現我一直都沒使用到access_token,這可不是筆誤。使用SDK時,它會自動幫你傳acess_token(我猜的),所以不用特別把它傳過去。但如果你是使用http來query的話就一定要了,所以上面的功能就要寫成這樣:
https://graph.facebook.com/fql?q=SELECT uid2 FROM friend WHERE uid1=me()&access_token=...


FB.ui

主要是用來產生dialog與使用者做互動,例如"發佈到塗鴉牆"、"邀請好友"、"分享連結"、"取得應用程式授權"等等都可以用FB.ui來與使用者溝通,也是個比較禮貌的做法。
那什麼是不禮貌的做法勒?例如說在取得一次使用者的發布塗鴉牆授權後,使用FB.api來直接發布:
FB.api('/me/feed', 'post', { message: body }, function(response){});
也因為FB.ui在動作時都會以彈出視窗讓你知道,所以照理來說應該是不用事先取得這些動作的授權,讓我們來看看要怎樣發布資訊到使用者牆上:
FB.ui(
  {
    method: 'feed',
    name: 'Facebook Dialogs',
    link: 'http://developers.facebook.com/docs/reference/dialogs/',
    picture: 'http://fbrell.com/f8.jpg',
    caption: 'Reference Documentation',
    description: 'Dialogs provide a simple, consistent interface for applications to interface with users.'
  },
  function(response) {
    if (response && response.post_id) {
      alert('Post was published.');
    } else {
      alert('Post was not published.');
    }
  }
);

[宅] facebook開發筆記 - javascript SDK(上)

前面兩篇講到了facebook API,現在我們來講講SDK。

API(Application Programming Interface)直譯成中文是"應用程式介面":只要藉由對方提供的介面丟東西進去就會回傳結果給你。
SDK(Software Development Kit)比較不一樣的是他需要在本機安裝他所提供的函式庫實際跑在本機端,而不是單純使用遠端的服務。

facebook javascript SDK

facebook目前提供JavaScript SDK、PHP SDK、iOS SDK、Android SDK四種開發環境,因為我目前只做web開發,而且也不只用php,所以選擇javascript SDK來做研究、開發。

安裝函式庫&初始化

要使用javascript SDK,必須先include進函式庫,我們來看看以下範例:
<div id="fb-root"></div>
<script>
  window.fbAsyncInit = function() {
    // init the FB JS SDK
    FB.init({
      appId      : 'YOUR_APP_ID', // App ID from the App Dashboard
      channelUrl : '//WWW.YOUR_DOMAIN.COM/channel.html', // Channel File for x-domain communication
      status     : true, // check the login status upon init?
      cookie     : true, // set sessions cookies to allow your server to access the session?
      xfbml      : true  // parse XFBML tags on this page?
    });

    // Additional initialization code such as adding Event Listeners goes here

  };

  // Load the SDK's source Asynchronously
  (function(d, debug){
     var js, id = 'facebook-jssdk', ref = d.getElementsByTagName('script')[0];
     if (d.getElementById(id)) {return;}
     js = d.createElement('script'); js.id = id; js.async = true;
     js.src = "//connect.facebook.net/en_US/all" + (debug ? "/debug" : "") + ".js";
     ref.parentNode.insertBefore(js, ref);
   }(document, /*debug*/ false));
</script>

第一部份(藍字) - "fb-root tag"

只要有facebook javascript SDK的地方就要有fb-root。
但是你會發現即使不加它,程式好像也能正常執行,這是因為在初始化時SDK找不到fb-root,就會幫你新創一個,並在console log中顯示"The "fb-root" div has not been created, auto-creating."
在facebook的官方文件中有提到,若將fb-root設為display: none 或 visibility: hidden,在萬惡IE中可能會不正常運作,但是基本上你也不用考慮它會影響排版,因為初始化時就會把它設為position:absolute且top:-1000之類的,絕對不會讓你看到。所以這部份很單純的嵌入這個小小的div就好。


第二部份(綠字) - 初始化設定

這部份很關鍵,第一部份不用改、第三部份也可以不用改,但是這個地方你至少必須填入你的appId,不然是不能work的,其他參數可以不用改沒關係。
雖然說除了appId以外的參數保留預設值就可以了,但是channelUrl似乎滿值得一提的,所以我在網路上查了一下,在stackoverflow上找到了一個不錯的解釋:

The channel file is to provide a way to do cross domain communication between FB's servers and your own. The reason for this is their tight control over access tokens. You must authenticate a redirect url and app id to retrieve this access token. In order for them to pass you the token, they hit your URL with the access token in the hash. With the Channel URL, they get to pass this token to themselves (their JavaScript running on your domain).
This channel file can then communicate the access token to your active page.

facebook提供給開發者的大部分服務幾乎都得靠access_token來驗證權限,而要取得access_token必須要經過facebook的兩個檢查:redirect urlapp id,他們必須和你在facebook developer那邊所註冊的資料是吻合的(redirect url得在登記的domain下)。也因為這個原因,在沒有預設chanel的狀況下,SDK會強制在你的頁面塞入一個隱藏的iframe以便在你的頁面載入social plugins,這樣一來會造成載入時間長以及效率低落的問題。所以為了提高效能,facebook建議開發者建立http://www.yourdomain.com/channel.html這個檔案,檔案中只要有一行程式碼即可:
<script src="//connect.facebook.net/en_US/all.js"></script>


第三部份(紅字) - 載入facebook javascript SDK

其實只要照範例把這段貼上去即可,不太需要變動它。
這段code主要是檢查document中是否已載入了SDK,如果沒有就嵌入SDK的js檔。在這段code裡面你會看到它所載入的js檔是"//connect.facebook.net/en_US/all.js",其中的en_US是代表洋人美語語系,若要改成台灣用的繁中語系,只要把en_US換成zh_TW就好了。