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

# Meta Pixel and Conversions API setup

> Connect a website Dataset, validate browser Pixel and Conversions API events, and define when each approved event may fire.

Use this guide to connect Meta website measurement to FloKit-generated campaign pages. It covers
browser Pixel and server-side Conversions API (CAPI) delivery for a website. Native-app attribution
remains the responsibility of the app's mobile measurement provider.

<Warning>
  Do not paste access tokens, test-event codes, passwords, two-factor authentication codes, live user
  data, or screenshots containing credentials into documentation, chat, email, or support tickets.
</Warning>

## Before you start

You need:

* administrator access to the relevant Meta Business Portfolio and ad account;
* one existing website Dataset (also called a Pixel in some Meta screens), or permission to create one;
* the production website origin that will send events;
* access to FloKit's masked Meta connection form; and
* an approved event plan and consent policy.

Connecting an ad account does not install a Pixel or enable CAPI. Treat campaign access and signal
delivery as separate integrations, and keep event delivery disabled until the validation checklist
passes.

## Make one Dataset available

<Steps>
  <Step title="Choose the website Dataset">
    Open [Meta Events Manager](https://business.facebook.com/events_manager2/list) and select the
    Dataset intended for the production website.

    Meta may label the asset **Dataset**, **Pixel**, or **Dataset and Pixel**. Reuse the established
    Dataset when one exists. If a new one is required, choose **Connect data → Web → Connect**, give it
    a generic operational name, and select the manual **Conversions API and Meta Pixel** setup path.
  </Step>

  <Step title="Connect the Dataset to the ad account">
    In [Meta Business Settings](https://business.facebook.com/settings), open **Data sources →
    Datasets** (or **Pixels**), select the Dataset, and use **Connected assets → Add assets** to connect
    the intended production ad account.

    Verify the account name, currency, and status before continuing. Do not connect unrelated assets.
  </Step>

  <Step title="Grant minimum partner access">
    Use the partner-sharing instructions displayed in FloKit's Meta setup screen. Share only the
    selected Dataset and grant the minimum permission Meta requires to manage the asset and send server
    events.

    Do not copy Business Portfolio IDs or other live asset identifiers into public documentation.
  </Step>

  <Step title="Confirm the selection in FloKit">
    In the masked FloKit setup form, select the Dataset and confirm that it belongs to the intended ad
    account. Enter any server-event credential only in the masked credential field.
  </Step>
</Steps>

Meta's current creation flow is also documented in its
[Pixel setup guide](https://www.facebook.com/help/messenger-app/952192354843755). Meta recommends
using the browser Pixel and Conversions API together for website events.

## Configure signal delivery

After the Dataset is available:

1. Confirm the Dataset is readable through the connected Meta integration.
2. Create or select a dedicated server-event credential; do not reuse a campaign-management
   credential implicitly.
3. Add the exact production website origin to the approved event-source allowlist.
4. Configure only the approved event mappings.
5. Run Meta Test Events for browser and server delivery.
6. Verify consent handling, event deduplication, and allowed fields.
7. Run a production canary before enabling broader delivery.
8. Enable purchase delivery separately and only after verified payment evidence is available.

If Meta requires an administrator to generate a CAPI access token, enter it directly in FloKit's
password-masked field. Do not route it through a person or store it in a document.

## When events fire

Browser events require the applicable measurement consent. FloKit records its first-party event first,
then sends only the approved Meta event from trusted runtime code. Generated page content cannot add or
change Pixel scripts.

| Meta event            | Delivery       | Fire only when                                                                                                     |
| --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------ |
| `PageView`            | Browser Pixel  | A page view occurs after consent; send it once from the trusted page runtime.                                      |
| `ViewContent`         | Pixel and CAPI | The landing page reaches the visibility threshold or receives a meaningful interaction—not merely when HTML loads. |
| Custom approved event | Pixel and CAPI | The configured qualification or completion rule succeeds.                                                          |
| `InitiateCheckout`    | Pixel and CAPI | The real payment surface opens successfully.                                                                       |
| `Purchase`            | CAPI only      | The payment provider verifies the first non-zero paid transaction; send it once, server-side.                      |

For events sent through both Pixel and CAPI, use the same logical event ID so Meta can deduplicate the
two copies.

### Events and fields that must not be sent

* Send nothing before the applicable measurement consent.
* Do not send quiz answers, free text, health information, financial details, credentials, or other
  sensitive fields.
* Do not include personal data unless it is explicitly approved, legally permitted, and processed in
  the format required by Meta and the organization's privacy policy.
* Do not fire `ViewContent` for an invisible, bounced, or merely prefetched page.
* Do not fire `InitiateCheckout` for a package selection, prefetch, failed handoff, or button click by
  itself.
* Do not fire `Purchase` from a browser callback, return URL, free-trial start, install, renewal,
  refund, or cancellation.
* Do not add a registration event unless a real registration milestone exists.

## Acceptance checklist

The setup is complete only when every check passes:

1. FloKit shows the approved Dataset under **Meta Signal Delivery**.
2. The dedicated CAPI credential test returns an accepted test event from Meta.
3. The approved event-source origin exactly matches the production website origin.
4. Meta **Test Events** shows browser and server copies for each dual-delivery event.
5. The browser and server copies use the same event ID and Meta reports them as deduplicated.
6. Browser tests prove that no Meta request occurs before consent.
7. Event payload inspection confirms that no unapproved or sensitive fields are present.
8. A production canary is accepted without duplicates or unexpected fields.
9. FloKit reaches **Signal ready** before campaign optimization changes to a deeper conversion event.

<Note>
  Seeing `fbq` in page source, seeing only a browser request, or seeing **Meta Ads: Ready** is not
  sufficient. Use Test Events, deduplication evidence, consent tests, and payload inspection as the
  acceptance proof.
</Note>

For background, Meta describes CAPI as a direct server connection for measurement and optimization in
its [Conversions API overview](https://www.facebook.com/business/help/AboutConversionsAPI).

## Troubleshooting

* **No Datasets/Pixels menu:** confirm that the correct Business Portfolio is selected and that the
  administrator has full control.
* **The ad account is unavailable under Connected assets:** assign the ad account to the same Business
  Portfolio, then retry.
* **FloKit is unavailable as a partner:** use the current partner details shown in FloKit's setup
  screen; do not copy identifiers from old documents.
* **More than one Dataset could apply:** stop and verify the established production asset before
  selecting anything.
* **Meta requests authentication, identity, or business verification:** the authorized administrator
  completes it directly in Meta. Do not create replacement assets to bypass the check.