「Facebook Night vol.7 発表内容まとめ 1：publish_streamとpublish_actions」で主要な2パーミッションの違いを、「Facebook Night vol.7 発表内容まとめ 2：認証ダイアログの構成」では、それら2つの認証ダイアログ上での扱いの違いを紹介しました。その過程で、ユーザがアプリをインストールしたからと言って、全部のパーミッションを許可しているとは限らないことや、あとからFacebook上の設定ページでパーミッションが消されうることを話しました。ここでは、それに対応する実装方法を紹介します。
与えられたパーミッションを確認する
例えば機能の1つとして、ユーザの好きな本一覧を取得し、そこからおススメの本をレコメンドするような機能を提供していたとします。user_likesパーミッションが許可されなかったり消されたりしたら必要なデータを読み込めなくなってしまいますから、算出方法を切り替えるとか、場合によっては該当ユーザへのレコメンド機能自体を非表示にする必要が出てくるかもしれません。それには、ユーザがどのパーミッションを許可してくれているのか、少なくともユーザがサービスを利用する旅に知る必要があります。これにはGraph APIのユーザオブジェクトのpermissionsコネクションを参照します。
以下の2種類のいずれかを用います。
curl -X GET "https://graph.facebook.com/me/permissions?access_token=USER_ACCESS_TOKEN"
curl -X GET "https://graph.facebook.com/{USER_ID}/permissions?access_token=APP_ACCESS_TOKEN"{
"data": [
{
"installed": 1,
"publish_actions": 1,
"user_likes": 1,
}
]
}許可されたパーミッションをキー、許可されているか否かの真偽値を値に持ちますが、installedというのだけ若干例外で、アプリをインストール済みか否かを指します。ユーザのアプリインストール時やログイン時、このAPIを利用してどのパーミッションが与えられているのかをチェックすることになります。Batch Request
- 認証ダイアログのページへリダイレクト
- 完了後、アプリ側（redirect_uri）へリダイレクト
- 渡されたcodeパラメータを元にアクセストークン取得
- ユーザ情報取得
Real-time Update API
場合によっては、ユーザのログイン時だけでなく、よりリアルタイムにパーミッションの変化を知りたい場合があります。例えばユーザのステータス投稿を定期的に取得したいならuser_statusパーミッションが必要となりますが、このパーミッションがFacebook上の設定画面から削除されてしまった場合、Batch Requestで紹介した方法ではユーザが次にログインするまで削除されたことを知ることができず、定期実行時にエラーが出続けることになります。Real-time Update APIを利用すると、Facebook上でGraph APIオブジェクトやそのコネクションに変化があった際にリアルタイムに受け取ることが可能です。PubSubHubbubに詳しい方は取っ付きやすいかもしれませんが、渡されるのがJSONだったりするなどの違いがあります。quoraで紹介されている限りでは、昔はPubSubHubbubで実装されていたものの、他のGraph APIの仕様との一貫性などの理由から変更したそうです。
流れ
どの情報を購読するのか、どのコールバックURLで通知を受けるのかを、Graph APIを用いて設定する必要があります。流れは以下の通りです。
それでは詳細を見てみます。
Step1. リクエスト送信
アプリがFacebook側へリクエストを送り、購読の対象を指定します。curl -X POST http://graph.facebook.com/{APP_ID}subscriptions \
-F "object=permissions" \
-F "fields=email,publish_actions,user_birthday,read_friendlists" \
-F "callback_url={CALLBACK_URL}" \
-F "verify_token={APP_GENERATED_TOKEN}" \
-H "Authorization: OAuth {APP_ACCESS_TOKEN}"
- object: 購読する対象のオブジェクトのタイプを指定します。指定できるのはuser、page、permissionsのいずれかです。今回はpermissionsを指定します。
- fields: 上記objectのプロパティもしくはコネクションの中で、購読したいもの。カンマ区切りでパーミッションを指定します。
- callback_url: objectとfieldsで指定した対象に変化があったときに通知を受け取るURL。
- verify_token: アプリ側で指定するトークンです。Facebookからの確認用リクエストで送られてきます。
Step2. 確認用リクエスト受信
FacebookからアプリのコールバックURLへとリクエストが送られてきます。ここで渡されるパラメータは以下の通りです。curl -X GET "{CALLBACK_URL}?hub.mode=subscribe&hub.challenge=XXXX&hub.verify_token={APP_GENERATED_TOKEN}"
- hub.mode: これは常にsubscribeが渡ります。
- hub.verify_token: 最初のリクエストでこちらから渡したverify_tokenがそのまま渡ってきます。アプリ側での確認用です。
- hub.challenge: Facebookが生成して渡してくるランダムな文字列。レスポンスとして、status200と共に返します。
Step3. レスポンスを返す
Facebookから渡されたhub.verify_tokenがアプリ側から送信したverify_tokenと一致することを確かめたら、HTTP Status 200とverify_tokenの値を返します。Step4. 最初のリクエストのレスポンスを受け取る
Step3までが正しく完了すればstatus 200が返り、不備があればstatus 400が返ります。購読状況を確認する
購読中の内容を確認するには以下のエンドポイントにアクセスします。返り値は以下のキャプチャの通りです。userオブジェクトのevents, locale, nameフィールドを購読していることが分かります。話が逸れてしまいますが、この発表の前の週にReal-time Update APIのドキュメントに変更があり、userオブジェクトのeventsコネクションも購読できるようになりました。userオブジェクトのドキュメントには反映されていませんが、テストした限りでは、キャプチャの通り購読できているようです。curl -X GET "https://graph.facebook.com/{APP_ID}/subscriptions?access_token={APP_ACCESS_TOKEN}"
購読の解除
任意のオブジェクトのみ購読解除
curl -X DELETE "https://graph.facebook.com/{APP_ID}/subscriptions?object=XXX"
全購読解除
objectパラメータを付け忘れると全購読が解除されますので注意してください。curl -X DELETE "https://graph.facebook.com/{APP_ID}/subscriptions"
また、ここに限らず、Graph APIでHTTP DELETEメソッドを使う箇所はmethod=deleteパラメータ指定でのHTTP POSTリクエストでも代用できます。
通知
実際の通知内容は以下のキャプチャのようになります。
こうして通知されたオブジェクトIDとフィールドを元に、Graph APIで最新情報を取得してくることになります。変更されたオブジェクトの情報がある程度まとめて送られてきますので、ここでもBatch Requestを活用すると効果的です。
ユーザがFacebook上でアプリを削除してしまったら？
アプリで退会処理を踏まず、Facebook上の設定・管理画面からアプリを削除されてしまうこともあり得ます。そういった場合の対処方法は「ユーザがFacebookアプリを削除したときに通知を受けるには」を参照してください。おまけ
ドキュメントの更新が激しくて、それに追いつくの大変ですよねという話をしました。公式ブログのエントリーで、その週に更新されたドキュメントURLがリストアップされていたこともありましたが、該当ページのどの部分が更新されているかを把握するのも面倒でした。また、前任者が実装したシェアボタンのドキュメントが、シェアボタンといいね！ボタンの統合で消えてしまったりして、あとから追いようが無いという問題もありました。そこで、6月上旬からはFBDocsで https://developers.facebook.com/docs/* のページをバージョン管理しています。左ナビゲーションのリンク先も、ドキュメント内のリンクであれば href="/docs/XXX" に置き換えてありますので、git cloneしてきて確認したいバージョンに戻しておいて、ブラウザで http://localhost/docs/XXX にアクセスして確認すると、当時のバージョンのまま遷移もできて少し便利かなと思っています。
今後ドキュメントの和訳を更新する際は、githubのコミットログのページか何かへのリンクを張るとかして、どの段階まで対応しているかを明示します。「この和訳の更新が追いついていないんだけど」とかあったらOklahomerページにメッセージ送るなどしてお知らせください。
