# Facebook Pixel

Track browser-side paywall and checkout events from Superwall web paywalls with Facebook Pixel. This integration injects Meta's client-side Pixel script and maps Web2App events to Pixel events.

Use the Facebook Pixel integration to send browser-side events from Superwall
web paywalls to Meta. This integration injects the standard Pixel script into
the page and maps Web2App events to Meta Pixel events such as `ViewContent`,
`InitiateCheckout`, and `Purchase`.

> **Note:** If you need server-side subscription lifecycle events such as
> renewals, cancellations, expirations, or refunds, use
> [Meta Conversion API](/docs/integrations/meta-conversion-api) instead. That
> integration is separate from Facebook Pixel.

In the **Web2App** integrations area, you can connect Facebook Pixel in
Superwall:

<img src="__img0" />

How this integration works [#how-this-integration-works]

Superwall exposes Facebook Pixel as a Web2App browser integration. When the
integration is enabled:

* Superwall injects Meta's `fbq` bootstrap script into the page
* The Pixel is initialized with your `pixelId`
* A `PageView` event is sent when the script loads
* Supported paywall and checkout events are forwarded to `fbq`

This is browser-side tracking for web paywalls. It does not forward
subscription lifecycle events from webhooks, and it does not use Meta's
Conversion API.

Set up in Superwall [#set-up-in-superwall]

Set this up from the dashboard UI rather than by editing a config object.

1. Open your app in Superwall.
2. Go to **Integrations**.
3. Open the **Web2App** integrations area.
4. Add or open **Facebook Pixel**.
5. Enter your **Pixel ID**.
6. Leave **Enabled** on if you want the integration to start sending events
   immediately.
7. Click **Save Integration**.

If the integration already exists, the same screen is used in **Edit
Integration** mode.

Fields shown in the dashboard [#fields-shown-in-the-dashboard]

| UI field   | Required | What to enter                                   |
| ---------- | -------- | ----------------------------------------------- |
| `Pixel ID` | Yes      | Your Facebook Pixel ID from Meta Events Manager |
| `Enabled`  | No       | Turn the integration on or off                  |

Superwall stores the underlying Web2App integration config for you. You do not
need to manually write `integrationId` or `config.pixelId` in the dashboard.

Getting your Pixel ID [#getting-your-pixel-id]

You only need the Pixel ID for this integration.

1. Go to [Meta Events Manager](https://business.facebook.com/events_manager).
2. Select your Pixel from **Data Sources**.
3. Copy the Pixel ID shown at the top of the page.

Script bootstrap [#script-bootstrap]

When the integration loads, Superwall injects Meta's standard client-side
script into the page:

```html
<script>
  fbq("init", "123456789012345");
  fbq("track", "PageView");
</script>
```

Superwall also adds Meta's `noscript` image fallback for the same Pixel ID.

Event mapping [#event-mapping]

The browser integration maps Web2App events to Pixel events as follows:

| Superwall browser event    | Meta Pixel event                         | Notes                                                                         |
| -------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------- |
| `paywall_open`             | `ViewContent`                            | Includes `content_name`, `content_id`, and `content_type: "paywall"`          |
| `transaction_start`        | `InitiateCheckout`                       | Includes `content_ids` and `content_type: "product"`                          |
| `transaction_complete`     | `Purchase`                               | Includes `transaction_id`, `content_ids`, and optional `value` and `currency` |
| `paywall_close`            | `trackCustom("PaywallClosed")`           | Custom event with `paywall_id`                                                |
| `manageLink_click`         | `trackCustom("ManageLinkClick")`         | Custom event with subscription fields                                         |
| `activateDeviceLink_click` | `trackCustom("ActivateDeviceLinkClick")` | Custom event with subscription fields                                         |

Event payload details [#event-payload-details]

Each mapped event sends a small payload based on the browser event data.

`paywall_open` -> `ViewContent` [#paywall_open---viewcontent]

```json
{
  "content_name": "Main paywall",
  "content_id": "paywall_123",
  "content_type": "paywall"
}
```

`transaction_start` -> `InitiateCheckout` [#transaction_start---initiatecheckout]

```json
{
  "content_ids": ["com.app.premium.monthly"],
  "content_type": "product"
}
```

`transaction_complete` -> `Purchase` [#transaction_complete---purchase]

```json
{
  "transaction_id": "txn_123",
  "content_ids": ["com.app.premium.monthly"],
  "content_type": "product",
  "value": 9.99,
  "currency": "USD"
}
```

The `value` and `currency` fields are only included when they are present in
the browser event payload.

`paywall_close` -> `PaywallClosed` [#paywall_close---paywallclosed]

```json
{
  "paywall_id": "paywall_123"
}
```

`manageLink_click` -> `ManageLinkClick` [#managelink_click---managelinkclick]

```json
{
  "subscription_name": "Premium Monthly",
  "subscription_status": "active",
  "redemption_code": "ABC123",
  "provider": "stripe"
}
```

`activateDeviceLink_click` -> `ActivateDeviceLinkClick` [#activatedevicelink_click---activatedevicelinkclick]

```json
{
  "subscription_name": "Premium Monthly",
  "redemption_code": "ABC123"
}
```

Facebook Pixel vs. Meta Conversion API [#facebook-pixel-vs-meta-conversion-api]

These integrations are related, but they solve different problems.

| Integration         | Tracking mode | Best for                                          | Does it send renewals, cancellations, and refunds? |
| ------------------- | ------------- | ------------------------------------------------- | -------------------------------------------------- |
| Facebook Pixel      | Browser-side  | Web paywall interactions and checkout flow events | No                                                 |
| Meta Conversion API | Server-side   | Subscription lifecycle and revenue webhook events | Yes                                                |

Use Facebook Pixel when you want client-side behavioral signals from web
paywalls. Use [Meta Conversion API](/docs/integrations/meta-conversion-api)
when you need server-side revenue and subscription lifecycle events.

Testing the integration [#testing-the-integration]

Validate the browser-side integration before relying on it in campaigns.

1. Enable the Facebook Pixel integration with your Pixel ID.
2. Open a web paywall that uses the integration.
3. Confirm `PageView` appears in Meta Events Manager.
4. Trigger paywall and checkout events.
5. Verify `ViewContent`, `InitiateCheckout`, `Purchase`, and any custom events
   appear as expected.

You can also confirm that `fbq` is loaded in the browser and inspect network
requests to Meta while exercising the paywall flow.

Common use cases [#common-use-cases]

Track paywall impressions [#track-paywall-impressions]

Use `ViewContent` from `paywall_open` to measure paywall views and build
remarketing audiences around paywall engagement.

Track checkout starts [#track-checkout-starts]

Use `InitiateCheckout` from `transaction_start` to see where users begin the
purchase flow but do not complete it.

Track completed purchases in the browser [#track-completed-purchases-in-the-browser]

Use `Purchase` from `transaction_complete` to capture client-side checkout
completion on web paywalls.

Track manage-subscription interactions [#track-manage-subscription-interactions]

Use `ManageLinkClick` and `ActivateDeviceLinkClick` to understand how users
interact with account and device-link flows.

Troubleshooting [#troubleshooting]

Events are not appearing in Meta [#events-are-not-appearing-in-meta]

**Possible causes:**

* The Pixel ID is incorrect
* The browser integration is not enabled
* The page did not load the injected `fbq` script
* The paywall flow did not emit the expected browser event

**Solutions:**

1. Verify the Pixel ID in Meta Events Manager.
2. Confirm the integration is enabled for the web paywall flow.
3. Check that `fbq` is available in the page.
4. Inspect the browser console and network requests during the flow.

`Purchase` is missing value or currency [#purchase-is-missing-value-or-currency]

**Possible causes:**

* The `transaction_complete` event did not include those fields

**Solutions:**

* Verify the browser event payload includes `value` and `currency`.
* If you need more complete revenue lifecycle reporting, use
  [Meta Conversion API](/docs/integrations/meta-conversion-api).

You need renewals, cancellations, or refunds [#you-need-renewals-cancellations-or-refunds]

Facebook Pixel does not send those lifecycle events in this integration.

Use [Meta Conversion API](/docs/integrations/meta-conversion-api) for that
server-side workflow.

Additional resources [#additional-resources]

* [Meta Events Manager](https://business.facebook.com/events_manager)
* [Meta Pixel documentation](https://developers.facebook.com/docs/meta-pixel/)
* [Meta Conversion API](/docs/integrations/meta-conversion-api) for
  server-side subscription lifecycle tracking