{"id":49416214,"url":"https://github.com/databrickslabs/meta-conversions-api-app","last_synced_at":"2026-04-29T03:07:12.696Z","repository":{"id":353655789,"uuid":"1220047085","full_name":"databrickslabs/meta-conversions-api-app","owner":"databrickslabs","description":"A companion Databricks App for the Meta Conversions API marketplace listing. Provides a guided setup experience for connecting your Databricks lakehouse to Meta's Conversions API (CAPI).","archived":false,"fork":false,"pushed_at":"2026-04-24T20:36:05.000Z","size":1288,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-24T22:32:22.249Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/databrickslabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS.txt","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE.md","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-24T13:43:11.000Z","updated_at":"2026-04-24T20:36:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/databrickslabs/meta-conversions-api-app","commit_stats":null,"previous_names":["databrickslabs/meta-conversions-api-app"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/databrickslabs/meta-conversions-api-app","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/databrickslabs%2Fmeta-conversions-api-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/databrickslabs%2Fmeta-conversions-api-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/databrickslabs%2Fmeta-conversions-api-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/databrickslabs%2Fmeta-conversions-api-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/databrickslabs","download_url":"https://codeload.github.com/databrickslabs/meta-conversions-api-app/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/databrickslabs%2Fmeta-conversions-api-app/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32408467,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T02:37:21.628Z","status":"ssl_error","status_checked_at":"2026-04-29T02:36:50.947Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-29T03:07:10.363Z","updated_at":"2026-04-29T03:07:12.682Z","avatar_url":"https://github.com/databrickslabs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Meta Conversions API App for Databricks\n\n[![build](https://github.com/databrickslabs/meta-conversions-api-app/actions/workflows/push.yml/badge.svg)](https://github.com/databrickslabs/meta-conversions-api-app/actions/workflows/push.yml)\n[![codecov](https://codecov.io/github/databrickslabs/meta-conversions-api-app/graph/badge.svg)](https://codecov.io/github/databrickslabs/meta-conversions-api-app)\n![python](https://img.shields.io/badge/python-3.11%2B-blue.svg)\n![node](https://img.shields.io/badge/node-20%2B-green.svg)\n![license](https://img.shields.io/badge/license-Databricks-lightgrey.svg)\n\nA companion Databricks App for the [Meta Conversions API](https://marketplace.databricks.com/details/8a8f4ead-db28-45e9-b39b-aabbbe1dbe08/Meta_Meta-Conversions-API) marketplace listing. Provides a guided setup experience for connecting your Databricks lakehouse to [Meta's Conversions API (CAPI)](https://developers.facebook.com/docs/marketing-api/conversions-api/) — built with FastAPI and React.\n\n\u003e This is a [Databricks Labs](https://databricks.com/learn/labs) project. It is provided as-is and is not formally supported by Databricks. See [`LICENSE`](./LICENSE) for terms of use.\n\n## About the Meta Conversions API\n\nThe Meta Conversions API lets you share server-side marketing data directly from your Databricks lakehouse to Meta, bypassing browser-based limitations like ad blockers and cookie restrictions. When used alongside the Meta Pixel, it improves measurement, reporting, and optimization by providing a more complete view of the customer journey.\n\n**Use cases**\n- **Optimizing ad performance** — Fuel Meta AI's delivery engine with high-quality signals to decrease cost per action\n- **Improving measurement** — Accurately track actions including deep-funnel milestones like subscription renewals or qualified leads\n- **Increasing match quality** — Share hashed first-party data to improve event match quality (EMQ) and enhance audience retargeting\n- **Tracking offline conversions** — Connect in-store purchases and phone-call conversions directly to Meta ad campaigns\n\n## What This App Does\n\n- **Guided wizard** to configure your Meta Pixel ID, access token, and optional test event code\n- **Test connection** to validate credentials against the Meta Graph API before saving\n- **Quick Launch** deploys a ready-to-run UDTF notebook with sample data to your workspace, securely stores your access token in Databricks Secrets, and uses the marketplace listing's mapping YAML when available\n- **Job Setup** lets you configure column mappings from your source table to Meta CAPI parameters (with mandatory transforms enforced per Meta's spec), then creates a Databricks job with optional scheduling\n- **Settings panel** reads your `~/.databrickscfg` profiles, lets you switch workspaces, and shows marketplace listing status\n- **Connection management** saves connections locally, lets you review/edit config, and pick up where you left off\n\n## Prerequisites\n\n- A Databricks workspace\n- The [Meta Conversions API marketplace listing](https://marketplace.databricks.com/details/8a8f4ead-db28-45e9-b39b-aabbbe1dbe08/Meta_Meta-Conversions-API) installed on your workspace\n- A Meta Pixel ID and access token ([how to get them](https://developers.facebook.com/docs/marketing-api/conversions-api/get-started))\n\n## Deploy to Databricks\n\nSee [`docs/deployment.md`](./docs/deployment.md) for the full flow.\n\n```bash\n# Build the frontend\ncd app/frontend \u0026\u0026 npm run build \u0026\u0026 cd ../..\n\n# Create the app\ndatabricks apps create meta-conversions-api-app \\\n  --description \"Meta Conversions API Connector\" \\\n  -p \u003cyour-profile\u003e\n\n# Deploy — note the /app suffix: Marketplace requires the source\n# code to live in a subfolder, so --source-code-path points at app/\ndatabricks apps deploy meta-conversions-api-app \\\n  --source-code-path /Workspace/Users/\u003cyour-email\u003e/meta-conversions-api-app/app \\\n  -p \u003cyour-profile\u003e\n```\n\n## Local Development\n\n### Install dependencies\n\n```bash\n# Python backend (root of repo)\nuv sync --extra dev\n\n# React frontend\ncd app/frontend\nnpm install\n```\n\n### Run\n\n```bash\n# Terminal 1: Backend (port 8000)\ncd app \u0026\u0026 uv run python app.py\n\n# Terminal 2: Frontend dev server (port 5173, proxies /api to backend)\ncd app/frontend\nnpm run dev\n```\n\nOpen http://localhost:5173\n\n## Architecture\n\n```\nmeta-conversions-api-app/\n  app/                        # App source — deployed to Databricks\n    app.py                    # FastAPI entry point (serves API + React SPA)\n    app.yaml                  # Databricks Apps deployment config\n    manifest.yaml             # Marketplace publishing spec\n    server/\n      config.py               # Dual-mode auth (local dev + Databricks App)\n      routes.py               # API endpoints\n      capi_runner.py          # SQL Statement API + temp UDTF execution\n      assets/                 # Bundled notebook + mapping YAML\n    frontend/\n      src/\n        App.tsx               # Main app with routing and state\n        components/           # React components (Wizard, JobSetup, etc.)\n        hooks/useApi.ts       # Fetch hook + POST helper\n      dist/                   # Pre-built bundle (committed)\n  tests/                      # Backend tests\n  docs/                       # User + deployment documentation\n  pyproject.toml              # Project metadata + tool config\n  Makefile                    # clean/lint/fmt/test/coverage/build/deploy\n```\n\n### API Endpoints\n\n| Endpoint | Description |\n|---|---|\n| `GET /api/me` | Current user + workspace from active Databricks profile |\n| `GET /api/profiles` | List `~/.databrickscfg` profiles |\n| `POST /api/profiles/switch` | Switch active Databricks profile |\n| `GET /api/marketplace-listing` | Check if Meta CAPI marketplace listing is installed |\n| `POST /api/test-connection` | Send a test event to Meta Graph API |\n| `POST /api/quick-launch` | Deploy notebook + secrets to workspace |\n| `POST /api/create-job` | Create a Databricks job with notebook + mapping |\n| `GET /api/default-mapping` | Return the default column mapping YAML |\n\n## Column Mapping\n\nThe app uses a YAML-based column mapping to translate your table schema into Meta's CAPI event format. The mapping supports:\n\n- **Server event parameters**: `event_name`, `event_time`, `action_source`, etc.\n- **User data** (`user_data`): `em`, `ph`, `fn`, `ln`, `client_ip_address`, `fbc`, `fbp`, etc.\n- **Custom data** (`custom_data`): `value`, `currency`, `content_ids`, `content_type`, etc.\n- **Transforms**: `sha256`, `normalize` (resolved to `normalize_email`/`normalize_phone`), `to_epoch`, `cast_float`, `cast_int`, `cast_string`\n\nMandatory transforms (e.g. SHA256 hashing for email/phone) are enforced per [Meta's parameter spec](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters).\n\n## Additional Information\n\n- **Direct connection** — Secure server-to-server connection that reduces signal loss caused by connectivity issues or browser loading errors\n- **Deduplication** — Send identical `event_id` values from both the Meta Pixel and the Conversions API to avoid over-reporting\n- **Privacy and control** — Supports Limited Data Use (LDU) to assist with CCPA and GDPR compliance\n- **Governance** — Running within Databricks ensures all marketing activation is managed through Unity Catalog\n\n## Contributing\n\nSee [`CONTRIBUTING.md`](./CONTRIBUTING.md) for development setup, testing, and the PR process.\n\n## Security\n\nTo report a security vulnerability, please see [`SECURITY.md`](./SECURITY.md).\n\n## License\n\nSee [`LICENSE`](./LICENSE) and [`NOTICE.md`](./NOTICE.md). This project is licensed under the Databricks License. `NOTICE.md` lists every bundled third-party dependency and its license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatabrickslabs%2Fmeta-conversions-api-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatabrickslabs%2Fmeta-conversions-api-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatabrickslabs%2Fmeta-conversions-api-app/lists"}