meta-ads-integration

Set up and optimize Meta (Facebook/Instagram) ad campaigns with Conversions API server-side tracking, dynamic product ads, and catalog sync for ecommerce

11 stars

byfinsilabs

View on GitHub Installation ↓

Best use case

meta-ads-integration is best used when you need a repeatable AI agent workflow instead of a one-off prompt.

Set up and optimize Meta (Facebook/Instagram) ad campaigns with Conversions API server-side tracking, dynamic product ads, and catalog sync for ecommerce

Teams using meta-ads-integration should expect a more consistent output, faster repeated execution, less prompt rewriting.

When to use this skill

You want a reusable workflow that can be run more than once with consistent structure.

When not to use this skill

You only need a quick one-off answer and do not need a reusable workflow.
You cannot install or maintain the underlying files, dependencies, or repository context.

Installation

Claude Code / Cursor / Codex

$curl -o ~/.claude/skills/meta-ads-integration/SKILL.md --create-dirs "https://raw.githubusercontent.com/finsilabs/awesome-ecommerce-skills/main/skills/marketing-growth/meta-ads-integration/SKILL.md"

Manual Installation

Download SKILL.md from GitHub
Place it in .claude/skills/meta-ads-integration/SKILL.md inside your project
Restart your AI agent — it will auto-discover the skill

How meta-ads-integration Compares

Feature / Agent	meta-ads-integration	Standard Approach
Platform Support	Not specified	Limited / Varies
Context Awareness	High	Baseline
Installation Complexity	Unknown	N/A

Frequently Asked Questions

What does this skill do?

Set up and optimize Meta (Facebook/Instagram) ad campaigns with Conversions API server-side tracking, dynamic product ads, and catalog sync for ecommerce

Where can I find the source code?

You can find the source code on GitHub using the link provided at the top of the page.

SKILL.md Source

# Meta Ads Integration

## Overview

Meta (Facebook/Instagram) is the dominant paid social channel for ecommerce, but reliable attribution requires pairing the browser-based Meta Pixel with server-side Conversions API (CAPI). Post-iOS 14, browser signals alone under-report 30–60% of conversions; CAPI restores signal fidelity by sending purchase events directly from your server. For Shopify, WooCommerce, and BigCommerce, official integrations handle both Pixel and CAPI automatically — no custom code required. Custom code only belongs in the Custom/Headless section.

## When to Use This Skill

- When setting up Meta advertising for a new ecommerce store
- When conversion data in Ads Manager looks under-reported after iOS 14 rollout
- When launching Dynamic Product Ads (DPA) and needing catalog feed sync
- When ROAS is declining and you need to restore the signal quality Meta's algorithm relies on
- When adding retargeting audiences based on product viewers and add-to-cart events

## Core Instructions

### Step 1: Choose your integration approach

| Platform | Recommended Method | CAPI Support | Catalog Sync |
|----------|--------------------|-------------|-------------|
| **Shopify** | Native Meta Sales Channel | Yes (built-in) | Yes (automatic) |
| **WooCommerce** | Facebook for WooCommerce plugin | Yes (built-in) | Yes (automatic) |
| **BigCommerce** | Meta channel in Channel Manager | Yes (built-in) | Yes (automatic) |
| **Custom / Headless** | Meta Pixel + facebook-nodejs-business-sdk | Manual CAPI implementation | Manual feed generation |

All three major platforms have official Meta integrations that install both the Pixel and CAPI in a single setup — use these rather than manually pasting Pixel code.

### Step 2: Connect your platform to Meta

---

#### Shopify

1. Go to **Shopify Admin → Sales Channels → + → Facebook & Instagram**
2. Install the Facebook & Instagram sales channel
3. Connect your Meta Business Manager account and select your Facebook Page and Ad Account
4. Under **Data Sharing**, select **Maximum** — this enables server-side CAPI in addition to the browser Pixel
5. Shopify automatically:
   - Installs the Meta Pixel on all pages
   - Fires ViewContent, AddToCart, InitiateCheckout, and Purchase events
   - Sends the same events via CAPI from Shopify's servers (deduplication handled automatically)
   - Syncs your product catalog to Meta Commerce Manager for Dynamic Product Ads
6. Go to **Facebook & Instagram → Overview** to verify pixel connection status
7. In **Meta Events Manager → Data Sources → [Your Pixel]**: check Event Match Quality (EMQ) score — aim for 7+/10

---

#### WooCommerce

1. Install **Facebook for WooCommerce** (free, official Meta plugin) from the WordPress plugin directory
2. Go to **WooCommerce → Facebook → Get Started** and connect your Meta Business Manager account
3. Under **Facebook Connection → Data Sharing Level**: select **Maximum**
4. The plugin installs the Meta Pixel across all pages and fires standard events automatically
5. CAPI is enabled automatically under the Maximum data sharing setting
6. Go to **WooCommerce → Facebook → Product Sync** to trigger an initial product catalog sync to Meta Commerce Manager
7. Verify catalog sync status in **Meta Commerce Manager → Catalog → Data Sources**

---

#### BigCommerce

1. Go to **BigCommerce Admin → Channel Manager → Add a Channel**
2. Select **Facebook & Instagram**
3. Connect your Meta Business Manager account
4. Enable **Enhanced Conversions** (CAPI) during setup
5. BigCommerce syncs your product catalog automatically and registers it in Meta Commerce Manager for Dynamic Product Ads
6. Check product sync status in **Channel Manager → Facebook & Instagram → Products**

---

#### Custom / Headless

For headless stores, you must install both the browser Pixel and server-side CAPI manually.

**Browser-side Pixel (add to `<head>` on every page):**
```javascript
// Replace YOUR_PIXEL_ID with your Pixel ID from Meta Events Manager
fbq('init', 'YOUR_PIXEL_ID');
fbq('track', 'PageView');

// Product page
fbq('track', 'ViewContent', {
  content_ids: [product.sku],
  content_type: 'product',
  value: product.price,
  currency: 'USD',
});

// Purchase — pass eventID for deduplication with CAPI
const purchaseEventId = `purchase-${orderId}`;
fbq('track', 'Purchase', {
  content_ids: order.lineItems.map(i => i.sku),
  value: order.subtotal,
  currency: order.currencyCode,
  order_id: order.id,
}, { eventID: purchaseEventId });
```

**Server-side CAPI (send from your order webhook):**
```typescript
import { FacebookAdsApi, ServerEvent, UserData, CustomData, EventRequest } from 'facebook-nodejs-business-sdk';

FacebookAdsApi.init(process.env.META_CAPI_ACCESS_TOKEN!);

async function trackPurchaseCapi(order: Order, req: Request) {
  const eventId = `purchase-${order.id}`; // MUST match the eventID passed to fbq()

  const userData = new UserData()
    .setEmail(order.customerEmail)    // SDK hashes PII automatically (SHA-256)
    .setPhone(order.customerPhone)
    .setFirstName(order.customerFirstName)
    .setLastName(order.customerLastName)
    .setZip(order.shippingAddress?.zip)
    .setCountry(order.shippingAddress?.countryCode)
    .setClientIpAddress(req.ip)
    .setClientUserAgent(req.headers['user-agent'] as string)
    .setFbp(req.cookies['_fbp'])   // _fbp cookie = browser identity signal
    .setFbc(req.cookies['_fbc']);  // _fbc cookie = click identity signal

  const customData = new CustomData()
    .setValue(order.subtotal)
    .setCurrency(order.currencyCode)
    .setContentIds(order.lineItems.map(i => i.sku))
    .setContentType('product')
    .setNumItems(order.lineItems.length)
    .setOrderId(order.id);

  const event = new ServerEvent()
    .setEventName('Purchase')
    .setEventId(eventId)
    .setEventTime(Math.floor(Date.now() / 1000))
    .setUserData(userData)
    .setCustomData(customData)
    .setActionSource('website');

  await new EventRequest(process.env.META_CAPI_ACCESS_TOKEN!, process.env.META_PIXEL_ID!)
    .setEvents([event])
    .execute();
}
```

**Product Catalog Feed for Dynamic Product Ads:**
Generate a CSV feed and serve it at a stable URL. Register it in **Meta Commerce Manager → Catalog → Data Sources → Add Data Feed**.

```typescript
// Generate CSV with required columns: id, title, description, availability, condition, price, link, image_link, brand
// Schedule regeneration every 4 hours — serve at a stable /feeds/meta-catalog.csv endpoint
```

### Step 3: Campaign structure for ecommerce

Build a three-tier campaign structure in **Meta Ads Manager**:

**Campaign 1: Prospecting**
- Objective: Sales → Purchases
- Budget: 60% of total Meta budget
- Audience: Broad (US 18–65, no interest targeting) — use Advantage+ targeting
- Ads: 3–5 creatives (static image, video, carousel, UGC)
- Use **Advantage+ Shopping Campaigns (ASC)** — Meta's automated format consistently outperforms manual campaign structures for ecommerce

**Campaign 2: Retargeting**
- Budget: 30% of total Meta budget
- Ad Set 1: Viewed product but did not add to cart (last 7 days)
  - Audience: Website custom audience → ViewContent event, last 7 days
  - Ads: Dynamic Product Ads (DPA) carousel showing viewed products
- Ad Set 2: Added to cart but did not purchase (last 3 days)
  - Audience: Website custom audience → AddToCart, last 3 days; exclude Purchases last 3 days
  - Ads: DPA + urgency messaging

**Campaign 3: Retention / LTV**
- Budget: 10% of total Meta budget
- Ad Set: Customer list audience (upload from Shopify → Customers export)
  - Exclude customers who purchased in the last 30 days
  - Ads: New arrivals, cross-sell products
- Ad Set: 1% Lookalike of top purchasers (great for prospecting)

### Step 4: Set up Dynamic Product Ads

For Shopify and WooCommerce, the official integrations auto-sync the product catalog. Verify setup:

1. Go to **Meta Commerce Manager → Catalogs → [Your Catalog]**
2. Check **Data Sources** — confirm your platform's feed is syncing and last updated within 24 hours
3. Check **Items** — verify products show correct prices, availability, and images
4. In **Ads Manager → Create Ad Set**: select your catalog under **Catalog Sales** campaign objective
5. Choose **Dynamic formats and creatives** — Meta automatically selects the best ad format per user

### Step 5: Verify Event Match Quality

In **Meta Events Manager → Data Sources → [Your Pixel] → Overview**:

| Signal | How to Improve |
|--------|---------------|
| EMQ below 6 | Send more user data (email, phone, fbp/fbc cookies) |
| CAPI not firing | Check platform integration is set to Maximum data sharing |
| Duplicate conversions | Verify deduplication — eventID must match between Pixel and CAPI |
| ViewContent not firing | Check the platform integration is active and pixel is on product pages |

## Best Practices

- **Use Advantage+ Shopping Campaigns (ASC) for prospecting** — Meta's automated campaign type consistently outperforms manual structure for ecommerce; start here, not manual campaigns
- **Set data sharing to Maximum on Shopify/WooCommerce** — this single setting enables CAPI and is worth significantly more accurate attribution than the default
- **Pass `_fbp` and `_fbc` cookies in CAPI** — these are the strongest identity signals for iOS 14+ attribution; include them in every CAPI event
- **Use `order_id` as the deduplication key** — prevents duplicate conversion counting when both Pixel and CAPI fire for the same purchase
- **Exclude recent purchasers from prospecting** — add a 30-day purchaser exclusion to cold campaigns to protect budget
- **Refresh creative every 4–6 weeks** — Meta campaigns show creative fatigue quickly; rotate 3–5 variations per ad set

## Common Pitfalls

| Problem | Solution |
|---------|----------|
| Duplicate purchase conversions in Ads Manager | Ensure `eventID` is identical in both Pixel and CAPI calls for the same event; Shopify's native integration handles this automatically |
| Conversions under-reported after iOS 14 | Set data sharing to Maximum in the Shopify Facebook channel settings or enable CAPI in WooCommerce Facebook plugin |
| Dynamic Product Ads show wrong price | Shopify/WooCommerce catalog syncs happen up to every 24 hours; for time-sensitive price changes, trigger a manual sync |
| Low EMQ score despite native integration | Go to Meta Events Manager → check that both browser and server events are showing; verify the integration is fully authorized |
| iOS 14+ campaign reach is low | Go to Meta Business Manager → Brand Safety → Domains → Verify your domain; enable Aggregated Event Measurement |
| Ad account disabled | Never send raw (unhashed) PII through the API; use the official SDK which hashes all data automatically |

## Related Skills

- @google-ads-ecommerce
- @tiktok-ads-integration
- @google-shopping-feed
- @email-marketing-automation
- @marketing-attribution-dashboard

Related Skills

shopify-metafields

from finsilabs/awesome-ecommerce-skills

Store custom data on any Shopify resource — products, orders, customers — using typed metafield definitions accessible from Liquid and the Storefront API

stripe-integration

from finsilabs/awesome-ecommerce-skills

Build secure payment flows with Stripe — Payment Intents, subscription billing, webhook handling, and European SCA compliance for card payments

paypal-integration

from finsilabs/awesome-ecommerce-skills

Add PayPal, Venmo, and Pay Later buttons to your store using the PayPal Commerce Platform SDK with Express Checkout for one-tap buying

video-commerce-integration

from finsilabs/awesome-ecommerce-skills

Enable shoppable video experiences with live shopping events, interactive product hotspots, and one-click checkout directly from video and livestream content

tiktok-shop-integration

from finsilabs/awesome-ecommerce-skills

Sync your product catalog to TikTok Shop, manage orders and inventory, and enable shoppable content with live shopping and affiliate creator programs

tiktok-ads-integration

from finsilabs/awesome-ecommerce-skills

Launch TikTok ad campaigns for ecommerce with Events API server-side tracking, Spark Ads, catalog sync, and shopping ads for product discovery

influencer-marketplace-integration

from finsilabs/awesome-ecommerce-skills

Connect to influencer networks to discover creators, manage campaign briefs, track deliverables, and measure ROI across Instagram, TikTok, and YouTube

pos-integration

from finsilabs/awesome-ecommerce-skills

Connect your physical point-of-sale system to your online store for unified inventory, shared customer records, and omnichannel order management

erp-integration

from finsilabs/awesome-ecommerce-skills

Sync orders, inventory, and customer data between your store and ERP systems like SAP, NetSuite, or Odoo using middleware and async queues

email-service-integration

from finsilabs/awesome-ecommerce-skills

Send reliable transactional emails (order confirmations, shipping updates) via SendGrid, SES, or Postmark with templates and deliverability best practices

analytics-integration

from finsilabs/awesome-ecommerce-skills

Implement GA4, Meta Pixel, and server-side tagging with a proper data layer so you capture accurate conversion events for ad campaigns

commerce-js-integration

from finsilabs/awesome-ecommerce-skills

Build a lightweight headless store using the Commerce.js SDK for product display, cart management, and checkout without a heavy backend