Connecting to Facebook Ads

The Sisense Facebook Ads connector is a standalone connector that allows you to import data quickly from your Facebook Ads account into the ElastiCube Manager without custom SQL. This connector includes several features to enable you to quickly and easily import data from Facebook Ads:

After you have downloaded and installed the connector, you can connect to Facebook Ads through a connection string you provide Sisense in the ElastiCube Manager. The connection string is used to authenticate users who connect to Facebook’s APIs.

This page describes how to install the Facebook Ads connector, how to connect to Facebook Ads with a connection string, and what tables you can import into the ElastiCube Manager.

Breaking Changes for the Marketing API Version 2.8

As of July 25, 2017, Facebook no longer supports their Marketing API version 2.8. Currently, all users whose Facebook app is v2.8 will receive an error. To overcome this issue, add the parameter ‘Version=2.10’ to the connection string.

For more information about the latest version of the Marketing API, see Facebook’s blog posts.

Prerequisites

Installing the Facebook Ads Connector

Sisense provides the Facebook Ads connector as a standalone connector that you can download and add to your list of default Sisense connectors. After you install the Facebook Ads connector, it is added to your list of Web Service connectors.

To install the Facebook Ads connector:

  1. Download the Facebook Ads installation file.
  2. Open the installation file and click Install.
  3. After the installation process is complete, click Close.

The Facebook Ads connector is displayed in the ElastiCube Manager under Add Data > Web Services.

Connecting to the Facebook Ads

To access Facebook Ads’ data from Sisense, you must provide valid Facebook Ads credentials in a connection string.

This section describes how to create a Facebook app to retrieve the necessary authentication parameters for the connections string and then how to construct the connection string.

Note: If you have already created a connection string for the Facebook connector, you can use the same credentials in the Facebook Ads connection string.

Creating an App

The credentials you need to connect to your data in Facebook are provided by Facebook when you create a Facebook app through the Facebook Developer site.

For more information, see Creating an App in Facebook.

Creating a Connection String

Sisense uses connection strings to connect to Facebook Ads and import data into the ElastiCube Manager. Each connection string contains authentication parameters that the data source uses to verify your identity and what information you can export to Sisense.

Note: When switching accounts, you must sign out of your account and then sign it with the new account.

After you have obtained the relevant credentials, you can create the connection used to connect to your Facebook account. The Facebook connection string has the following structure:

jdbc:DataSourceName:Property1=Value1;Property2=Value2;

The following is an example of Facebook connection string:

jdbc:facebook:OAuthClientId=112345383774486;OAuthClientSecret=064c524478d712534b7e7e4224fad;

InitiateOAuth=GETANDREFRESH;Version=2.8;CallbackURL=http://localhost/;Timeout=0;ThrottleSeconds=15;

ThrottleMaxPercent=90;Other=RetryWaitTime=60000;MaximumRequestRetries=5;

The example above includes both mandatory and optional parameters you can provide in the connection. The required parameters are emphasized in bold.

If you have any issues connecting to your data source, see Troubleshooting JDBC Data Connectors.

Mandatory Parameters

Adding Facebook Ads Tables to your ElastiCube

After you have changed the connectivity settings of the predefined ElastiCube, or if you want to create your own ElastiCube from scratch, you can add Facebook Ads tables exposed by the Facebook API.

Facebook provides access to data associated with the Facebook account you defined in the connection string. Once you have connected, Sisense displays a list of Facebook Ads tables you can import. For a list of supported tables, see Facebook Ads Tables.

To add Facebook Ads data:

  1. In ElastiCube Manager, click Add Data and then, Facebook Ads. The Connect to Facebook window is displayed.
  2. In the Date Range fields, select the date range for the relevant Facebook Ads data you want to import.
    Note: When performing an accumulative build, if you change the date range from your previous build, select Delete existing Data to prevent duplication.
  3. In Datasource Connection String, enter your connection string.
  4. Click Connect to Server. Facebook is displayed in the Select Database list.
  5. Click OK. Sisense connects to Facebook and displays a list of tables available for you to import. For a list of tables you can import, see Facebook Ads Tables.
  6. Select the relevant tables and click Add. The tables are displayed in the ElastiCube Manager.

Tip: Facebook Ads leverages the Facebook Marketing API, however, this API includes user request limitations. To overcome this limitation, try to reduce the date range or query fewer Ad accounts by removing them from your developers profile (Settings > Advanced > Advanced Ad Account IDs). For more information, see Facebook’s Marketing Rate limitations.

Facebook Ads Tables

The table below describes the tables you can import from various Facebook APIs. Facebook limits the number of calls and the amount of data that you can retrieve from their APIs. These limitations depend on which Facebook API you are using and your account type. When you reach a limit, Sisense returns the error provided by Facebook. For example, if you receive any of the following error codes, this usually indicates that you have reached one of Facebook’s limitations:

If you encounter one of these errors, refer to the Facebook API that exposed the table for more details regarding that API’s limitations.

Available Tables

Table Description
AdAccounts The Ad Accounts available for a user. AdAccounts in Facebook are the accounts you have available in Facebook for creating Ads on. Accessing Ad Account information requires the ads_read permission.
AdCreatives Information about an Ad Creative or the Ad Creatives on a specific Ad Account, Ad Set, or Ad. AdCreatives in Facebook represent a collection of the creatives for specific Ads in Facebook. Accessing Ad Creative information requires the ads_read permission.
AdInsights Ads Insights provides access for reporting and analytics purposes. Accessing AdInsights information requires the ads_read permission.
AdInsights_Age_Gender The following are breakdowns of the AdInsights table. Due to storage constraints, Facebook has made only some permutations of breakdowns available. For more information, see Facebook Breakdowns.
AdInsights_Country
AdInsights_FrequencyValue
AdInsights_Placement_Device
AdInsights_HStatsByAdvertiserTZ
AdInsights_HStatsByAudienceTZ
AdInsights_Placement_Device
AdInsights_Placement_ImpressionDevice
AdInsights_ProductId
AdInsights_PublisherPlatform_ImpressionDevice_PlatformPosition
AdInsights_Region
AdInsightsActions Query an Ad Report. Accessing Ad Report information requires the ads_read permission. AdInsightsActions represents a breakdown of the Actions column from AdInsights.
AdInsightsActions_Age_Gender The following are breakdowns of the AdInsightsActions table. Due to storage constraints, Facebook has made only some permutations of breakdowns available. For more information, see Facebook Breakdowns.
AdInsightsActions_Country
AdInsightsActions_FrequencyValue
AdInsightsActions_HStatsByAdvertiserTZ
AdInsightsActions_HStatsByAudienceTZ
AdInsightsActions_Placement_Device
AdInsightsActions_Placement_ImpressionDevice
AdInsightsActions_ProductId
AdInsightsActions_PublisherPlatform_ImpressionDevice_PlatformPosition
AdInsightsActions_Region
Ads Query information about an Ad or the Ads in a specific Ad Set, Campaign, or Ad Account. Accessing Ad Information requires the ads_read permission. Ads in Facebook represent individual ads that have been created.
AdScheduledReports Query the Scheduled Reports for a given Ad Account. Accessing Scheduled Report information requires the ads_read permission. The scheduled reports are a list of reports scheduled to run every day for your account. These can be maintained in the Facebook Ads Manager. Daily runs of these reports are available from ScheduledReportRuns.
AdSets Query information about an Ad Set or the Ad Sets on a specific Campaign or Ad Account. Accessing Ad Set information requires the ads_read permission. AdSets in Facebook represent a collection of Ads in Facebook.
Campaigns Query information about a Campaign or the Campaigns on a specific Ad Account. Accessing Campaign information requires the ads_read permission. Campaigns in Facebook represent advertising campaigns that individual Ads or AdSets may be a part of.

Versions

Version Release Date Improvements
6.6.1.50 June 12, 2017 New version of Graph API v2.9 ChangelogNew objects: SimpleVideoInsights, VideoInsightsByActionType, VideoInsightsByDistributionType, VideoInsightsByReactionType
6.6.1.45 May 17. 2017 General Release

Version 6.6.1.45

Breaking Changes

In the latest version of the Facebook Graph API, permissions have been largely reworked. All of the friends* permissions have been removed. In addition, most permissions require Facebook approval if you wish to request information about other user accounts who are not an administrator of the Facebook App. Sisense recommends reviewing the new permissions listed by Facebook here:

https://developers.facebook.com/docs/facebook-login/permissions/v2.1

In addition, users may reject requested permissions in the Authorization dialog on Facebook. If this happens, the specific Permissions requested will state that they are declined under the Status column. The permission may be rerequested by executing GetOAuthAccessToken and setting AuthType to rerequest.

If you want to keep using an old version of the API, you can by simply setting the Version connection property in the connection string to the specific version you were using and also setting the Location to a folder where you have saved an older copy of the schema files (.rsd and .rsb files).

If you want to update your app to 2.9, then you don’t have to do anything

Note: Sisense removed few metrics from the AdInsights / AdInsightsActions due to their removal by Facebook in 2.9.

A number of various changes have been made across tables due to changes in Facebook. These changes are listed below: