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

http://developers.facebook.com/docs/ に記載されているdocumentationの和訳と、調べていて分かったノウハウを紹介します。
Life is tough, so are we.
ドキュメント全体の目次はこちら
Facebook関連情報はFacebookページで共有しています。
2013年06月28日21:01

by oklahomer

2013/10/02の仕様変更

カテゴリ

あと2週間弱で2013/07/10 の仕様変更が有効になりますが、その次にくる10月の仕様変更が先日発表されました。ここでは、その仕様変更の内容を紹介します。

4fcc6c21c869a309cb62bb6f736fb008
  
10/02に強制移行となる新仕様と変更は以下の通りです。この内容はアプリの設定画面（Settings > Advanced > Migrations）にある「October 2013 Breaking Changes」を有効にすることで、早めに移行することも可能です。 
  1. Game Achievement APIの変更。
    ゲームカテゴリのアプリで、ユーザが何かを達成してポイントを得たりする際に利用するAchievement APIですが、それがアップデートされます。カスタムプロパティがdataフィールドに含まれるようになり、他のOpen Graphアクションと同じように利用できるようになります。
  2. /USER_ID/likes のデフォルト値変更。
    現状の仕様では、ユーザのいいね！全件を返しますが、この変更後はデフォルトで25件のみ返されるようになります。また、他APIと同様にpagingプロパティが返されるようになるので、それを利用してページングすることが可能です。
  3. /POST_ID/likes のデフォルト値変更。
    現状の仕様では、直近の4件のみ返されていますが、仕様変更以降は全いいね！が取得できるようになります。いいね！数はsummaryフィールドで返されるようになります。
  4. ネットワークを利用したプライバシー設定の削除。
    以前は、ユーザが属するネットワーク別にプライバシー設定ができましたが、既にFacebook本体で利用できなくなっているため、Graph APIやFQLでも利用できなくなります。今現在、投稿時のプライバシー設定でネットワークが指定された場合、「自分のみに公開」で投稿するのと同等の動作になっています。移行完了後は、ネットワークが指定された場合はエラーが変えるようになります。「Facebook今昔物語 ~あのころ僕らはリア充だった 2005夏~」で紹介した通り、ネットワークを越えての交流に制限があるなど、昔はネットワーク設定の持つ意味は大きかったのですが、ちょっと寂しいですね。
  5. Graph APIを利用して友だちのタイムラインに投稿できなくなる。
    友だちのウォールへの投稿がユーザの不満に繋がるケースが多いため、これは利用できなくなります。Feed Dialogを利用し、ユーザによる入力を介して投稿するのは引き続き可能です。「Open Graphアプリとウォール投稿が一部規制される詳細」で紹介した内容の延長ですね。
  6. FQLとGraph API利用時の limit=0 仕様変更。
    これまで、APIのバグの為に limit=0 を利用した場合に全件が返されていましたが、今後は0が指定された場合は0件のみ返されるようになります。
以下の内容も10/02に有効になりますが、アプリの設定で早期に移行することはできません。
  1. iOSとAndroidのネイティブアプリは、ログイン時に公式SDKを利用しなくてはならない。
    追記：AppleのSocial frameworkを引き続き利用することはできますが、 フォールバックでは結局iOS SDKを利用しなくてはならなくなります。この煩雑な手順を実装するには手間がかかるため、単にiOS SDKのみ利用することが推奨されています。
詳細についてはDeveloper Roadmapを参照してください。
 
2013年06月23日19:07

by oklahomer

「信頼できる連絡先」設定：「なりすまし3人でアカウント乗っ取り」の対応

カテゴリ

スパムアカウント3人と友だちになってしまうとアカウントを乗っ取られる可能性がある、という話について、Facebookの提供する「信頼できる連絡先」設定を用いて対応する方法を紹介します。

前提

詳細は以下のリンク先の通りですが、なりすましアカウント3人と友だちになってしまうと、アカウントが乗っ取られてしまうという話があります。
ますます巧妙になるFacebookアカウント乗っ取り。Facebookマーケティングのプロが教えるその傾向と対策。 @reosucker
先週あたりあちこちで取り上げられていて、大体の記事は「スパムアカウントとは友だちにならないようにしましょう」と結んでいました。

残る不安

が、それだけだと以下のような不安も残ります。
  • 友だちアカウント3つが乗っ取られて、それらを使って自分のアカウントが取られたら...
  • 先週捨てた元カノとその友だち2人に恨まれていたら...
  • 先週リストラした部下3人に恨まれていたら...
こうした場合、脅威となるのは偽アカウントだけではなくリアルなアカウントです。

信頼できる連絡先

おそらくFacebook側の想定している正しい対策としては、「信頼できる連絡先」の設定があります。「アカウント設定 > セキュリティ > 信頼できる連絡先」で3~5件設定できるもので、ここで設定しておくと、その相手に対してセキュリティコードが送られるようになる為、勝手に相手を選ばれてしまうことが無いようです。

5

これが設定中の画面。
あくまでキャプチャ用に入れてるので、今はこの4人じゃないですよ！

2a4e90fc1838427922913db373113e64

2013/07/13 追記：
設定が完了すると、選んだ相手に対して以下のような通知が送られます。
0b8f1cf79c7f21f760043cbf4577b1c1
追記終わり

この設定以降、悪意ある人間が「パスワードを忘れた方はこちら」の手順を踏もうとしても、設定した連中にしか送信することはできません。また、「信頼できる連絡先を表示」をクリックした際、相手の名前を正しく入力しないと次に進めなくなります。
3
設定している相手のうち1人の名前を正しく入力すると、設定した全アカウントが表示され、次のステップへ。
2
とはいえ、これらの信頼できる相手が乗っ取られるとややこしいですね。
遺産相続の話のもつれから、信頼できる相手が一夜にして悪意の第３者になるとかもドラマティック！あと数年したら、生活笑百科でこういう話も出てくるんでしょうか。

ヘルプ

詳しくは公式ヘルプをご覧ください。
信頼できる連絡先とは何ですか。アカウントに信頼できる連絡先を追加するにはどうすればよいですか。
2013年06月21日02:32

by oklahomer

OGPの仕様追加：記事にひもづくFBページや個人アカウントとの連携を強める

カテゴリ

先日の開発ブログで、OGPの仕様追加が公開されました。これを用いることで、記事がニュースフィード上に流れるとき、その記事にひもづくFBページへのいいね！や個人アカウントのフォローを促すことができるようになります。

方法

方法は簡単で、Facebookページを紐づけるならarticle:publisherを指定
<meta property="article:publisher" content="https://www.facebook.com/cnn" />
個人アカウントを紐づけるならarticle:authorを指定します。 
<meta property="article:author" content="https://www.facebook.com/fareedzakaria" />
fb:adminsで指定していたのとは別に指定する必要があるので気をつけてください。
これにより、Facebookページを紐づけているならいいね！ボタンが、個人アカウントを紐づけているならフォローボタンが、記事がニュースフィード上に流れる時に出ることになります。 

851575_484225854997088_516067102_n

 また、フォローやいいね！が出るのは、閲覧者がまだフォローやいいね！をしていない場合のみとなります。

Facebook側のキャッシュ

ただし、既存の記事に対してこのタグを追加しても、すぐには反映されない場合があります。Facebook側でページの情報をキャッシュしているためです。これをクリアして再取得させるには、Facebook Debuggerを用いるのが確実です。 以下のキャプチャの一番下の項目をみると、article:publisherとして追加したFBページのIDが出ているのがわかります。

ogp

多量のページのキャッシュを更新させる必要がある場合は、Facebook DebuggerのAPIを用いると便利です。Facebook::OpenGraphにはcheck_objectというメソッドが用意されていて、キャッシュの有無にかかわらず強制的にスクレイピングさせ、キャッシュを更新するとともにOGPの内容をチェックさせる実装になっています。
https://github.com/oklahomer/p5-Facebook-OpenGraph/blob/master/lib/Facebook/OpenGraph.pm#L516
2013年06月16日14:12

by oklahomer

ドキュメントのURLとか名称とか構成が変わりすぎて腹が立つ

カテゴリ
ドキュメント
小ネタ

今月上旬にFacebook::OpenGraph 1.00を出しました。Facebook Platformの定める主要な機能を実装しおわった状態で、利用法をまとめたCookbookや日本語版PODのJA.podは置かれていないのですが、利用法は t/ 配下のテストを見て頂くと分かると思います。が、今回はモジュール本体についての話ではなく、ドキュメントのURLとか名称とか構成が変わりすぎて腹が立った話です。

公式ドキュメントへのリンク

Facebook::OpenGraphでは、本家ドキュメントURLや ドキュメントの要所要所の引用をコード中にコメントとして残しています。POD中にも概要ページへのリンクなど残してあるのですが、そちらはあくまでモジュールの使い方が中心で、細かい実装面については以下のようにコード中で参照しているという具合です。
# ページ名: セクション名
# https://developers.facebook.com/該当ページのパス
sub method_name {
    my ($self, $foo) = @_;
    # 仕様の抜粋
    ........
}
ですが、こうしてリンクを残していても、リンク先ページはしょっちゅう変わってしまいます。たとえば、コメントで参照しているURLを最新のものに置き換えた結果がこちら。
Update document links · 957ab92 · oklahomer/p5-Facebook-OpenGraph · GitHub

直近数ヶ月の変更だけでこれです。けっこう多めですが、各項目に機能が増えて来たり複雑になってきて整理し直すというのは分かりますから、ある程度は仕方ありません。

改悪!!

ただ納得いかないのは、認証・認可のフロー周りのドキュメントがかなりの頻度で分割されたり構成が変わったりして、ただでさえ複雑なのが余計に分かりにくくなっている点です。たとえば今回の変更の一部だと以下のように。

b1d4703121320e07e843f2f08d0fead1

これは signed_request をパースする箇所なのですが、去年後半のドキュメントは"Using the signed_request Parameter（signed_requestパラメータを利用する）"というタイトルで、該当セクションの名前は"Parse the signed_reqeust（signed_reqeustをパースする）"でした。これはとても分かり易いと思います。
で、変更後は以下の通り。
  • ページ名：Using Login with Games on Facebook（Facebook上のゲームにログインする）
  • セクション名：Parsing the Signed Request（Signed Requestをパースする）
Games on Facebookということは、facebook.com内でiframe表示する canvas タイプのゲームアプリを指しているように見えます。ですが、signed_requestパラメータを利用するタイミングはそれだけではありません。ぱっと思いつく限りでも以下の数パターンがあります。
こうして見ると、明らかに前のタイトルの方が分かり易い気がしませんか。私ならGames on Facebookなんて書かれていたら読み飛ばしてしまいそうです。あと細かい話ですが、該当セクションに直接飛ばした場合、セクション名がヘッダに隠れてしまってちょっと分かりにくい...

まとめ

親切心から該当ドキュメントのリンクを残していても、かなり高い頻度で遷移先のページが更新されているので、その旨も共有しておかないと余計に混乱するので気をつけましょう。私が過去の仕様を確認する場合は、Wayback Machineで当初の日付前後まで遡るようにしています。そういった場合は、ドキュメントのリンクと同時にその日付も残しておくと分かり易いと思います。
95ad8ae82936a527dca619a5ed3b795b

おまけ

以下、ドキュメント周りを追って来て思う全体の流れです。
これまでの大まかな流れとしては以下のような感じ。
  1. 2009~2010年
    ドキュメントやwikiの状態が古く、リンク切れも多い状態。
    旧フォーラム（今はfacebook.stackoverflow.comへ移行）で情報交換するのが主流
  2. 2010~2011年あたり
    ドキュメントの更新が活発になり、2011年f8でのOpen Graph Action/Object発表以降は特に力を入れるようになった。
    バグ報告も外部から見えるように管理され始めた。
    stackoverflow.comで一般的な内容を聞くと怒られるので、概要についてはQuoraなどで聞く人が出てくる。
  3. 2012年後半
    /docs/howtos/* 配下に項目毎にページが置かれ、ページ毎にStep1から手順を追って解説
  4. 2013年前半
    細かい仕様については /docs/technical-guides/* 配下、概要については /docs/* 配下にまとめ始めた？
2013年05月27日22:38

by oklahomer

続・PHP SDKに足されたappsecret_proofというパラメータ

カテゴリ

先日のエントリーで、PHP SDKの最新版で追加されたappsecret_proofというパラメータを紹介しました。その際、appsecret_proofの値について現段階ではバリデーション処理は行われていないらしいものの、appsecret_proofに絡む例外についてstackoverflow.comでトピックが上がっていたとも紹介しました。このトピックやappsecret_proofについて進展があったので紹介します。

アプリの設定画面

先日確認した段階では、アプリの設定画面上でappsecret_proofの設定を見つけられなかったのですが、今朝、見つけました。アプリの設定画面で Advanced > Security に行くと「Require AppSecret Proof for Server API calls」という項目があり、ここで有効／無効の設定ができます。

e7f93b0b3cb1c81b639bf4bfb03ef3f5

24日に新規作成したアプリでも「無効」になっていたので、今のところ、「新規でアプリを作成したら最初から有効になっていた！」などの混乱は起きなそうです。では、なぜこれに絡んだ問題がstackoverflow.comに投稿されていたのか、という問題に関しては後ほど説明します。話は逸れますが、新しく作ったアプリでのみ、数個上の項目に「Client Token」という項目が表示されていました。カーソルを重ねると「The Client Token is for auth methods in place of the app secret」と説明が出ます。

AppSecret Proofを有効にする

まずテストユーザを作成し、AppSecret Proofを無効にしたままでユーザの基本情報を取得してみます。
Oklahomers% curl -X GET \
> 'https://graph.facebook.com/me?access_token=XXXXXXXXXXXXXXX'
{"id":"100006006484235","name":"Linda Amfkfdhdbce Letuchysen","first_name":"Linda","middle_name":"Amfkfdhdbce","last_name":"Letuchysen","link":"http:\/\/www.facebook.com\/profile.php?id=100006006484235","gender":"female","timezone":0,"locale":"ja_JP","updated_time":"2013-05-27T13:39:27+0000"
}
appsecret_proofなしでも取得できました。PHP SDK内での挙動と同様にするため、POSTメソッド利用で?method=GETパラメータを付けて実行してみます。
Oklahomers% curl -X POST \
> -F 'access_token=XXXXXXXXXXXXXXX' \
> -F 'method=GET' \
> https://graph.facebook.com/me
{"id":"100006006484235","name":"Linda Amfkfdhdbce Letuchysen","first_name":"Linda","middle_name":"Amfkfdhdbce","last_name":"Letuchysen","link":"http:\/\/www.facebook.com\/profile.php?id=100006006484235","gender":"female","timezone":0,"locale":"ja_JP","updated_time":"2013-05-27T13:39:27+0000"}
この場合も取得できました。
いよいよ、設定画面でAppSecret Proof for Server API callsを有効にします。

09ca3a3567692b37c90e72ae56f91622

Oklahomers% curl -X GET \
> 'https://graph.facebook.com/me?access_token=XXXXXXXXXXXXXXX'
{"error":{"message":"API calls from the server require an appsecret_proof argument","type":"GraphMethodException","code":100}}

Oklahomers% curl -X POST \
> -F 'access_token=XXXXXXXXXXXXXXX' \                         
> -F 'method=GET' \
> https://graph.facebook.com/me
{"error":{"message":"API calls from the server require an appsecret_proof argument","type":"GraphMethodException","code":100}}
いづれの場合も失敗しました。例のトピックで挙げられている例外と同じメッセージのようです
そこで、PHP SDKの中でやっているのと同等の操作でappsecret_proofの値を生成してみます。
Oklahomers% perl -MDigest::SHA -e 'print Digest::SHA::hmac_sha256_hex("XXXXXXXXXXXXXXX", "APP_SECRET_VAL")'
yyyyyyyyyyyyy86fb3f7fd3d8ceeb887544af6ff7f541d5f7b46xxxxxxxxxxxxxxx
これを用いて、再度ユーザの基本情報を取得してみます。
Oklahomers% curl -X POST \
> -F "access_token=XXXXXXXXXXXXXXX" \
> -F "appsecret_proof=yyyyyyyyyyyyy86fb3f7fd3d8ceeb887544af6ff7f541d5f7b46xxxxxxxxxxxxxxx" \
> -F "method=GET" \
> https://graph.facebook.com/me
{"id":"100006006484235","name":"Linda Amfkfdhdbce Letuchysen","first_name":"Linda","middle_name":"Amfkfdhdbce","last_name":"Letuchysen","link":"http:\/\/www.facebook.com\/profile.php?id=100006006484235","gender":"female","timezone":0,"locale":"ja_JP","updated_time":"2013-05-27T13:39:27+0000"}

Oklahomers% curl -X GET \
> "https://graph.facebook.com/me?access_token=XXXXXXXXXXXXXXX&appsecret_proof=yyyyyyyyyyyyy86fb3f7fd3d8ceeb887544af6ff7f541d5f7b46xxxxxxxxxxxxxxx"
{"id":"100006006484235","name":"Linda Amfkfdhdbce Letuchysen","first_name":"Linda","middle_name":"Amfkfdhdbce","last_name":"Letuchysen","link":"http:\/\/www.facebook.com\/profile.php?id=100006006484235","gender":"female","timezone":0,"locale":"ja_JP","updated_time":"2013-05-27T13:39:27+0000"}
どちらの方法でも取得できることを確認できました。 先日stackoverflow.comで報告していた人は、何かの拍子で設定画面の該当項目を有効にしてしまったものの、PHP SDKがまだ最新ではなかった為にappsecret_proofパラメータが渡されていなかったようです。 その旨を返しておいたので、のちほど本人から回答が来てハッキリするかもしれません。
2013/06/30追記：06/26に質問者からコメントが着きました。やはり何かの拍子に設定画面をいじってしまったらしく、appsecret_proofの利用がONになっていたようです。設定をいじっていないのにいきなりappsecret_proofが求められるということは無いと分かったので一安心ですね。
記事検索