Ads API Getting Started
From Facebook Developer Wiki
Note: You can read an in depth discussion about how logging in users works for a canvas page application.
Note: For more in depth documentation on building desktop applications, please read Authorization and Authentication for Desktop Applications.
Contents |
Creating a Facebook Platform Application
- Log in to the account you’ll use to develop the application. This must be a real Facebook account, not an advertising-only “gray account.”
- Go to http://www.facebook.com/developers/
- Click “Set Up New Application”
- Enter an application name, agree to the Terms of Service, then click “Save Changes.”
- Add any other users who need to access this application in the “Developers” list.
- Click “Save Changes” to finish configuring the application.
Please read Creating_a_Platform_Application for more information on the advanced settings.
Ads API Terms
In order to get started, you need to go to http://www.facebook.com/ads/manage/api_terms.php?app_id=YOURAPPLICATIONID, where YOURAPPLICATIONID is for the application which has already been granted Ads API access. Check the checkbox to agree with the terms provided. This only has to be done once per application, and must be done by an owner of the application.
Trying the Ads API out
Once Facebook has white listed your application you can test the API calls using the Developer Console
Be sure to select the correct application from the drop down.
User Authentication
In order for an application to manage ads on behalf of a user, Facebook requires the user to authorize the application and grant an additional permission to access their ads account, called the "ads_management" permission. Once the user has provided the necessary authorization, the application can request a session key to make ads API calls on behalf of the user. This document is meant to highlight some simple ways to get a session key and the extended permission from the user.
Simple Authentication for Facebook Platform Applications
If your Ads API implementation will live on Facebook Platform then you have a few options for authenticating users. Read about them on the Authorizing Applications tutorial.
Authentication for Facebook Connect Applications
If your Ads API implementation will not be a Facebook application on Facebook.com, you can use Facebook Connect to establish a user session and request extended permissions as well. The following wiki pages give overviews for setting up Facebook Connect:
- Facebook Connect
- Connect/Setting Up Your Site - a quick start guide
- Using Facebook Connect with Server-Side Libraries
User Authentication via URLs
You can prompt a user to authorize your application and grant access to that user's ads by sending her to login.php and passing "ads_management" in the "req_perms" field. This will prompt the user to authorize your application and to grant your application permission to manage the user's ads. This extended permission is required in order to make ads API calls for a particular user. The URL to prompt for this permission can follow the structure of the link below (with your API key filled in).
- http://www.facebook.com/login.php?api_key=YOURAPIKEY&connect_display=popup&v=1.0&next=http://www.facebook.com/connect/login_success.html&cancel_url=http://www.facebook.com/connect/login_failure.html&fbconnect=true&return_session=true&req_perms=ads_management
The next and cancel URLs are not required. However, without them the permissions window will close regardless of whether or not it was successful.
If you need to make calls on behalf of a user when the user isn't actively signed in to Facebook simply request the "offline_access" extended permission by passing "offline_access" as the value of the "req_perms" parameter in the URL above.
You can request multiple permissions at once using prompt_permissions.php. The correct use of this feature is documented here
How Signatures Are Generated
You can read about how these signatures are generated. This applies both to the signatures Facebook generates and the ones that your application needs to generate, only the parameters that get passed may be different.
About Session Keys
Applications don't receive infinite/non-expiring sessions when a user authorizes your application. Instead, Facebook sends your application a temporary session key that lasts an hour or until the user logs out of Facebook.
Each time a user who has authorized your application interacts with it, Facebook will renew the temporary session and send you the session key, even when this user visits a page in your application that doesn't require authorization. You don't need to make any calls to get this key.
While the user is on your canvas page, Facebook continues to renew the session key by pinging its servers.
If your application doesn't have an active session key and it needs one, you should direct the user to login.php (like you would with require_login); if the user has authorized the application previously, a session will be established automatically; otherwise, the user sees the authorization prompt.
Managing User Sessions
Like Facebook Platform apps, the Facebook Ads API methods currently require a user's session key in order to take actions on behalf of that user. As outlined in the “Making calls when a user is offline” section above, you can simply prompt a user to authorize your application and grant it an infinite session key in one simple step.
If this is a web app, the new session key will be in the parameters of the request. You can learn more about extracting that key from Authorizing_Applications#Parameters_Passed_to_Your_Application this wiki page.
If your application isn't a canvas page application, or if you are unable to read the POST parameters, you can use this API call to get the session key:
- auth.renewOfflineSession(int UID) returns session_key
At minimum, UIDs should be stored in a location where the application can access then in real time. We recommend storing UIDs, session keys, and Ads Account ID in a manner that makes it easy to programmatically access them and keep them together. This is important because any calls made with an account ID belonging to one user and the session key for another user will fail with a permissions error.
Managing Multiple Users
If you are building a tool to manage multiple advertiser accounts we recommend collecting the "offline_access" and "ads_management" extended permissions at one time from your user. Passing a next URL as well as "return_session" will direct the user to a page like this:
http://apps.facebook.com/YOURCANVASPAGE/test.php?session={%22session_key%22%3A%22REMOVED%22%2C%22uid%22%3AREMOVED%2C%22expires%22%3A0%2C%22secret%22%3A%22CREMOVED%22%2C%22sig%22%3A%REMOVED%22}
The values of the parameters have been removed but you can pull the UID and session key by accessing the page's GET parameters and store them in a database somewhere. This is the bare minimum you need to save so that you can make Facebook API calls at any time.
In PHP you could instantiate a Facebook object like this:
- $facebook = new Facebook($apikey, $apisecret);
- $facebook->set_user($uid, $session_key, 0);
- $apiclient = $facebook->api_client();
You're now ready to make API calls with the $apiclient object.
This is only for that one user ID, visit the authentication URL you generate for your application (instructions above) with each different account you would like to authorize and be sure to manage the credentials appropriately. Making API calls for user 2's ad account with user 1's session key will result in an error.
