> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anotherwrapper.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Meta Ads

> Optional Meta Pixel and Conversions API checkout attribution

<Info>
  Meta Ads support is **completely optional**. If you don't run Meta Ads, you can skip this entirely.
</Info>

## What This Does

This feature tracks the two Meta events most people care about for paid traffic:

* **`InitiateCheckout`** -- when someone clicks a checkout button
* **`Purchase`** -- when the payment webhook succeeds and the purchase is stored

That gives you clean ad performance measurement without forcing Meta code into the generic analytics layer.

## Why It's Separate From Analytics

In this repo:

* Product analytics live under `lib/analytics/*`
* Meta checkout attribution lives under `lib/attribution/meta/*`

That split is intentional. PostHog, Plausible, and DataFast are general analytics tools. Meta Ads is a paid acquisition channel with its own tracking requirements. Keeping them separate means you're never forced to enable Meta just because the feature exists.

## Setup

<Steps>
  <Step title="Get your Meta credentials">
    You'll need your Meta Pixel ID and a Conversions API access token from Meta Events Manager.
  </Step>

  <Step title="Add env vars">
    ```env theme={null}
    NEXT_PUBLIC_ENABLE_META_ATTRIBUTION=true
    NEXT_PUBLIC_META_PIXEL_ID=your-pixel-id
    META_ACCESS_TOKEN=your-access-token
    ```

    Optional for testing:

    ```env theme={null}
    NEXT_PUBLIC_META_TEST_EVENT_CODE=your-test-code
    ```
  </Step>

  <Step title="Restart the app">
    The Meta Pixel only loads when `NEXT_PUBLIC_ENABLE_META_ATTRIBUTION=true` and the required values are present.
  </Step>

  <Step title="Test with a checkout flow">
    Click a checkout button and complete a purchase. Check Meta Events Manager to confirm both events fire.
  </Step>
</Steps>

## How the Flow Works

1. A user clicks a checkout CTA rendered through `CheckoutLink`
2. The repo sends Meta `InitiateCheckout` in the browser
3. The payment provider completes checkout
4. Your webhook is verified by the shared payment route
5. The purchase is stored by the shared payment processor
6. The repo sends Meta `Purchase` through Conversions API

<Warning>
  **Only checkout buttons that go through the shared checkout abstraction get the Meta browser event automatically.** Use `components/(ui-components)/payments/checkout-link.tsx` for your CTAs. Hardcoded raw checkout URLs in random UI files will not trigger Meta events.
</Warning>

## What Meta Receives

The implementation sends:

* Product/content identifiers from the shared checkout catalog
* Value and currency
* Hashed user identity data when available
* A stable event ID for purchase deduplication

The purchase event is emitted after the purchase row is inserted -- the safest place to do it.

## Key Files

* `lib/attribution/meta/provider.tsx` -- Meta provider component
* `lib/attribution/meta/browser.ts` -- browser-side pixel events
* `lib/attribution/meta/conversions-api.ts` -- server-side Conversions API
* `components/(ui-components)/payments/checkout-link.tsx` -- checkout CTA component
* `lib/payments/processor.ts` -- where purchase events fire

## Verify It Works

<Check>
  Your Meta Ads setup is working if:

  * The Meta Pixel loads only when enabled
  * Clicking a checkout CTA triggers `InitiateCheckout`
  * A successful purchase webhook triggers `Purchase`
  * Events appear in Meta Events Manager
</Check>

<Tip>
  For testing, set `NEXT_PUBLIC_META_TEST_EVENT_CODE` and confirm test events appear under that code in Events Manager.
</Tip>

<AccordionGroup>
  <Accordion title="Pixel loads but no events fire">
    Make sure your checkout buttons use the `CheckoutLink` component, not hardcoded URLs.
  </Accordion>

  <Accordion title="InitiateCheckout works but Purchase doesn't">
    Check that `META_ACCESS_TOKEN` is set. The Purchase event goes through the server-side Conversions API, which needs the token.
  </Accordion>

  <Accordion title="Events don't appear in Events Manager">
    Double-check your Pixel ID. Also verify that checkout URLs are present in your env -- the Meta feature won't fire events if there's nothing to check out.
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="Payments" icon="money-bill" href="/payments">
    See how hosted checkout links and payment webhooks work in the repo.
  </Card>

  <Card title="Analytics" icon="chart-line" href="/services/analytics">
    Read about the separate product analytics layer for PostHog, Plausible, and DataFast.
  </Card>
</CardGroup>