[Facebook] Open Graph（開放社交關係圖）動作設定教學

Facebook 於 2011/09/23 發佈了新的 Open Graph 開發者教學，在應用程式中出現了 Open Graph（開放社交關係圖）頁籤，項目相當多，因此快速做了簡單的翻譯，方便未來研究之用。

其中此篇便是讓使用者可以使用各種「動作」的新功能，就像除了某某某覺得什麼很「讚」之外，還可以增加某某某 listen to 某專輯、某某某 cook 一道菜這樣的動作。
這邊有相關的介紹。
※不過很可惜的是目前尚不支援中文的動作與物件。

翻譯功力尚淺，請各位前輩不吝指正，也歡迎同好一起討論：）

這份教學將會帶領你照著下面步驟建立、測試、發佈你的第一個 Open Graph 應用程式。我們會建立一個讓使用者發佈料理資訊的範例應用程式。

Step 1: 建立 Facebook app
Step 2: 取得使用者的時間軸授權
Step 3: 定義初始動作、物件與集合
Step 4: 為你的使用者發佈動作
Step 5: 把社群外掛加到你的應用程式中: Facepile plugin, Activity plugin, and Recommendations plugin
Step 6: 將動作送交審閱

如果你對 Open Graph 有疑問，請造訪: Debug and Troubleshoot。為了讓你更快上手，我們亦提供了範例下載。

Step 1: 建立 Facebook app

先至 Dev App，點擊「建立新的應用程式」，並輸入應用程式的名稱以及命名空間。

當你送出初始資訊，你便會進入應用程式的基本設定頁面。

基本資料：
1. 你的應用程式命名空間。這會是您的應用程序所特有的，將被用來管理你的物件和動作。
選擇你的應用程式是如何跟 Facebook 結合：
1. 選擇「網站」（在此份教學中，我們會建立一個與 Open Graph 整合的範例網站）
2. 輸入網站的 URL。

您已設置的基本信息後，您便可以在你的網站中加入「增加到時間軸」的外掛，定義你的 Open Graph 行為和物件。

Step 2: 取得使用者授權

為了發佈使用者的 Open Graph 動作，您的應用程序需要取得使用者的 publish_actions 權限。您可以使用「加入到時間軸」外掛，它會自動要求用戶的權限。

下面是一段使用 JavaScript SDK 的範例程式碼，幫助你快速進入狀況。請記得把 YOUR_APP_ID 以及範例圖片網址更新成你的喔。

[code language=”HTML”]

 
<h3><span style="color: grey; font-family: verdana;">
Stuffed Cookies
</span></h3>
<img title="Stuffed Cookies" src="http://example.com/cookie.jpg" alt="" width="550" />

[/code]

您會發現，你的外掛可能會產生一個空白的預覽，並點擊「加入到時間軸」按鈕，產生一個空的權限對話框。

要將特定的 app 資訊植入 授權對話框 與 加入時間軸外掛，請參閱 Auth Dialog 指南。

Step 3: 定義動作、對象與聚合

應用程式開發中的 Open Graph 頁籤顯示了 “Getting Started” 頁籤：

定義行為類型與對象類型

Getting Started 精靈將引導你定義初始的動作與對象。

點擊你的應用程式中的「Open Graph」頁籤
接著點擊「Getting Started」

本教學中，你會建立一個使用者可以 cook a recpie 的動作（譯註：尚不知道在中文版會如何呈現這樣的行為句子）。為了達成前述目的，我們將會定義一個動作（或動詞）叫做 cook，並定義一個對象（或名詞）叫 recipe。

在動詞輸入框中輸入 cook ，並在名詞輸入框中輸入 recipe。（譯註：可惜的是，目前似乎尚無法輸入中文的動詞與名詞。– 2011/09/23）
點擊「Get Started」

下一步，你可以定義你的動作，cook 這個動作擁有自訂屬性與範例資料。在本教學中，我們使用預設的配置。點擊 Save Changes and Continue。

下一步，定義對象，recipe 擁有自訂屬性與範例資料。在本教學中，我們使用預設的配置。點擊 Save Changes and Continue。

定義集合

下一步，定義集合。

當使用者與你的應用程式以一種有意義的方式互動，我們亦會將使用者在時間軸上的動作以特別方式顯示集合資訊。集合資訊也可以用來植入驗證對話框展示區塊。

讓我們來建立一個特別標註 receipes cooked 列表的集合資訊：

Date to Display – 我們需要一個 cook 動作的列表，所以在此輸入 cook。
Layout Style – 選擇 List
Sort By – 選擇 Most Recent Cook
Aggregation Title – 輸入一個有趣的集合資訊標題，像是「Recipes I’ve Cooked」
Caption Lines – 你可以參考物件的自訂屬性，或動作的屬性。在此份教學中，我們不填這欄，更多本欄的資訊，請參考這裡。
In Timeline – 預覽在時間軸中你的集合資訊。點擊 Save and Finish 來返回 Open Graph 資訊頁面。

當你儲存你的物件、動作與集合資訊的定義後，Open Graph 的控制台將會秀出這些資訊的綜覽。

下個單元會帶領你發布你的第一個動作並在使用者的時間軸中呈現集合資訊。

Step 4: 發佈動作

為了要發佈一個使用者的動作，你得先 建立一個對象（create an object），這是基於在 Step 3 中定義的物件。

當對象被建立後，你便可使用 Graph API 發佈一個動作。

建立物件

Open Graph 資訊頁面在 Recipe 後面提供了「Get Code」連結。Open Graph 的 meta 標籤，包含那些你要嵌入在你網頁中的動作資訊。

複製程式碼片段到你的網頁中。確認你的網頁是擺在 Facebook 可透過 HTTP GET 存取的主機上。
使用偵錯工具去驗證你的 meta 標籤是正確地被設置的。請試著解決所有的錯誤訊息（若有的話）。
記下對象的 URL，因為你將會使用它來發佈你的動作。

下面是加入 <meta> 標籤的頁面。請記得把 YOUR_APP_ID、APP_NAMESPACE、OBJECT_TYPE 以及範例圖片網址更新成你的喔。
[code language=”HTML”]
<html xmlns="http://www.w3.org/1999/xhtml" dir="ltr" lang="en-US"
xmlns:fb="https://www.facebook.com/2008/fbml">

</head>

<body>
<div id="fb-root"></div>
<script src="http://connect.facebook.net/en_US/all.js"></script>
<script>
FB.init({
appId:’YOUR_APP_ID’, cookie:true,
status:true, xfbml:true, oauth:true
});
</script>

<fb:add-to-timeline></fb:add-to-timeline>

<h3>
<font size="30" face="verdana" color="grey">
Stuffed Cookies
</font>
</h3>
<p>
<img title="Stuffed Cookies"
src="http://fbwerks.com:8000/zhen/cookie.jpg"
width="550"/><br />
</p>
</body>
</html>
[/code]

發佈動作

發佈一個使用者與對象連結的動作。Open Graph 資訊頁面的 Action 後方，擁有「Get Code」連結，這包含了 curl 程式碼片段，你可複製到終端機中並直接執行。

發佈動作涉及建立一個 HTTP POST 要求送到 me/[namespace]:[action_type] Graph API 端點，帶有以下參數：

[object_type]: 一個鏈接到一個網頁，代表一個對象。
access_token: 一個有效的用戶 access_token publish_actions權限。

下面範例是傳送一個 POST 到：
[code]
https://graph.facebook.com/me/APP_NAMESPACE:ACTION_TYPE?OBJECT_TYPE=OBJECT_URL&access_token=ACCESS_TOKEN
[/code]
這將會發佈一個 cook 的動作，recipe 與提供的 OBJECT_URL 相應。請把 OBJECT_URL 更換為你的網頁 URL。

下面是更新了行為與 Cook 按鈕的範例應用程式。請記得把 YOUR_APP_ID、APP_NAMESPACE、OBJECT_TYPE、ACTION_TYPE 以及範例圖片網址更新成你的喔。
[code language=”HTML”]
<html xmlns="http://www.w3.org/1999/xhtml" dir="ltr" lang="en-US"
xmlns:fb="https://www.facebook.com/2008/fbml">

<fb:add-to-timeline></fb:add-to-timeline>

<h3>
<font size="30" face="verdana" color="grey">
Stuffed Cookies
</font>
</h3>
<p>
<img title="Stuffed Cookies"
src="http://example.com/cookie.jpg"
width="550"/><br />
</p>

<form>
<input type="button" value="Cook" onclick="postCook()" />
</form>
</body>
</html>
[/code]
點 cook 按鈕，如果發佈是成功的，你將會取得一個返回的 id，其代表新的發佈。恭喜！你已經成功發佈一個動作，並完成讓 Open Graph 應用程式運作的基礎階段了。

為了檢視你時間軸上的聚合資訊，我們還得要建立一些動作。使用上面的步驟，建立幾個物件，並引發幾個動作。你需要發佈至少五個動作，才能看到時間軸上的集合資訊。

在 Facebook 的時間軸上，你應該會看到你應用程式的集合資訊：（譯註：集合資訊這塊筆者尚未成功試出來…僅有在一開始允許加入到時間軸時可看到這個資訊，不知是否因為尚在改版之故）

Step 5: 加入社群外掛

加入一個或更多的 Social Plugins 供 Open Graph 應用程式使用。

在你的對象網頁中，你可以加入任何外掛去標註 Open Graph 動作。在我們的教學中，讓我們加入 Activity Plugin。

Activity

Activity Plugin 已經更新，以標註你應用程式的 Open Graph 動作。

加入 Activity Plugin：
[code language=”HTML”]
<fb:activity actions="APP_NAMESPACE:ACTION_TYPE"/></fb:activity>
[/code]

下面是整份教學範例，加上 Add to Timeline、張貼動作，以及 Activity plugin。請記得把 YOUR_APP_ID、APP_NAMESPACE、OBJECT_TYPE、ACTION_TYPE 以及範例圖片網址更新成你的喔。
[code language=”HTML”]
<head prefix="og: http://ogp.me/ns# APP_NAMESPACE:
http://ogp.me/ns/apps/APP_NAMESPACE#">
<meta property="fb:app_id" content="YOUR_APP_ID" />
<meta property="og:type" content="APP_NAMESPACE:OBJECT_TYPE" />
<meta property="og:title" content="Stuffed Cookies" />
<meta property="og:image" content="http://example.com/cookie.jpg" />
<meta property="og:description" content="The Turducken of Cookies" />
<meta property="og:url" content="http://example.com/cookie.html">

<fb:add-to-timeline></fb:add-to-timeline>

<h3>
<font size="30" face="verdana" color="grey">
Stuffed Cookies
</font>
</h3>
<p>
<img title="Stuffed Cookies"
src="http://example.com/cookie.jpg"
width="550"/><br />
</p>

<form>
<input type="button" value="Cook" onclick="postCook()" />
</form>
<fb:activity actions="APP_NAMESPACE:ACTION_TYPE"></fb:activity>
</body>
</html>
[/code]

Step 6: 將你的你的動作送交審閱

在你的應用程式可以向所有使用者發佈 Open Graph 動作之前，我們會採用一個輕量級審查和核准程序。

打開 Open Graph 活動將立即看到您的應用程式的管理員、開發人員和測試人員。這允許你做終端到終端的集成測試。一旦完成，透過應用程式開發頁提交動作審查。

在我們驗證你的 Open Graph 使用方式符合標準，我們將會核可應用程式對所有 Facebook 的使用者發佈動作。請注意，我們並非核可你的應用程式，而只是 Open Graph 動作的使用。

更多細節請參照這裡。

故障排除

下面是當你遇到應用程式動作或對象問題時，幾個有幫助的技巧提示：

如何驗證你的對象（Object）

使用 object debugger，你可驗證你的對象是否使用了必要的 meta 標籤。

如何驗證你的行為已被發佈

使用 object debugger 確保你的對象是正確地被定義的
確認你在 API 呼叫時使用正確的命名空間。記得當命名空間被儲存後便不能修改。
確認在你建立 Graph API 呼叫前，已經從 access_token 中移除了 &expires token。
確認你可在 Graph API POST 呼叫後取得返回的 id

為什麼我在發佈動作後得到「This method must be called with an app access_token」的錯誤？

在應用程式開發頁，你的動作類型中取消勾選「Require app access token to write」選項。

範例程式碼

此份教學在我們的 Samples and How-To 中已可取得。

而這邊是筆者製作的範例。

翻譯有誤或有任何需修正的部分，請不吝指正，大家一起討論：）

Partner Studio

patw 的技術筆記

[Facebook] Open Graph（開放社交關係圖）動作設定教學

Step 1: 建立 Facebook app

Step 2: 取得使用者授權