Facebook Ads

With HockeyStack you can seamlessly authenticate, fetch, and analyze ad performance metrics from Facebook Ads, Campaigns, and Lead Forms

Getting Started

1. Sign In: A Facebook login window will appear, sign in and proceed to granting permissions

2. Grant Permissions: Review the requested permissions, such as access to your ad accounts and campaigns. Click Allow to grant the necessary permissions.

3. Confirmation: After granting permissions, you'll be redirected back to the ad reporting platform, confirming the successful connection

What Data Gets Tracked as Metadata

The following fields are tracked and stored during the integration process:

Field	Description
account_id_hashed	A hashed version of the account ID for secure storage.
type	The type of tracked data, such as paid-ads.
date	The date of the ad activity, formatted as YYYY-MM-DD.
id	A unique identifier for each data row, generated as an MD5 hash.
metadata	A JSON object containing detailed metadata about the campaign and ad.
account_id	The original account ID associated with the ad.
network	The advertising network, such as Facebook Ads.
campaign_id	The unique ID of the campaign.
adgroup_id	The unique ID of the ad group.
ad_id	The unique ID of the ad.
campaign_name	The name of the campaign.
adgroup_name	The name of the ad group.
ad_name	The name of the ad.
utm_source	The source of the traffic, such as facebook.
utm_campaign	The campaign name, URL-encoded if necessary.
utm_medium	The medium of the traffic, such as paid.
utm_content	Content-specific identifier for the campaign.
utm_term	The keyword associated with the campaign, if applicable.
impressions	The total number of impressions for the ad.
clicks	The total number of clicks for the ad.
cost	The total cost of the ad campaign in the specified currency.
currency	The currency in which the ad costs are measured (e.g., USD).

High-Level Integration Flow

1. Validate Integration:

   • Ensure the integration object contains required fields like facebookUserId and accessToken.

2. Fetch Ad Accounts:

   • Retrieve ad accounts linked to the user’s facebookUserId using facebookApiRequest.

   • Handle token expiration or invalid tokens by marking the integration as expired.

3. Retrieve Currencies:

   • Fetch account currencies using fetchAccountCurrencies.

   • Update stored currencies with the updateCurrencies function.

4. Process Ad Accounts:

   • Iterate through all ad accounts in the integration object.

   • Skip accounts marked as paused to optimize processing.

5. Fetch Insights and Ads:

   • Fetch ad insights (e.g., impressions, clicks, and spend) for a specific date range.

   • Retrieve associated ad data and format it for storage.

6. Process Lead Forms:

   • Identify and process any lead forms linked to ads using fetchLeads.

   • Create lead actions from submissions and store them.

Tracking Lead Forms

The integration tracks Facebook lead form submissions and creates a "Facebook Lead Form Submit" action that can be used as part of Goal building

Action Properties Tracked:

Field	Description
facebook_lead_id	Unique identifier for the Facebook lead.
facebook_form_id	Identifier for the lead form submitted.
facebook_campaign_name	Name of the campaign associated with the lead.
facebook_campaign_id	Unique ID of the campaign.
facebook_adgroup_name	Name of the ad group associated with the lead.
facebook_adgroup_id	Unique ID of the ad group.
facebook_ad_name	Name of the ad generating the lead.
facebook_ad_id	Unique ID of the ad.
facebook_creative_name	Name of the creative asset used in the ad.
facebook_creative_id	Unique ID of the creative asset.
utm_source	Traffic source, defaulting to facebook.
utm_medium	Traffic medium, defaulting to paid.
utm_campaign	Encoded campaign name for tracking.
submitted_at	Timestamp when the lead form was submitted.

Company Properties Tracked:

Field	Description
company_name	The name of the company, if provided.

Other Properties Tracked:

Field	Description
userId	Email address of the user, derived from the lead form.
identity	Same as userId, used for identifying the user.
session_start_date	Timestamp of when the lead form submission occurred.
actionDate	JavaScript Date object representation of the lead submission time.
actionType	Always set to custom for lead forms.
actionName	Always set to Facebook Lead Form Submit.
shared	Additional metadata including submission ID and associated properties.

Notes and Caveats

• Token Expiration:

  • Handle authentication errors (codes 190 and 102) by marking the integration as expired and prompting re-authentication.

• Rate Limits:

  • For rate limit errors (error code 17), retry up to 3 times with exponential backoff.

• Large Data Requests:

  • Split date ranges or reduce data volume for errors related to excessive data (error code 1).

• Default Processing Period:

  • The integration processes the last 28 days by default, with adjustments for specific accounts as needed.

• Batch Limits:

  • Data is processed in batches of 1000 records to optimize performance.

• Campaign Name Tracking:

  • Track and handle changes in campaign names to ensure data consistency.