Pixel & CAPI

For Meta and TikTok, conversion attribution requires:

• A Pixel (Meta) / Pixel (TikTok) on your site or app.
• A CAPI (Conversions API) / Events API access token to send events server-side.

Layers handles both server-side via the Layers SDK + ingest pipeline. You don't ship the Meta SDK or TikTok SDK in your app.

How it works

1. The Layers SDK in your app sends events to in.layers.com/l/events.
2. The ingest pipeline stores the event in the SDK event store.
3. The CAPI relay looks up the project layer's CAPI config. If the layer is active and its CAPI block has enabled = true, a pixel_id set, and a resolvable access_token_vault_id, the relay continues.
4. If all conditions are met, the relay POSTs the event to:
   • Meta Graph API's Conversions endpoint (keyed to the Pixel / dataset ID from capi.pixel_id). Events are mapped from the SDK name to a standard Meta event name (e.g. purchase_success → Purchase). Unmapped events are dropped.
   • TikTok Events API. Events are mapped to standard TikTok events; unmapped events dropped.

Where to configure

In each ad layer's settings:

{
  "capi": {
    "enabled": true,
    "pixel_id": "1234567890",
    "access_token_vault_id": "vault_xyz"
  }
}

The vault_id references an entry in the Layers credential vault — the actual token never appears in config.

Generating tokens

Meta

1. Meta Events Manager → your Pixel → Settings → Conversions API.
2. Click Generate access token.
3. Copy.
4. In Layers, paste into the layer setup wizard. Layers stores in vault and shows you the vault_id.

TikTok

1. TikTok Business Center → Events Manager → your Pixel → Settings.
2. Click Generate access token.
3. Copy and paste into Layers.

Test events

After configuration, run a test event:

1. In Layers, the layer's overview tab → Send test event.
2. Open Meta Events Manager → Test Events, or TikTok Events Debugger.
3. Confirm the event arrived.

Event name mapping

Both Meta and TikTok relays map SDK event names to the platform's standard events. Events that don't map are dropped (logged but not forwarded). Dedup across a client-side Pixel and CAPI is handled via event_id, not naming — see below.

Defaults — see standard events for the full mapping table:

• purchase_success, paywall_purchased → Meta Purchase, TikTok Purchase
• subscription_start, trial_start → Meta Subscribe/StartTrial, TikTok Purchase
• add_to_cart → AddToCart
• content_open → ViewContent
• sign_up → CompleteRegistration

Per-layer overrides can be set via capi.event_map on the layer config.

Event ID for dedup

Each Layers SDK event has a UUID event_id. CAPI requests include this ID. If you also have a client-side Pixel firing the same event, ensure both share the event_id so Meta dedupes.

Vault binding

The token is decrypted only inside the CAPI relay path at send time — it never appears in logs or in API responses. See Vault & credential handling.

Multi-pixel setups

For brands with separate Pixels per app or geo:

• Install one Meta Ads layer (or TikTok Ads layer) per Pixel.
• Each layer has its own capi config.
• The CAPI relay routes events to the right Pixel based on the app → project-layer lookup.

Troubleshooting

• Events not arriving — check the layer's overview tab for "CAPI silent failure" warnings. Common cause: vault_id rotated; regenerate.
• Duplicate conversions — the client Pixel and CAPI both reported without sharing event_id. Synchronize event_ids in your client code.
• TikTok event dropped — your custom event name isn't in the standard map. Either rename in your SDK or accept the drop.