2014/4/30にFacebook Graph APIが2.0にバージョンアップしました。

Business Mapping APIやTaggable Friends API等、未検証項目が多いですが、公式サイトを調べたメモを書き留めておきます。

詳細に関しては公式サイト(英文)を参照ください。

さくっと確認したい人向け

APIのendpointが変更に
- 2014/04/30までに作成したアプリは2015/04/30まで /{object}のURLが /v1.0/{object}へのアクセスと同様になる
- 2014/05/01以降に作成したアプリは2016/04/30まで /{object}のURLが /v2.0/{object}へのアクセスと同様になる
友達に対するAPIアクセス権限が新しくなった
- v1.0では権限を指定せずにアプリ側で友達一覧が取得できたが、友達情報を取得するにはuser_friends権限が必要になった
- /me/friends はアプリ認証済みの友達のみを返すようになった
アプリ認証時に求められる権限が任意選択可能に
- 必須権限に関してはアプリ側で制御する必要がある
- /me/permissionsで個別の権限チェックができる
- ログインのたびに足りない権限があれば再度チェックを求めることも可能
アプリによってはFacebookによるレビューが必要になる
- public_profile, email and user_friends を超える権限を必要としているアプリはFacebookのレビューが必要になった
FQLはバージョン2.0でまだ提供されているが、次のバージョンでは利用できなくなるので注意
シェアダイアログが新しくなった
- New Share Dialogの詳細はこちら
  - toにuseridを指定して相手のウォールに投稿することができなくなった
- v2.0ではLegacy Feed Dialogsのtoやfrom項目にusernameを指定できなくなった
  - toにuseridを指定して相手のウォールに投稿することは可能
  - Legacy Feed Dialogsがいつまで使えるかは不明
APIを使ってアプリ認証していない友達の招待はできるか？
- /me/friendsで取得できる友達IDはアプリ認証済みのユーザのみになったので、アプリを使ってない友達のウォールに気軽に投稿するというのはできない
- Facebook上のcanvasアプリ（Game）であれば可能
- Game以外（例えばキャンペーンサイト等）で招待機能を実現するのは現在のところ無理

しっかり確認したい人向け

基本的な確認項目

APIのendpointが変更に
- 既存APIは /{object}でアクセスしていたが、新APIは /{version}/{object}でアクセス
- 新しいAPIは /v2.0/{object}
- 既存APIで使用していた /{object}のURLはサポートされている最も古いバージョンが自動的に使用される
  - 2014/04/30までに作成したアプリは2015/04/30まで /{object}のURLが /v1.0/{object}へのアクセスと同様になる
  - 2014/05/01以降に作成したアプリは2016/04/30まで /{object}のURLが /v2.0/{object}へのアクセスと同様になる
APIのサポート期間
- v2.0は2016/04/30まで有効
- v1.0は2015/04/30まで有効(こちらは1年間なので注意)

UserIDとFriendsに関する主な確認項目

アプリにスコープしたユーザID
- これまではFacebookユーザIDを自由に取得できたが、アプリに紐づくユーザIDを発行するように変更
- 複数のアプリ間で同じユーザをマッピングするには新しく追加されたBusiness Mapping APIを使用する必要がある
友達に対するAPIアクセス権限が新しくなった
- v1.0では権限を指定せずにアプリ側で友達一覧が取得できたが、友達情報を取得するにはuser_friends権限が必要になった
/me/friends はアプリ認証済みの友達のみを返すようになった
- 2014/04/30までに作成したアプリは2015/04/30まではv1.0として使用可能であるため友達情報をすべて取得することができる
- 2014/05/01以降に作成したアプリはデフォルトでv2.0が適応されるため、アプリ認証済みの友達しか取得できない
friend_* の権限がすべて削除された
- v1.0では友達の情報がすべて取得できたので、個別に権限を分けてあったがアプリ認証済みの友達情報しか取得できなくなったので個別権限は削除された
友達のリストはタイトルのみに
- v2.0になりmanage_friendlist権限は非推奨に

ログインに関する主な確認項目

アプリ認証時に求められる権限が任意選択可能に
- 必須権限に関してはアプリ側で制御する必要がある
- /me/permissionsで個別の権限チェックができる
- ログインのたびに足りない権限があれば再度チェックを求めることも可能
basic_info権限はpublic_profile権限に置き換えられた
- 公開プロフィールのみ必須権限となっている
- 友達リストはデフォルト権限から外れたので個別指定する必要がある
アプリによってはFacebookによるレビューが必要になる
- public_profile, email and user_friends を超える権限を必要としているアプリはFacebookのレビューが必要になった

Graph APIに関する主な確認項目

変更になった点

v2.0ではオブジェクトの画像取得以外のAPIはすべてアクセストークンが必要になった
/me/friendlists の返却内容が変わった
/me/permissions の返却内容が変わった

新規追加のendpoint

/me/taggable_friends：タグ付け用API
/me/invitable_friends：招待用API(Facebook.com上のゲームアプリのみ使用可能)
/me/tagged_places：v1.0の /me/locationsの置き換え
/{object-id}?fields=context：Social Context API（未調査）
/me/ids_for_business:Business Mapping API（未調査）

削除されたendpoint

/me/username
/me/locations
/me/checkins
/me/questions
/me/subscribers
/me/subscribedto
/me/notes
/{page-id}/notes
/{page-id}/questions
/search?type=post&q=foobar
/me/home?q=foobar

FQL

FQLはバージョン2.0でまだ提供されているが、次のバージョンでは利用できなくなる
開発者は可能な限り早くFQLからGraphAPIに移行すべき

Tagging People
- v2.0からは友達リストはアプリを使っていないユーザを含めなくなったので、Taggable Friends APIを使用してタグ付けする必要がある
- user idの代わりにtokenを用いて更新を行う
App links
- 詳細は applinks.org
New Share Dialog for Web
- 詳細はこちら
- 既存のダイアログと同様に使用できるが、追加としてログインなしでOpen Graph storiesを投稿できるようになった
Legacy Feed and Share Dialog
- v2.0ではLegacy Feed Dialogsのtoやfrom項目にusernameを指定できなくなった
Legacy Feed Dialogであればv2.0でもtoを指定して相手のウォールに投稿することが可能
- Legacy Feed Dialogがいつまで使えるかは不明

      FB.ui({
        method: 'feed',
        link: 'https://developers.facebook.com/docs/dialogs/',
        caption: 'An example caption',
        to: '{userid}'
      }, function(response){});

New Share Dialogだとtoを指定できない

      FB.ui({
        method: 'share',
        href: 'https://developers.facebook.com/docs/dialogs/',
        caption: 'An example caption',
        to: '{userid}'
      }, function(response){});

Games and Payments

省略

APIを使ってアプリ認証していない友達の招待はできるか？

/me/friendsで取得できる友達IDはアプリ認証済みのユーザのみになったので、アプリを使ってない友達のウォールに気軽に投稿するというのはできない

ver2.0で友達招待機能を実現するには

Invitable Friends API
Taggable Friends API

の2通りの方法がある

Invitable Friends API

Invitable Friendsを使用するにはcanvasのgameアプリである必要がある

gameはアプリのカテゴリでゲームを選択すれば適用された

canvasアプリの場合は、INVITE_TOKENを用いてjs SDKからユーザ招待ダイアログを表示できた

FB.ui({method: 'apprequests',
       message: 'YOUR_MESSAGE_HERE',
       to: 'INVITE_TOKEN'
}, requestCallback);

canvasアプリではない場合は相手ユーザに通知が届かないので注意

Taggable Friends API

別の方法としてタグ付けも用意されている

invitable friendsと同様に、IDがtokenになっているので、tokenをもとに

/{user-id}/feed
Open Graph story tagging
Open Graph story mentions

を使えば実現できそう

事前にFacebookのレビューが必要だったので未検証

5/9 タグ付け関連追記

Taggable Friends APIやタグ付けを本番環境で使用するにはFacebookのレビューが必要だが、一般公開しない状態（sandboxモード）であればレビューなしでも検証できたので追記

APIは Graph API Explorer を使って試した

1. /{user-id}/feed を使ってタグ付けを行う場合

* messageに文言を入力
* tagsにTaggable Friends APIで取得したtokenidを入力
* placeに該当するplace idを入力
* linkにURLを入力

上記設定で友人のタグ付け投稿はできた

注意事項
- Facebookガイドラインでmessageを自動入力することは禁止されているので、ユーザから文言を受け取り、それをmessageパラメータとしてpostする必要がある
- 実際にその場にいないのにも関わらず場所のタグ付けを行うこともガイドライン違反になるので注意

2. Open Graph story mentions を使ってmentionを送る場合

こちらも試してみたが、結果的には

Mention tokens must be in @[username], @[userid] or @[facebook user profile URL]

と表示されうまくPOSTできなかった

検証方法
- まずアプリダッシューボードの「オープングラフ」設定でカスタムストーリーを作成
- もしくはcommon actionである「Like」を作成（共通項目ではあるが個別設定が必要であるためaddする必要がある）
- 該当アクションを選択して設定画面に移動し、Capabilitiesの「Tags」,「User Messages」のチェックをオンにする
- API Explorerで/me/og.likesを指定
  - messageに @[tokenid] を指定
  - objectにURLを入力
- 送信すると Mention tokens must be in @[username], @[userid] or @[facebook user profile URL] とエラーになってしまう

招待機能に関するまとめ

Game以外のキャンペーン等でv2.0を使用する場合、現在のところ無理でした
Open Graph story mentionsのエラーに関して調べたところ、issueとして上がっていたので近いうちに修正される模様です