Tutorial : Facebook開発者向けドキュメントの日本語訳とTips

このチュートリアルは、Open Graphアプリケーションを作成し、テストし、公開するための主なステップをガイドします。ユーザの料理したストーリーを投稿するサンプルアプリケーションを作成します。

Step 1: Facebookアプリケーションの作成
Step 2: Add to Timelineプラグイン用のユーザ認証を得る
Step 3: Define Dev Appで、アクション、オブジェクト、アグリゲーションを定義する
Step 4: ユーザのアクションを投稿する
Step 5: Facepile, Activity, Recommendationsプラグインを足す
Step 6: 登録し、アクションの認可を得る

Open Graphのアクション投稿で問題が発生したら、Debug and Troubleshootの項目を確認してください。早く試してみたい方のために、ダウンロード用のチュートリアルも用意しました。

Step 1: Create a Facebook App

アプリケーションを作成するには、Dev Appへ行って'Create New App'をクリックし、アプリケーション名とネームスペースを入力してください。

初期情報の入力が終わったら、アプリケーションの基本設定ページに飛びます。

Basic Info:
1. アプリケーションのネームスペース。必ず一意である必要があり、オブジェクトとアクションの管理に使われます。
Select how your app integrates with Facebook:
1. Websiteの項目を選択します（チュートリアルでは、Open Graphのウェブサイトへの実装を行います）
2. ウェブサイトのURLを入力します。

基本情報の設定が終わると、ウェブサイトにAdd to Timelineプラグインを足したりOpen Graphのアクションやオブジェクトを定義できるようになります。。

Step 2: Authenticate Users

ユーザのOpen Graphアクションを投稿するには、ユーザのpublish_actionsパーミッションを取得している必要があります。 Add to Timelineプラグインを使うと、このパーミッションを許可するよう、自動的にユーザを促します。

以下に、JavaScript SDKを用いたサンプルコードがありますので、すぐに試してみる参考になります。YOUR_APP_IDとサンプル画像URLを自分用の物に切り替えるのを忘れないでください。

<html xmlns="http://www.w3.org/1999/xhtml" dir="ltr" lang="en-US"
     xmlns:fb="https://www.facebook.com/2008/fbml"> 
<head>
<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://example.com/cookie.jpg" 
            width="550"/>
</p>       
</body> 
</html>

プラグインが比較的空っぽのプレビューを生成することに気づくでしょう。また、Add to Timelineボタンも空っぽのパーミッションダイアログを生成します。

Auth DialogとAdd to Timelineプラグインをアプリケーション情報で埋めるには、 Auth Dialogガイドをご覧ください。

Step 3: Define Actions, Objects, and Aggregations

Dev AppのOpen Graphタブに、Getting Startedタブが表示されます。

Define Action Type and Object Type

Getting Startedウィザードで、アクションとオブジェクトの定義ができます。

アプリケーション設定下の'Open Graph'タブをクリックする
'Getting Started'をクリックする

このチュートリアルでは、ユーザがレシピを料理するというアクションを取れるようにします。そのためには、cookというアクション（動詞）を定義し、recipeというオブジェクト（名詞）を定義します。

verbフィールドにcookと入力し、nounフィールドにrecipeと入力する
'Get Started'をクリックする

ウィザードの次のステップでは、cookというアクションのプロパティとサンプルデータをカスタマイズして定義します。それができたらSave Changes and Continueをクリックします。

ウィザードの次のステップでは、recipeのプロパティとサンプルデータをカスタマイズして定義します。チュートリアルではデフォルトのオブジェクト設定を使います。定義したらSave Changes and Continueをクリックします。

Define an Aggregation

ウィザードの次のステップは要約の定義です。

Let's create an aggregation to highlight a list of recipes cooked:

ユーザがアプリケーション上で意味のある行動をするとTimeline上にユーザの行動要約が表示されます。Auth DialogのShowcaseセクションを中を埋めるのにも要約が用いられます。

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 Dashboardに戻ります。

変更を保存したら、オブジェクト,アクション,要約の定義は完了です。Open Graph設定のDashboardで設定の要約を見ることができます。

次のセクションでは、アクションを投稿してユーザのタイムラインに要約を載せる方法を紹介します。

Step 4: Publish Actions

ユーザのアクションを投稿するには、Step 3で定義したオブジェクトに基づいてオブジェクトを生成する必要があります。

オブジェクトが生成されたら、Graph APIを使ってアクションを投稿します。

Create an Object

Open Graph Dashboardページを見ると、Recipeオブジェクトの横に'Get Code'というリンクがあります。ここでは、webページ中に含める必要のあるメタタグが生成されます。

ウェブページにコードを貼付けます。FacebookがHTTP GETメソッドでアクセスできる場所でページをホストすることを忘れないでください。
debugger toolにURLを入力して、メタタグが正しく設定されているかをチェックします。
このURLをアクション投稿に使うことになります。

以下が、<meta>タグを追加したページです。YOUR_APP_IDと画像URLを自分の物に置き換えるのを忘れないでください。

<html xmlns="http://www.w3.org/1999/xhtml" dir="ltr" lang="en-US"
    xmlns:fb="https://www.facebook.com/2008/fbml"> 

<head prefix="og: http://ogp.me/ns# YOUR_NAMESPACE: 
    http://ogp.me/ns/apps/YOUR_NAMESPACE#"> 
    <meta property="fb:app_id" content="YOUR_APP_ID" /> 
    <meta property="og:type" content="YOUR_NAMESPACE:recipe" /> 
    <meta property="og:title" content="Stuffed Cookies" /> 
    <meta property="og:image" content="http://example.com/zhen/cookie.jpg" /> 
    <meta property="og:description" content="The Turducken of Cookies" /> 
    <meta property="og:url" content="http://example.com/zhen/cookie.html"> 

</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>

Publish an Action

アクションを投稿することで、ユーザとオブジェクトが結びつけられます。Open Graph Dashboardページのアクション横に'Get Code'というリンクがあります。ここには、ターミナルに貼付けて実行できるcurlコードが書かれています。

アクションを投稿するには、me/[namespace]:[action_type]に対して、以下のパラメータと一緒にHTTP POSTリクエストを送ります。

[object_type]: オブジェクトのウェブページへのリンク
access_token: publish_actionsパーミッションを持った有効なaccess_token

例えば、以下のURLに対してPOSTリクエストを送ります。

https://graph.facebook.com/me/YOUR_NAMESPACE:cook
       ?recipe=OBJECT_URL&access_token=ACCESS_TOKEN

これで、OBJECT_URLにあるrecipeに対するcookアクションを投稿できます。OBJECT_URLの部分を、自分のウェブページのURLに置き換えてください。

<html xmlns="http://www.w3.org/1999/xhtml" dir="ltr" lang="en-US"
     xmlns:fb="https://www.facebook.com/2008/fbml"> 

<head prefix="og: http://ogp.me/ns# YOUR_NAMESPACE: 
            http://ogp.me/ns/apps/YOUR_NAMESPACE#"> 
    <meta property="fb:app_id" content="YOUR_APP_ID" /> 
    <meta property="og:type" content="YOUR_NAMESPACE:recipe" /> 
    <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"> 

    <script type="text/javascript">
    function postCook()
    {
        FB.api('/me/YOUR_NAMESPACE:cook' + 
                    '?recipe=http://example.com/cookie.html','post',
                    function(response) {
            if (!response || response.error) {
                    alert('Error occured');
            } else {
                alert('Post was successful! Action ID: ' + response.id);
                }
        });
    }
    </script>
</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://example.com/cookie.jpg" 
                            width="550"/><br />
        </p>       

        <form>
            <input type="button" value="Cook" onclick="postCook()" />
        </form>
    </body> 
    </html>

cookボタンをクリックして投稿に成功すると、投稿されたアクションを表すidが返されます。おめでとうございます！これであなたは、アクションを投稿し、Open Graphアプリケーションを作成して運用する基礎部分を完了しました。

タイムライン上で要約を見るには、アクション作成がもう少し必要になります。上記で解説した方法でオブジェクトをもう少し作成し、何個かアクションを実行します。Timeline上で要約を見るには5個以上のアクションが必要です。

Timelineページに行って、アプリケーションの要約が出るか見てみてください。

Step 5: Add Social Plugins

Open Graphアプリケーションに対応したSocial Pluginsを追加します。

オブジェクトのウェブページにこれらプラグインを追加し、Open Graphアクションをハイライトすることができます。チュートリアルでは、Activity Pluginを足してみましょう。

Activity

Activity Pluginは、アプリケーション毎にカスタマイズしたOpen Graphアクションをハイライトするようにアップデートされています。

<fb:activity actions="YOUR_NAMESPACE:ACTION-TYPE"/></fb:activity>

こちらがAdd to Timelineの全容で、Add to Timeline, アクション投稿, アクティビティプラグインが１ページ内に含まれています。

<head prefix="og: http://ogp.me/ns# YOUR_NAMESPACE: 
            http://ogp.me/ns/apps/YOUR_NAMESPACE#"> 
    <meta property="fb:app_id" content="YOUR_APP_ID" /> 
    <meta property="og:type" content="YOUR_NAMESPACE:recipe" /> 
    <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"> 

    <script type="text/javascript">
    function postCook()
    {
        FB.api('/me/YOUR_NAMESPACE:cook' +
                    '?recipe=http://example.com/cookie.html','post',
                    function(response) {
            if (!response || response.error) {
                    alert('Error occured');
            } else {
                alert('Post was successful! Action ID: ' + response.id);
                }
        });
    }
    </script>
</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://example.com/cookie.jpg" 
                            width="550"/><br />
        </p>       

        <form>
            <input type="button" value="Cook" onclick="postCook()" />
        </form>
        <fb:activity actions="YOUR_NAMESPACE:cook"></fb:activity>
    </body> 
    </html>

Step 6: Submit Your Actions For Approval

ユーザに対してOpen Graphアクションを投稿する前に必要なapproval processを紹介します。

Open Graphアクティビティは、アプリケーションの管理者,開発者,テスターには即座に見えるようになります。これにより徹底したテストが可能です。それが完了したらDev Appを通じてアクションを登録してレビューします。

あなたのOpen Graph利用が基準を満たしていると確認できたら、アプリケーションを承認し、全Facebookユーザに対してアクション投稿できるようになります。

プロセスの詳細に関してはこちらをご覧ください。

Debug and Troubleshoot

オブジェクトやアクションを実装する上で問題に直面した時に役立つヒントです。

How to verify your Objects are in the graph

object debuggerを使い、必要なメタタグが含まれているか確認できます。

How to verify your actions are published

object debuggerを用いてオブジェクトが正しく定義されているか確認します。
API呼び出しに正しいネームスペースを使っているか確認します。ネームスペースは一度保存したら変更できません。
Graph APIを呼び出す前に、access_tokenの&expiresを削除していることを確認してください。
Graph APIのPOSTリクエストでidが返されるのを確認してください。

Why am I getting "This method must be called with an app access_token" error when publishing an action?

Dev Appの設定ページで"Require app access token to write"チェックボックスのチェックを外してください。

Sample Code

このチュートリアルは Samples and How-Toからダウンロード可能です。

Facebook開発者向けドキュメントの日本語訳とTips

Tutorial