Measurement Bridge guide
A reusable checklist for first-open measurement and server-side postbacks.
What it can change remotely
The Cloudflare console can register apps, enable first-open measurement, add or disable generic destinations on code-approved receiver hosts, stage the fixed OpenAI Conversions adapter, choose events, map generic fields, select consent gates, and HMAC-sign generic requests without a mobile release.
The OpenAI adapter is compiled and tested locally, but is not deployed or enabled. It still requires a Pixel ID, API key, authoritative server-owned ads consent, provider validation, and explicit enablement. Direct Meta, TikTok, and Google adapters are not active. Never put an access token in an endpoint URL. The bridge also cannot download a brand-new native SDK; that must be compiled, reviewed, and released through Apple or Google.
Add an app and postback
- Open Conversion Relay, enter the Conversion admin token, and load configuration.
- Choose Register another app, assign its stable
app_id, and leave measurement disabled until its build is tested. - For a generic receiver, use a host reviewed in Worker code and enter its exact credential-free HTTPS endpoint, request format, and consent gate. For OpenAI, select the compiled adapter; its endpoint, JSON format, ads-consent gate, and no-HMAC policy are fixed.
- Select only the events the receiver contract requires. OpenAI maps signup, trial, subscription, and first open in compiled code and accepts no operator-defined fields.
- Keep the destination disabled, choose Preview exact plan, and compare the redacted request with the receiver documentation.
- Apply the reviewed plan, test against a non-production receiver or test Pixel, then enable and apply a second reviewed plan.
- Use delivery counters and the stable event ID at the receiver to verify receipt; retries retain that same ID.
Available events
| Event | Truth source |
|---|---|
install_first_open | Compiled Measurement Bridge, once per pseudonymous installation. |
sign_up_completed | Authenticated backend account completion. |
trial_started | Verified RevenueCat webhook only. |
subscription_started | Verified RevenueCat/store purchase only. |
Available fields
| Field | Use |
|---|---|
event_id, event_name, date | Stable deduplication ID, event type, and UTC occurrence time. |
amount, amount_minor, currency | Provider-confirmed commerce value in major or minor units. |
plan_name, product_id | Reviewed plan label and exact store product identifier. |
install_id, account_id_hash, app_id, platform | Pseudonymous attribution and app/platform routing. |
email_sha256 | Normalized hash; preferred where the partner supports it. |
email | Raw email only for authoritative backend events, explicit ads consent, encrypted PII configuration, and an approved partner contract. |
Background delivery contract
- Every event and destination dispatch is durable and idempotent.
- The Worker scheduler retries transient failures with a bounded attempt count and preserves the same event ID.
- Private hosts, redirects, unsafe URLs, excess response bodies, and unapproved fields fail closed.
- HMAC signing lets the receiver verify timestamped content; reveal and store each destination key as a secret.
- Disabling a destination stops new dispatches without deleting the audit history.
Operator to-do
- Document the receiver endpoint, event names, required fields, consent basis, data retention, and deletion path.
- Use hashed identifiers unless a reviewed contract genuinely requires raw PII.
- Advertising delivery requires authoritative server-owned consent and attestation; do not trust a mobile client claim by itself.
- Run the automated plan/form, duplicate-intake, transient failure, consent, signature, app-isolation, and disable tests.
- V1 has no one-click rollback, manual replay, scoped deletion, or provider readback endpoint. To revert configuration, preview and apply known prior values.
- Run
node server/test/conversion_relay_test.mjsbefore deployment. - After deployment, confirm scheduler health and one non-production receiver delivery before enabling production traffic.