Facebook Integration¶
The Facebook integration is set up with OAuth2 authentication. To set up this integration, a developer account is needed. An app should be configured in Facebook, correct permissions should be enabled for the app, and the app should also be verified. The process is described here in detail.
Changes in Links or Documentation contents.
API docs content and links are subject to constant change. So, this documentation should be read with a bit of caution. The process that was working at the time of writing this document is mentioned here and if anything has broken and require changes that are not present in this document, it is advised to check the official documentation.
Frontend Flow:¶
The Facebook integration works similar to Google integration. In the account configuration's manage Facebook modal, the button to create a new connection is clicked. The Facebook account that has ads running is logged in and finally redirected back to the manage Facebook modal.
Figure: Facebook Integration Frontend Flow
If the OAuth fails then the redirected page will take to the manage facebook section with popup dialogue displaying the failed message. If the connection is successful, the re-import account popup will appear where facebook ads account can be selected for which the data will be pulled.
The manage facebook modal loads data from api_facebook_connection and api_facebook_account. The connection can be edited where the account can be deleted or added from the accordion. There is also an option to re-authorize the connection which would re create the connection. The reimport section is shown in the figure below.
Figure: Facebook Integration Reimport Section
Toggle is disabled for already imported account in the re-import pop-up.
API Document Description¶
The API is accessed using Meta Business SDK. There are SDK available for different languages as mentioned here. The python SDK is used in the project. The documentation of facebook_business python package shows there are sets of CRUD operation related to ADs that can be performed, but in Cubed, the SDK is only used to read the analytics data and the permission is also set up accordingly in the developer portal.
The facebook app responsible for OAuth must undergo App Review to obtain all the required permissions as mentioned in the Permission Reference. This is most likely already done, and the permission that is of interest to us are ads_read, business_management, attribution_read. This can be submitted through a developer portal.
Setting up a client's ad account:¶
Main reference for this section is https://developers.facebook.com/docs/business-management-apis.
There are various combination of account that may be used to give Cubed access to facebook, which is described here: https://developers.facebook.com/docs/marketing-api/business-manager/best-practices. The users could be an advertisement agency, or customer themselves and they might have admin or non admin rights to the ads data. There is also a concept of owning and managing pages and business assets in facebook. The mentioned documentation link in the beginning of the paragraph can be helpful when dealing with client facing issue. Since, facebook also have hierarchical structure for accounts, the permission to access the right resource could be tricky. Easy way to check if proper right is given is by checking if Cubed can import the ad account. Getting the right account to log into cubed is crucial to start pulling the data. It might be helpful to go through this document about business manager to understand the hierarchy of users too: https://developers.facebook.com/docs/marketing-api/business-manager/get-started.
After logging into facebook, the user may reimport/delete the ad accounts from the accordion. The ad account is the one whose data will be pulled and if the account does not appear in the reimport section, then there is a very high chance that the user does not have ad accounts or the correct rights to grant us access to them. Again this document should be thoroughly referenced to check if their account is correctly setup: https://developers.facebook.com/docs/marketing-api/business-manager/best-practices as it describes number of scenarios.
Backend¶
The integration involves commands and views.
View¶
Views are typical for OAuth, there is a initialize view to start the login, there is a callback view that catches the redirection from facebook server and there is also a view to fetch new ad account used by re-import pop-up.
Command¶
The command uses python sdk to pull insights data for ad account. The reference to sdk is already mentioned above and the insights api can be referenced in the Marketing API.