Meta Conversions API - Databricks App

**Overview**
A guided companion app for the [Meta Conversions API](https://marketplace.databricks.com/details/8a8f4ead-db28-45e9-b39b-aabbbe1dbe08/Meta_Meta-Conversions-API) Marketplace listing. The data listing gives you the UDTF, sample dataset, and example notebook that power server-side conversion events from your Databricks lakehouse to Meta. This app wraps all of that in a UI — so you can configure credentials, send test events, and schedule a production job in minutes, without writing SQL or wiring up secrets by hand.

**Databricks Labs** — community-maintained companion to the Meta Conversions API data listing. Same underlying UDTF; guided setup on top.

---

**Use Cases**

Powers the same use cases as the underlying [data listing](https://marketplace.databricks.com/details/8a8f4ead-db28-45e9-b39b-aabbbe1dbe08/Meta_Meta-Conversions-API) — the app is just the fastest path to activating them:

- **Optimizing ad performance** — fuel Meta AI's delivery engine with high-quality server-side signals to decrease cost per action.
- **Improving measurement** — accurately track deep-funnel milestones like subscription renewals, qualified leads, and offline conversions.
- **Increasing match quality** — share hashed first-party data to improve event match quality (EMQ) and enhance audience retargeting.
- **Tracking offline conversions** — connect in-store purchases and phone-call conversions directly to your Meta ad campaigns.

---

**Prerequisites**

Before installing this app, make sure you have:

1. **The [Meta Conversions API](https://marketplace.databricks.com/details/8a8f4ead-db28-45e9-b39b-aabbbe1dbe08/Meta_Meta-Conversions-API) data listing** installed on that workspace — this provides the sample dataset the app depends on. Install it first.
2. **A Meta Pixel and an access token**:
- [How to set up a Meta Pixel](https://www.facebook.com/business/help/952192354843755)
- [How to generate a Conversions API access token](https://developers.facebook.com/docs/marketing-api/conversions-api/get-started)

---

**Why install this app**

Install the [Meta Conversions API](https://marketplace.databricks.com/details/8a8f4ead-db28-45e9-b39b-aabbbe1dbe08/Meta_Meta-Conversions-API) data listing first. It gives you everything you need to activate conversion data at scale:

- **Direct connection** — a secure server-to-server path from your Databricks lakehouse to Meta's Conversions API, bypassing browser-based limitations such as ad blockers and cookie restrictions.
- **Deduplication** — pair the Meta Pixel and the Conversions API with a shared `event_id` to avoid over-reporting.
- **Privacy and control** — Limited Data Use (LDU) support to assist with CCPA and GDPR compliance, with full control over what is shared.
- **Governance** — all marketing activation runs inside Databricks, managed through Unity Catalog for transparency and scale.

This app **removes the manual setup** between *"marketplace listing installed"* and *"first event sent"* and condenses the [Meta Conversions API](https://marketplace.databricks.com/details/8a8f4ead-db28-45e9-b39b-aabbbe1dbe08/Meta_Meta-Conversions-API) workflow into a five-minute guided experience.

---

**What the app provides**

- **Setup Wizard** — paste your Meta Pixel ID and access token; the app stores the token in a Databricks Secret scope on your behalf and validates it against the Meta Graph API before saving.
- **Test Connection** — sends a test event to Meta so you know the credentials are valid before you commit.
- **Quick Start** — one-click execution against the marketplace sample dataset. Validates the full Databricks → Meta chain in seconds.
- **Deploy Notebook** — drops the UDTF example notebook into your workspace, pre-wired to your secret scope and the marketplace catalog you installed.
- **Job Setup** — point the connector at your own table, map your columns to Meta's Conversions API parameters (SHA-256 hashing of email and phone is enforced to match Meta's spec), and schedule a Databricks Job with a cron expression.
- **Test mode** — use Meta's `test_event_code` so events land in the Test Events tab of Meta Events Manager, separate from production analytics.

---

**5-minute Quick Start**

**1\. Authorize the app**

On first open, Databricks asks you to grant six scopes on your behalf: `sql`, `sql.warehouses`, `catalog.catalogs:read`, `catalog.schemas:read`, `catalog.tables:read`, and `files.files`. These let the app execute the UDTF, list tables for you to pick from, and deploy the notebook to your workspace. Click **Authorize**.

**2\. Point at your catalog**

The app auto-detects the catalog where you installed the Meta CAPI data listing. If it can't, enter the name you chose at install time — it defaults to something like `meta_meta_conversions_api`.

**3\. Run the Wizard**

- **Step 1:** Enter your Pixel ID and paste the access token. Leave *Store as a Databricks Secret* checked.
- **Step 2:** Click **Test Connection**. This sends a test event to `graph.facebook.com/v24.0/<pixel-id>/events` — you should see *"Connection successful — credentials verified."*
- Click **Save Configuration**. The app creates a Secret scope named `meta_capi_pixel_<pixel-id>` and stores your token there.

**4\. Run a Quick Start against the sample dataset**

From the post-setup screen, click **Run Now** under *Quick Start*. The app:

1. Queries the marketplace sample table (`<your-catalog>.meta_capi.conversion_data`).
2. Runs the UDTF via the SQL Statement Execution API using a session-scoped temporary function.
3. Posts the resulting batches to Meta's Conversions API.
4. Reports the batch summary — *"Sent 1001 events to Meta CAPI (2 batches)."*

If you're in test mode, head to **Meta Events Manager → Test Events** to see events appear within seconds.

---

## Where to go next

- **Source code & issues:** [github.com/databrickslabs/meta-conversions-api-app](https://github.com/databrickslabs/meta-conversions-api-app)
- **Full documentation:** [docs/](https://github.com/databrickslabs/meta-conversions-api-app/tree/main/docs) — deployment guide, architecture overview, troubleshooting, user guide
- **Meta Conversions API reference:** [developers.facebook.com/docs/marketing-api/conversions-api](https://developers.facebook.com/docs/marketing-api/conversions-api/)
- **The underlying data listing:** [Meta Conversions API on Databricks Marketplace](https://marketplace.databricks.com/details/8a8f4ead-db28-45e9-b39b-aabbbe1dbe08/Meta_Meta-Conversions-API)

## Troubleshooting

- **Wizard can't reach Meta** — confirm your access token has the `ads_management` permission; token errors surface on the Test Connection step.
- **Quick Start fails with "table not found"** — confirm the [Meta Conversions API](https://marketplace.databricks.com/details/8a8f4ead-db28-45e9-b39b-aabbbe1dbe08/Meta_Meta-Conversions-API) data listing is installed on the same workspace and you entered the correct catalog name.
- **"Permission denied on secret scope"** — can happen after redeploying the app: each Databricks App has its own service principal, and the old SP owns the scope ACL. Grant the new SP `WRITE` with `databricks secrets put-acl <scope> <new-sp-client-id> WRITE`.
- **Full troubleshooting guide:** [docs/troubleshooting.md](https://github.com/databrickslabs/meta-conversions-api-app/blob/main/docs/troubleshooting.md)

**Support**

This is a [Databricks Labs](https://databricks.com/learn/labs) project — community-maintained, not formally supported. File bugs and feature requests at [github.com/databrickslabs/meta-conversions-api-app/issues](https://github.com/databrickslabs/meta-conversions-api-app/issues).

**License**

Distributed under the [Databricks License](https://github.com/databrickslabs/meta-conversions-api-app/blob/main/LICENSE). See [NOTICE.md](https://github.com/databrickslabs/meta-conversions-api-app/blob/main/NOTICE.md) for the full list of third-party dependencies and their licenses.