# Facebook Ads

## 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hockeystack.com/integrations/ad-platforms/facebook-ads.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.