Facebook API v2.2 リリース 「token_for_business」についてまとめ

11.4
2014

v2.2_01

日本人がハロウィンに浮かれて馬鹿騒ぎをしている間に、FacebookからGraph API version2.2がリリースされました。
(正確には、ハロウィンより前にリリースされてますけど)

Graph API v2.2 and updated iOS and Android SDKs
https://developers.facebook.com/blog/post/2014/10/30/graph-api-v2.2/

今回の変更点は主にFacebookページの管理・更新をAPI経由で行う場合に影響が及ぶものが多く、また、機能の統廃合ではなく新機能が追加された形がほとんどなので、前回・前々回のバージョンアップと比べるとそれほど影響は大きくありません。

v2.2の主な変更点

Facebookのブログにあるハイライトを確認してみます。

  • Apps can now programmatically hide and unhide comments on Page posts.
  • A new token_for_business field on the User object makes it easier to identify the same person across multiple apps owned by the same business.
  • There’s a new way to manage Page subscriptions for realtime updates via a dedicated subscribed_apps edge.
  • More of a Page’s attributes are now editable via the API through the Page node or the settings edge.
  • アプリから(APIを通して)Facebookページの投稿に付いたコメントの表示・非表示を変更できるようになった。
  • Userオブジェクトに新しく追加された「token_for_business」により、ビジネスマネージャーを使って管理している複数のアプリ間で同一ユーザーを判別するのが容易になった。
  • Facebookページの更新情報をリアルタイムに通知する、専用の「subscribed_apps」edgeがAPIに追加される
  • APIを通して、Facebookページの管理・更新がより多くの項目で可能になった。

で、例えば「subscribed_apps」周りについては以下のブログでとても詳しく解説されています。

Facebook Graph API v2.2 リリース: 各種更新のサーバ間通知機能が熱い件|blog::dameningen

「token_for_business」について

さて、変更点の中で気になったのは、「token_for_business」に関して。
複数のアプリ間で同一ユーザーを判別するため、とのことですが、従来のBusiness Mapping APIとの違いなどが気になったので、簡単に調べてみました。

おさらい

API v2.0以降からユーザーIDの仕様が変更され、「app-scoped ID」という、アプリごとに変わるユーザーIDになりました。
このため、複数のアプリ間で同一のユーザーを判別することが出来なくなりました。
それに伴い、同じ管理者が所有するアプリ間であれば同一ユーザーを判別することが出来る仕組み「Business Mapping API」というものが提供されています。

mapping5

この辺の話について、詳しくはこちら↓

Facebook「Business Mapping API」の使い方と「app-scoped ID」について

今回、v2.2リリースのタイミングで公開された新しい「token_for_business」というフィールドは、複数のアプリ間で同一ユーザーを判別するために使えるということで、上記の「Business Mapping API」と用途が被る気もしますが実際どうなのか、調べてみました。

「token_for_business」とは

「token_for_business」は、ユーザーオブジェクトに追加されたフィールドです。
下記の要領で取得できます。

v2.2_02

/me?fields=token_for_business

なおこのフィールドは、ユーザーオブジェクトのデフォルトには含まれないので、明示して引っ張る必要があります。
これで返ってくる文字列は、ビジネスマネージャー毎の値になります。
つまり、同じビジネスマネージャーに登録されている複数のアプリで、すべて同じ文字列が返ってきます。

v2.2_03

なるほど、この値を使うことでアプリ間で同一のユーザーが判別できそうですね。

※ちなみに、「token」などという名前が付いていますが、別に「access token」とは何の関係もありません。

「token_for_business」について詳しく

Facebookの公式docsは以下です。

Mapping the same user across multiple apps
https://developers.facebook.com/docs/apps/for-business#field

  • The person being queried must have logged into this app
  • This field can be called with an app access token, or a user access token. If using a user token, the person being queried must be the same person for whom the token was generated.
  • If the owning business changes, the value of token_for_business will also change
  • If you request the token_for_business field and the app is not associated with a Business Manager, the call will error
  • The value returned by token_for_business is a token, not an ID – it cannot be used directly against the Graph API to access a person’s information. You should still store the ID in your database, and use this to call the Graph API to get that person’s information.
  • token_for_businessを参照する際、ユーザーはそのアプリにログインしている必要がある
  • token_for_businessは、app access tokenもしくはuser access tokenで呼び出すことが出来る。user access tokenを使う場合は、そのトークンを作成したユーザーと参照しているユーザーが同じでなければならない。(※例えばFB.apiなりを使えば勝手にトークン設定してくれるから気にする必要ないですけど。)
  • アプリを関連付けているビジネスマネージャーを変更した場合(別のビジネスマネージャーに関連付けを変更したり)、token_for_businessも変わってしまいます。
  • token_for_businessを参照する際に、アプリがビジネスマネージャーに関連付けられていない場合は、Errorが返ります。
  • token_for_businessはあくまでもtokenであってIDではないので、このtokenを使ってGraph APIを叩き、ユーザーの情報を得ることはできません。今まで通り、ユーザーのIDをDBなどに保存して、APIを叩くときにはそのIDを使って叩く必要があります。

ビジネスマネージャーの関連付け先を変えた場合はtoken_for_businessも変わってしまう、ってのがちょっと不安ですね。
まあ、そう頻繁に変えるものでもないと思いますけど。

また、公式docsには下記の記載もありました。

For convenience, the token_for_business field is available in all API versions

全てのAPIバージョンで使える、とのこと。
v2.2以降というわけではなく、旧バージョンでも使える、ってことですね。

実際に「token_for_business」を取得してみる

というわけで、実際に簡単な動作サンプルを使って「token_for_business」を取得してみました。

token_for_businessの取得部分はこんな感じです。

FB.api('/me/', {fields: 'token_for_business'}, function(response) {
	if (!response || response.error) {
		var read_err_text = 'Error';
		$("#biz_token").text(read_err_text);
	} else {
		var read_ok_text = response.token_for_business;
		$("#biz_token").text(read_ok_text);
	}
});

いつも通りデモページはJS直書きですので、適宜ソース見てください。

token_for_business取得デモ – v2.2
token_for_business取得デモ – v2.1
token_for_business取得デモ – v2.0
token_for_business取得デモ – v1.0

v2.2_04

ご覧の通り、API v1.0も含めて全て同じ値が取得できています。
Business Mapping APIを利用した場合、V1.0のアプリでは利用できませんでした。
そこは大きな違いの一つですね。

なお、デモで使っている4つのアプリは全てビジネスマネージャーに登録しています。

v2.2_05

「Business Mapping API」と「token_for_business」は何が違うのか

Business Mapping API

Business Mapping APIは、その名の通りマッピングを行うAPIです。
取得するデータのイメージを図にすると下記のようになります。

v2.2_06

見てわかる通り、同じビジネスマネージャーに関連付けられたアプリの場合、どのアプリに対してBusiness Mapping APIを叩いても、各アプリにおけるそのユーザーのIDが全て入った状態で返ってきます。

これは、各アプリで利用するというよりも、マスターとなるようなアプリを用意し、そのアプリで利用するイメージです。
例えば、プラットフォームへの「ログイン」アプリなどにこのAPIを実装すれば、そのプラットフォームで提供する個別のアプリに対しても一括でログインさせるようなことも可能..かも。(もちろん、単なる名寄せも可能)

ただし、API v1.0では利用できません。

token_for_business

一方でtoken_for_businessは、前述の通り下記のようなイメージです。

v2.2_03

こちらは、個別のアプリでデータを取るイメージです。
特別にマスターのアプリは用意しなくとも、毎回このデータを取得し、後でそれをKeyにして名寄せが可能です。
API v1.0でも利用できます。

ただし、ユーザーのDBにこのトークン情報を保存するような運用の場合、万が一ビジネスマネージャーの関連付けを変更した場合はトークンが変わってしまうので注意が必要です。

まとめ

ザックリまとめると、複数のアプリのユーザーデータから、同一ユーザーを判別したい場合に、単純に後で名寄せを行うだけの用途であれば「token_for_business」で十分です。実装もおそらく楽。
いわゆる、プロモーション用途としてはこちらを使う形になるのでしょう。

そうではなく、同一ユーザーに対して複数アプリに一括ログインさせたり、複数アプリの情報を一覧表示させたり、といった横断的な機能実装などが必要な場合は、「Business Mapping API」を使ってすべてのアプリのIDを一気に取得してしまうことで可能になる、かもしれません。