Facebook「Business Mapping API」の使い方と「app-scoped ID」についてHow use Facebook”Business Mapping API”, what is “app-scoped ID”?

9.10
2014

mapping12
こんにちは。
Appleの発表がありましたね。まあ、あまり興味が無いので見てないんですけど。

さて、以前「Facebookビジネスマネージャー」というものの使い方を簡単にまとめました。
その際にも少し触れましたが「Business Mapping API」というものがあります。
今回はその辺のお話です。
mapping12

I have written the article ‘How to use “Facebook Business Manager”‘ some months ago.
I have mentioned about “Business Mapping API” in that article.
This time, describe about it.

API v2.0から、ユーザーIDの仕様が変わっている(app-scoped ID)

まずはじめに、API v2.0からアプリ経由で取得できるユーザーIDの仕様が変わっています。

Facebookプラットフォームアップグレードガイド(→日本語訳が出来てました。)
https://developers.facebook.com/docs/apps/upgrading#upgrading_v2_0_user_ids

docsが日本語訳されてました。「1. アプリ専用のユーザーID」というのが、「app-scoped ID」のことです。

mapping4

「app-scoped ID」とはなんなのか?

「app-scoped ID」の概念を簡単に説明すると、下記の図のようになります。

mapping2
なお、実際には「User ID」も「app-scoped ID」もどちらも単なる数字の羅列です。
↑の図のようにわかりやすい規則性はありません。

つまり、今まではどのアプリからもユーザー一意のIDが取得できていましたが、API v2.0以降はアプリごとに一意なIDとして、新たに「app-scoped ID」というものが導入されました。
ユーザー個人を特定できる情報は極力アプリには落とさない、ってことですかね。

「app-scoped ID」に切り替わったのはいつから?

mapping3
「app-scoped ID」は、API v2.0のタイミングで仕様が変わりました。v2.0以降を利用するアプリが対象になります。
すなわち、2014/4/30以降に作成したアプリもしくは、それ以前に作成したアプリでもAPI v2.0以降に移行を行ったものは対象になります。

2014/4/30以降に新たに作成したアプリについては、ユーザーのIDは全て「app-scoped ID」になっています。
API v2.0以降に移行を行ったアプリについては、移行以前にログインしたことがあるユーザーのIDは「User ID」ままとなり、移行後に初めてログインするユーザーのIDは「app-scoped ID」になります。
そのため、移行後にユーザーがログインすると既存のIDが書き換わる、というような事態は発生しません。

「app-scoped ID」に切り替わったことにより複数のアプリをまたいでユーザーの識別ができなくなった

このIDの仕様の変更ですが、通常の利用用途(アプリ単体としての動作完結)であれば何ら問題はありません。

ただし、ユーザーのIDを複数のアプリ間で連携しているようなケースでは、問題が発生します。
複数のアプリが全てAPI v1.0を利用している場合は良いのですが、一部もしくはすべてがv2.0以降を利用している場合、前述のようにユーザーのIDはアプリごとに変動してしまうので、連携が不可能になります。

mapping5

複数のアプリ間で同じユーザーを特定したり、1つのプログラムの中で機能や用途によってアプリを複数使っているようなケースでは今までこのUser IDをキーにユーザーのデータを相互参照していたと思いますが、それが出来なくなってしまうのです。

別のフィールドでユーザーの識別ができないか

では他に何かユーザー一意の情報はないでしょうか?
可能性としてあり得るのは、名前もしくはユーザーネーム(※)です。

※ユーザーネーム・・・http://www.facebook.com/[username] の形式でURLとして設定できる任意の名前です。他のユーザーと重複できません。

ただ、「名前」は他のユーザーと重複OKなので、一意の情報にはなりません。
ユーザーネームは一意ですが、なんとAPI v2.0からはこの情報を取得するAPIも廃止されています。

2014年4月30日 – APIバージョン2.0
https://developers.facebook.com/docs/apps/changelog#v2_0_graph_api

mapping6

つまり、どちらも使えないのです。あとはemailぐらいですかね、使えそうなの。

ここまでの流れを見れば、Facebookが「ユーザーを特定する」ようなアクションに対して規制を強めているのがわかると思います。
いずれそもそもポリシーで規制される可能性もあるかもしれませんね。

app-scoped ID を使って、ユーザーを一意に特定する方法(Business Mapping API)

さて、前段でapp-scoped IDというのが何なのかは説明しました。
ではこれを使ってアプリを横断してユーザーを特定する方法は完全に無いのでしょうか。

実は、これまたv2.0から新しく実装された「Business Mapping API」というものを利用することで、それが可能になります。
ただし、このAPIを使った場合でも、ユーザーのUser IDを取得することは不可能です。

はじめに、Facebookビジネスマネージャーを設定する

まずはじめに、ビジネスマネージャーの設定を行い、ビジネスアカウント(→このネーミングが正しいか微妙ですけど)の作成をする必要があります。

ビジネスマネージャーの設定については、以前まとめていますので今回は省きます。

mapping7

Facebookビジネスマネージャーの設定方法まとめ
https://snowadays.jp/2014/07/2889

なお、作成には「親」となるFacebookページが必要ですが、ここで設定したページはその後更新の際に若干不便になります。
(↑の記事を書いた当時と比べ、今ではほとんど通常と変わらなくはなりましたが。)
安易に企業の公式ページとかを設定するのは避けた方が良いと思います。(正しい使い方としては「公式ページ」を設定するんでしょうけど。)

「Business Mapping API」を使うために

まず、↑で設定したビジネスマネージャーの中で、連携させたいアプリを全て登録します。
仮にあなたが全てのFacebookアプリの管理人であれば、この作業は即時完了しますが、管理人が別にいる場合は承認待ちの状態になります。

mapping1
こうすることで、登録した複数のアプリはビジネスアカウントに紐づいてグルーピングされます。
この登録が完了したアプリのうち、API v2.0以降のものについては「Business Mapping API」が使えるようになります。

「Business Mapping API」の使い方

ビジネスアカウントに登録した複数のアプリですが、普通にユーザーのIDを「/me?fields=id」でたたいても、一意のIDではなくアプリごとに異なるIDが返ってきてしまいます。
ところが、「Business Mapping API」を使うことが出来るアプリについては「/me/ids_for_business」という形式で下記のようなデータが取得可能です。

{
  "data": [
    {
      "id": "10153949089790582",  /* App Scoped User IDです */
      "app": {
        "name": "Business's App 1",   /* アプリの表示名です */
        "namespace": "business_app_1",   /* アプリのネームスペースです */
        "id": "647733625268125"  /* アプリのIDです */
      }
    }, 
    {
      "id": "605665581", 
      "app": {
        "name": "Business's App 2", 
        "namespace": "business_app_2", 
        "id": "370612223054807"
      }
    }, 
    {
      "id": "10154053730190582", 
      "app": {
        "name": "Business's App 3", 
        "namespace": "business_app_3", 
        "id": "194890427204075"
      }
    }
  ]
}

上記の例では、「Business’s App 1~3」の3つのアプリは同じビジネスアカウントに登録してあることになります。

このデータを受け取ることで、デベロッパーでは「App1のID:10153949089790582さんと、App2のID:605665581さんと、App3のID:10154053730190582さんは同一人物」ということがわかります。

見ればわかる通り、User ID(v1.0までで取得できていた、真のUser ID)はどこにも入っていませんのでご注意を。

結構使いにくいですね・・・。
というのも、仮に個別にアプリを立てていくようなケースがあるとすれば、↑でいうところの「App 1~3」がどんどん増えていくことになります。
となると、例えばこれらのデータをDBにため込むとした場合に、カラムがどんどん増えていくようなイメージです。
特定の二つ、とか三つ、のアプリだけ記録すればいいなら問題ないんですけどね・・・。

実際にデモアプリで「Business Mapping API」を使ってみます

幸いなことに手元に複数のパターンのアプリがあります。
(アプリ名は気にしないでください)

  1. Tuesday ※API v1.0 →認証ページ
  2. Sunday ※API v2.0 →認証ページ
  3. Monday ※API v2.0 →認証ページ
  4. Wednesday ※API v2.1 →認証ページ

で、これらのアプリを、ビジネスマネージャーに設定してみました。
期待値としては、v1.0であるTuesday以外の3つのアプリについてはどれにログインしても他の2つのアプリにおけるそのユーザーのIDが取れるはずです。

★説明不要かと思いますが、当然デモを試すユーザーが3つのアプリ全てにログインしたことが無ければそうなりません。はじめてデモにアクセスする場合は、事前に3つのデモページでユーザーの認証通してからでないと、Business Mapping APIのテストはできません。

API v1.0のアプリを使って「/me?fields=id」を叩いてみる

デモページはこちら

mapping8

API v1.0で「/me?fields=id」を叩いていますので、このID(100*********125)が私の「User ID」です。(真のUser ID、real User ID)
なお、デモページではBusiness Mapping APIの情報も表示するようになってますが、v1.0では使えないのでError表記となります。

API v2.0のアプリを使って「/me?fields=id」と「/me/ids_for_business」(Business Mapping API)を叩いてみる

デモページはこちら

mapping9

さて、続いてはAPI v2.0で「/me?fields=id」と「/me/ids_for_business」を叩いてみました。
v2.0ということで、このUser ID(752*********630)は「App Scoped User ID」です。

また、その下にBusiness Mapping APIの結果も並べています。
各アプリそれぞれで、User IDが異なっているのがわかりますね。
さて、このうち一番下のSundayのアプリのUser IDは、先ほど確認した真のUser ID(100*********125)と同じです。
何故でしょうか?

過去にログインしたことがあるAPI v2.0のアプリを使って「/me?fields=id」と「/me/ids_for_business」(Business Mapping API)を叩いてみる

デモページはこちら

mapping10

このアプリはv2.0にもかかわらず、User IDが真のUser IDのままです。

実は、過去にログインしたことがある場合、そのユーザーのIDは「App Scoped User ID」にはならずに、以前の「User ID」のまま返されます。
これは、v2.0移行後にそのユーザーが再ログインしていようとしていまいと、関係ありません。
全てのアプリにおいて、2014/4/30よりも以前にログインしたユーザーのIDは、「User ID」のままです。
「App Scoped User ID = User ID」といった方が正しいですかね。

★なお、この結果は私がたまたまSundayのアプリに4/30以前にログインしていたから出ただけなので、初めてログインする人は単純に全アプリで「App Scoped User ID」(別々のID)が返ると思います。あしからず。

API v2.1のアプリを使って「/me?fields=id」と「/me/ids_for_business」(Business Mapping API)を叩いてみる

デモページはこちら

mapping11

おまけです。念のためv2.1でも試してみました。
まあ、v2.0と結果は変わりません。

ステージング用のアプリとかどうするの?

さて、余談ですが。
開発用のアプリはともかく、本番アプリとは別にステージングのアプリを運用しているようなケースでは、本番とステージングのアプリでユーザーのIDが変わってしまう(アプリが違うから)と困りますよね。

そんな時、「Test Apps」を使えば同じID(同じApp Scoped User ID)が使えるようです。
この辺の話は、また改めてまとめます。

User ID have changed to “app-scoped ID” in api v2.0.

First of all, the specification about user ID have changed in api v2.0.

Facebook Platform Upgrade Guide
https://developers.facebook.com/docs/apps/upgrading#upgrading_v2_0_user_ids

See “1. App-scoped User IDs” above.

mapping4

What is “app-scoped ID”?

See below image, it explaining about “app-scoped ID”.

mapping2
Actualy, both of “User ID” and “app-scoped ID” are just numbers.
There are no regularity.

So far we were able to get an same “User ID” from every app.
Now, we can get the “app-scoped-ID” that is different ID for each app later than api v2.0 was released.

Facebook may not want to give the information that can identify the user personal.

When was it changed to “app-scoped ID”?

mapping3
The “app-scoped ID” have released with api v2.0.
It’s scope is the app either created after April 30 2014 or created before that and have been migrated to v2.0.

All user ID have been “app-scoped ID” in your app created after April 30 2014.
In the app created before April 30 2014 and have been migrated to v2.0, the ID of a user log in first time after migration is “app-scoped ID”.
The ID of a user had logged in before migration is still “User ID”.
It means the ID of existing user isn’t change by “app-scoped ID”.

We can no longer identify users across the multiple apps because of “app-scoped ID” change.

This specification change doesn’t affect the app running alone.
But it have a problem in the case of using the user ID across the multiple apps.
We can no longer use the user ID across the multiple apps because of user id is different for each app later than api v2.0.

mapping5

We had referred to the data by using “User ID” as key if identify the same user across the multiple apps or use multiple apps in one promotion.
But we can’t any more.

Can we identify the user by other information?

Is there nothing to be replaced “User ID”?
It may be used the “name” or “username”.
Username is the string of the url, like “http://www.facebook.com/[username]”.

Unfortunately, “name” isn’t unique of all Facebook users.
Many users have same “name”.
On the other hand, “username” is unique.
But it had been expired that the api for getting the “username” information in api v2.0.

April 30th, 2014 – API Version v2.0
https://developers.facebook.com/docs/apps/changelog#v2_0_graph_api

mapping6

So, we can’t use both.
The only thing we can use is “email”.

I think, Facebook really not want to give the information that can identify the user personal.
Someday it may be going to be prohibited by the policy.

We can still identify the user by “Business Mapping API”!

Don’t be sad, we can still identify the user across the multiple apps by using “Business Mapping API”.
It has been available in api v2.0.
Of course it can get only “app-scoped ID”, not “user ID”

You need to set the “Business Manager”

You need to set the “Business Manager”, and making the business account.

mapping7

Please see below ,how to use “Facebook Business Manager” is.

How to use “Facebook Business Manager”
https://snowadays.jp/2014/07/2889

Please note that when you make the account of “Business Manager” you need a facebook page.
And the admin UI of the page that was set in “Business Manager” is changed.

Prepare for using “Business Mapping API”

All of the apps that are used across need to be registered in “Business Manager”.
If you have the admin role of each app, registration will finish immediately.
It will be waiting for approval if you have not the admin role.

mapping1

Every app registered in “Business Manager” is grouped by “Business Account”.
The app registered can use “Business Mapping API”, if it is later than api v2.0.

How to use “Business Mapping API”

You can get the data by calling api “/me/ids_for_business”.
If you call this, you will get like below.

{
  "data": [
    {
      "id": "10153949089790582",  /* App Scoped User ID */
      "app": {
        "name": "Business's App 1",   /* App name */
        "namespace": "business_app_1",   /* App namespase */
        "id": "647733625268125"  /* App ID */
      }
    }, 
    {
      "id": "605665581", 
      "app": {
        "name": "Business's App 2", 
        "namespace": "business_app_2", 
        "id": "370612223054807"
      }
    }, 
    {
      "id": "10154053730190582", 
      "app": {
        "name": "Business's App 3", 
        "namespace": "business_app_3", 
        "id": "194890427204075"
      }
    }
  ]
}

In this case, the app “Business’s App 1”, “Business’s App 2”, “Business’s App 3” are registered in same “Business Manager”.

Now you can find that user id:10153949089790582 in the “App 1” and user id:605665581 in the “App 2” and user id:10154053730190582 in the “App 1” are same user.
Note that these user id are “app-scoped ID”, not “User ID”.

Umm…it’s inconvenience.

If you create the app each time, app will continue more and more. (App 1,2,3,4,5…100!)
So, if you store these ids in database you need create column as many as the number of apps.
If the number of apps is constant, there is no problem.

“Business Mapping API” demonstration

There are some apps demo below.

  1. Tuesday ※API v1.0 →Demo
  2. Sunday ※API v2.0 →Demo
  3. Monday ※API v2.0 →Demo
  4. Wednesday ※API v2.1 →Demo

These apps are registered in same “Business Manager”.
If it works, you can get the user id of every app when you log in each app except api v1.0 “Tuesday” app.

★Note that the user using the demo needs to have logged in all apps.
You can’t test “Business Mapping API” before you have logged in all apps.

Example of calling “/me?fields=id” by api v1.0 app.

Demo is here

mapping8

Since it is api v1.0, this id “100*********125” is my “User ID”(real user ID) .
In api v1.0, “Business Mapping API” returns error.

Example of calling “/me?fields=id” and “/me/ids_for_business” by api v2.0 app.

Demo is here

mapping9

Next, calling “/me?fields=id” and “/me/ids_for_business” by api v2.0 app.
Since it is api v2.0, this id “752*********630” is “App Scoped User ID”.

In api v2.0, “Business Mapping API” returns some data.
You can see there is different ID for each app.
By the way, the ID of the “Sunday” app is same as ID of the v1.0 app above.
Why is it?

Example of calling “/me?fields=id” and “/me/ids_for_business” by api v2.0 app that had been logged in before.

Demo is here

mapping10

In this app, this is is real user id.

If the app had been logged in before April 30 2014, user id is still “User ID” not “app-scoped ID”.
If the user logged in the app again after April 30 2014, it doesn’t change.

I had logged in the “Sunday” app before April 30 2014.
That’s why the id of the “Sunday” app same as the “Tuesday” app(api v1.0).

Example of api v2.1

Demo is here

mapping11

Of course, it’s same as v2.0.

How about if the app is staging?

If you have the staging app in addition to production app, the user id is different for each.
It is problem.

For this case, you can use “Test Apps” and get the id from staging app same as production app.

I will write about this soon.