Debugging

Debug logging

Enable verbose logging when initializing:

await layers.init({
  appId: 'app_xxx',
  apiKey: 'unused',
  environment: 'development',
  enableDebug: true,
});

Each track() then prints the payload and the HTTP response from the ingest endpoint.

Event Inspector

Open the Events page on the app dashboard. Events appear within a few seconds of firing. Filter by app_id, event name, or user.

See Event inspector.

CAPI delivery status

Each ad layer's overview tab in the dashboard surfaces CAPI delivery health (success rate, last-delivered timestamp). Watch this after wiring a new layer.

If the layer shows "degraded":

• Re-check the CAPI config (pixel_id / dataset_id set, vault-backed access token still valid).
• Regenerate the CAPI access token if it has expired or been revoked (tokens don't auto-refresh).
• Check Meta / TikTok platform status.

Meta Test Events

In Meta Events Manager → your Dataset (Pixel) → Test Events tab, you can:

• See live CAPI events as they arrive.
• Get a Test Event Code to scope the view to one device.

There is no first-class Layers-side flag to set a test-event-code today. If you need one, pass it as a property on your events and plumb it through a per-app event_map override; otherwise rely on Layers Events page filtering by install_id.

TikTok Events Debugger

Same concept on the TikTok side — Business Center → Events Manager → your Pixel → Debugger.

Common issues

Events not arriving at the Events page

1. Confirm the device is hitting in.layers.com (network inspector, Charles, mitmproxy).
2. Confirm app_id matches the Layers project.
3. If on web, confirm an ad-blocker isn't blocking in.layers.com — set up a custom domain to work around it.
4. If setConsent({ analytics: false }) was called, events are NOT enqueued.

Events in Layers but not in Meta / TikTok

1. The event name isn't in the mapping table and there's no per-app event_map override — the relay drops it silently.
2. CAPI isn't enabled on the ad layer (check capi.enabled, pixel_id, vault-backed access token).
3. Vault-encrypted CAPI token was rotated or revoked.
4. Pixel ID mismatch between the ad layer config and what's installed client-side.

Duplicate conversions

If you also run the Meta Pixel or TikTok Pixel client-side, share the event_id. The SDK generates one automatically; pass it through to your client-side Pixel.

401 / 403 responses

X-App-Id header missing, invalid, or revoked. The response body is intentionally opaque ({ error: "unauthenticated" }) for security — server logs have the structured reason. Check that appId in your SDK config matches the Layers project.

Local echo endpoint

For offline CI tests, point baseUrl at a local HTTP server:

new LayersClient({
  apiKey: 'unused',
  appId: 'app_xxx',
  environment: 'development',
  baseUrl: 'http://localhost:8080',
});

The server won't run the CAPI relay, but you can assert on the request shape.