Facebook / Meta Ads

Facebook / Meta Ads is a digital advertising platform offered by Meta, allowing businesses to create and display ads on the Facebook, Instagram, Messenger, WhatsApp, and other Meta platforms. Advertisers can target specific demographics, interests, behaviors, and locations, and choose various ad formats like images, videos, and carousels to reach their desired audience. The platform provides detailed performance metrics, enabling advertisers to measure the effectiveness of their campaigns and make data-driven optimizations.

Features

Feature nameSupported
Column HashingTrueField level
BlockingTrueField level
IncrementalTrue
Custom dataTrue
HistoryFalse
ReSyncTrueTable level
TemplatesTrue

Data Schema

Open full-page schema explorer

Meta applies global rate limits across your account

  • This means that Meta imposes certain restrictions on how often you can make requests or perform certain actions on their platform for a specific account. This is usually done to prevent misuse or overuse of their services.
  • If you're using Meta APIs for multiple purposes, you might encounter problems when trying to sync data with Weld as the global rate limits might have been reached.
  • When you reach 40% of your rate limit Weld will slow down all Meta syncs to avoid maxing out rate limits.

Meta APIs Scopes

The Weld App asks for the following scopes when setting up the integration:

  • ads_read
  • ads_management
  • business_management

Setup Guide - ELT

Prerequisites

  • An active Meta account with permission to access data from accounts you would like to sync.
  • The breakdowns and fields you would like to sync.

Step 1 - Create the connection

  1. In Weld, click Data Sources in the sidebar, then Add Data Source, and choose Facebook Ads. If the account is already connected, choose Use existing connection and go to Step 2.
  2. Check the connection Name (1). It's filled in for you, and you can change it.
  3. Under Select Authentication Method (3), choose how Weld signs in to Meta:
    • OAuth (Most users): click Authorize (4), sign in to Meta and approve Weld's access. You're taken back to the setup.
    • System User (Agency): paste the System User Access Token of a system user in Meta Business Manager, and click Connect. This is mainly for agencies. See Get a system user access token below.

If someone else owns the Meta account, for example a client, click Share Authorization Link (2) instead and send them the link. They sign in and grant access without a Weld login. See Authorization links.

Get a system user access token

In Meta Business Manager, open Business Settings:

  1. Under Users → System users, add a system user, or choose an existing one.
  2. Click Assign assets and give the system user access to the ad accounts Weld should sync.
  3. Click Generate new token, choose your app, and select the ads_read, ads_management and business_management permissions, the same ones Weld asks for when you sign in with OAuth. Copy the token.

The token must give access to at least one ad account, or Weld rejects it. See Meta's system users guide for more.

Step 2 - Connection Settings

  1. Ad Accounts (1): the Meta ad accounts to sync.
  2. Click Window and View Window (2): the attribution windows for conversions in the standard reports, such as 7d_click and 1d_view. Custom reports don't use them.
  3. Add custom report (3): add a report with the fields and breakdowns you choose. See Custom Report Builder below.
  4. Limit historical data: sync only data after a date you choose. Leave it empty to sync all the history the API offers.

Click Next.

Data Retention Limit

The Facebook Ads API has a 3-year data retention limit. Historical data is only available up to 3 years prior to the table’s initial sync date. Any data older than 3 years cannot be retrieved.

Step 3 - Data to sync

Tick the tables you want. Object tables, such as account, sync in full. Report tables, such as action_conversion_device, sync incrementally. Expand a table to remove or hash columns.

Step 4 - Configure sync

Choose how often to sync, check the Destination schema name, which is where the tables land in your warehouse, and click Start Initial Sync.

Query your data

When the first sync finishes, the tables are in your warehouse under the destination schema. In Transform, find them under Data Sources in the sidebar, then write a model on top of them or ask Ed to write one. See Data models.

Tables

Weld supports data replication of both object and report Meta Ads data.

  • Objects

    • Description: Objects represent the structural and operational setup of an advertising entity. This includes configurations, targeting settings, and relationships with other entities in the advertising ecosystem.
    • Example: ad_group

  • Reports

    • Description: Reports focus on the performance metrics and results of the entity. They provide detailed data about how well the entity is performing on a daily basis.
    • Example: ad_group_report

Objects Overview

  • Core Entities: Essential to Meta Ads, representing foundational data. Provides information on what the entity is and how it is set up:
    • Advertisers
    • Campaign
    • Ad Group
    • Ad

Reports Overview

  • Performance Metrics: Includes detailed metrics and statistics for reporting on Ads, Ad Groups, and Campaigns. Indicate how well the entity is performing, based on various performance metrics.
  • Granularity: Data availability is detailed, offered on a daily and hourly basis.
  • Additional Reporting Dimensions: Reports can also be created based on Country, Language, Age, Gender, and Platform.

Custom Report Builder

Our custom report builder allows you to create personalized Meta Ads reports tailored to your specific requirements. By defining dimensions, breakdowns, fields, and other criteria, you can extract actionable insights from your advertising data. Here's how to use it:

Fields

  1. Name:

    • Description: Specifies the name of the report.
    • Input Type: Text
    • Requirement: Mandatory
    • Example: "Ad conversions"

  2. Required dimensions:

    • Description: Define the necessary dimensions that should be part of the report. These dimensions represent the primary categorization of data.
    • Input Type: Dropdown
    • Requirement: Mandatory
    • Default: Date

  3. Action breakdown (0/10):

    • Description: Break down actions (like conversions) by specific types or sources. For example, breaking down link clicks by device type.
    • Input Type: Multi-select (up to 10 selections allowed)
    • Requirement: Optional
    • Example: action_type, action_device

  4. Breakdowns (0/24):

    • Description: Additional ways to segment the data in your report. This provides a more granular view.
    • Input Type: Multi-select (up to 24 selections allowed)
    • Requirement: Optional
    • Example: Age, Gender, Location
    • Hourly Reports: To generate hourly reports, select either hourly_stats_aggregated_by_advertiser_time_zone or hourly_stats_aggregated_by_audience_time_zone. More info about them here: Meta Ads Hourly Stats

  5. Fields (0/76):

    • Description: Choose the specific metrics and attributes you want to include in the report.
    • Input Type: Multi-select (up to 76 selections allowed)
    • Requirement: Optional but recommended
    • Example: Impressions, Clicks, Spend, CTR

  6. Level:

    • Description: Define the granularity of the data. Meta's ad structure consists of Campaigns -> Ad Sets -> Ads. Decide at which hierarchy level you want to pull the data.
    • Input Type: Dropdown
    • Options: Campaign, Ad Set, Ad
    • Requirement: Mandatory

  7. Action Report Time:

    Description: This field determines the time window in which actions, either "Impressions" or "Conversions," are attributed to your ad after being viewed or clicked. It's crucial for understanding the effectiveness and latency of your ads.

    Options:

    1. Impressions:

      • Description: Choosing this option means that your report will attribute actions based on when a user viewed your ad.
      • Use Case: This is beneficial for campaigns that aim to raise awareness. Even if a user doesn’t immediately interact with the ad, seeing the ad might influence their behavior later.

    2. Conversions:

      • Description: Selecting this option attributes actions based on when a user clicked on your ad and then took a desired action, like making a purchase.
      • Use Case: This is especially pertinent for direct response campaigns where the aim is to drive immediate action, such as sign-ups, purchases, or downloads.

    Choosing the Right Option: The best choice between "Impressions" and "Conversions" largely depends on your custom report objectives. By Default this value is set to "Impressions", however if you are looking for specific conversion values such as action values, converted product value or purchase ROAS then "Conversions" would be advised.

Troubleshooting:

  1. Report Validation Failed: Ensure all mandatory fields have been filled.
  2. No Data in Report: Some combinations of breakdowns and fields might result in empty datasets. Try broadening your selections or changing the report "Level".
  3. Remember that certain combinations of breakdowns and fields may yield no data or may not be supported. Experiment with different configurations to find the most valuable insights.

Setup Guide - Reverse ETL

Meta reverse ETL allows you to sync data on a schedule from your Weld App automatically into a custom audience user list in Meta.

Prerequisites

  • An active Meta account with permission to access data from accounts you would like to sync.
  • The breakdowns and fields you would like to sync.

Step 1 - Destination

  1. In the Reverse ETL section, , select + Add Reverse ETL Sync
  2. Select Facebook Ads on the list of connectors
  3. Give the connector a name
  4. Select the Authentication Method as:
  • OAuth: This is the recommended method for most users, as it allows Weld to access your Meta account securely.
  • ** System User**: Suitable for agencies or users managing multiple accounts, this method requires a system user token.
  1. Click Authorize if you selected OAuth, or enter your system user token if you selected the System User method and click Connect.
  2. When authorization is complete, you will be redirected back to the Weld connections overview. The configuration is complete.

Step 2 - Target Details

You will need to select where you would like to send your data. Select:

  • Ad Account: The Meta Ads account where you want to send the data.
  • Custom Audience: The specific custom audience within the ad account that you want to update with the synced data.

Step 3 - Map Data

  1. Select the source data model that you would like to sync to Facebook Ads. This can be a table or a view from your data warehouse.
  2. Select the destination object you would like to sync to. In Facebook Ads, this is typically user.
  3. You will be presented with several options to configure your sync, which we will go through in the next steps.

Sync Mode

Choose how you want to sync data from your source model to the destination object. Depending on the destination object, you might have only one or multiple of the following options available:

  • Upsert: Updates existing records and inserts new ones.

Field Mapping

Map the fields from your source model to the fields in Facebook Ads. You can map the fields manually or use the auto-mapping feature to match fields based on their names. Ensure that the fields you map correspond to the properties in Facebook Ads.

Step 4 - Schedule

After you finished the steps above, click on Next to proceed to the scheduling step. Here you can choose how often you would like the sync to run:

  • Independent: The sync will run on its own schedule, independent of other syncs.
  • Orchestration: The sync will be part of an orchestration workflow, allowing you to run it in conjunction with other tasks.

Step 5 - Finalise and Run

After you have configured the sync, click on Start Sync to finalize the setup. The sync will perform the initial run immediately.

SQL Templates

View all →

Was this page helpful?