Facebook issues app-scoped user IDs for people who first log into an instance of an app, and page-scoped user IDs for people who first use a Messenger bot. By definition, this means the ID for the same person may be different between these apps and bots.
A business may operate several Facebook Apps or bots – common in games studios, for example, to support use cases such as cross-promotion or fraud detection, or in bots used to communicate with users. In these cases, you may need to map the same person’s ID between those apps and bots.
The Business Mapping API is only useful for businesses who operate multiple Facebook Apps, and who need to map the same user’s ID between them. If you have one primary app you are unlikely to need to use the Business Mapping API and thus do not need to set up a business or associate your apps with the business.
Business Manager is a way to help businesses and agencies manage their Facebook Pages, ad accounts, apps and payment methods in one place.
If you don’t need to use the Business Mapping API, we do not recommend setting up a business at this time. As a business needs to be linked with the primary Facebook Page for your business, the person who is best-placed to set up the business on Facebook is the person who usually manages facebook ad accounts and Page permissions for your company. If they have already setup your business within Business Manager, you are free to associate apps with that business.
There are three methods by which you can map the same user across multiple apps:
- The token_for_business field on the User node
- The token_for_business property in the signed_request object passed to apps rendered inside a Facebook Canvas frame
- The ids_for_business edge on the User node
Before you can use any of these mechanisms, you first must let Facebook know that your apps are owned and operated by the same business entity. To do this you will need to use Facebook Business Manager to:
- create a new business, or
- associate your apps to an existing business.
The token_for_business field on the User node
Once an app has been associated with a Business Manager, you may request the token_for_business field on the User node. This returns a string which is the same for this person across all the apps managed by the same Business Manager.
GET /me?fields=token_for_business
would yield:
{
“id”: “1234567890”
“token_for_business”: “weg23ro87gfewblwjef”
}
Usage notes:
- 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.
For convenience, the token_for_business field is available in all API versions
The token_for_business property in the Canvas signed_request object
To make it simple for apps with a Canvas presence to map a user across multiple apps, if the app is associated with a Business Manager, and the user had logged into the app, a token_for_business field will be added and passed to the app via the signed_request passed to Canvas apps upon load. For example:
{
“algorithm”: “HMAC-SHA256”,
“expires”: 1414263600,
“issued_at”: 1414257389,
“oauth_token”: “CAAGEkq9GMZAkBAFnvvQ3M6msZBKITLa1gVZBVdnLTdJue2QeV6fMKRXn4G6fcEZB5ZAJyg3z6HdaKOJCCMJ1l9YFWmN4hq6nNnx77f9O7SYhsnPcJ6iH79xjFwqhrALgieDp7GiziMy5Y3Mol6RzHvCM5ceqQe9ZAijvrWZB5hEIwphbMQKEwZA4ZBozXP3NJgEZA3nZCMTTtvleWpxfmqIqO5XwxneCZBsZC4”,
“token_for_business”: “AbwoGqummPbF3zp_”,
“user”: {“country”:”gb”,”locale”:”en_GB”,”age”:{“min”:21}},
“user_id”: “10154418713995634”
}
The value of the token_for_business field will be the same as if queried on the User node directly, e.g. via /me?fields=token_for_business. It also follows the same rules, i.e. if the owning business changes, the value of token_for_business will also change.
If the app is not associated with a Business Manager, or the user has not logged into the app, the token_for_business property will not be present in the signed_request object.
The ids_for_business edge on the User node
Get mapped business IDs by calling the ids_for_business edge on the User node. The response is an array of objects, each of which represents an app which is associated with the same business as the calling app, which the person has also logged into.
GET /me/ids_for_business
Example Response:
{
“data”: [
{
“id”: “10153949089790582”,
“app”: {
“name”: “Business’s App 1”,
“namespace”: “business_app_1”,
“id”: “647733625268125”
}
},
{
“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”
}
}
]
}
For data to be returned by the API, the user must have logged into one or more apps which are associated with the same business as the app from which you’re making the API call. Example: if a person has logged into 3 of 5 apps associated with the same business, the API will return 3 objects.
