Developer

Troubleshooting

Turn on App SDK diagnostics with a logger, read each log line, and fix common setup problems such as a blocked events host or an invalid publishable key.

Pass a logger to see what the SDK does. Without a logger the SDK writes nothing, not even to the console.

Turn on diagnostics

await Apex.configure({
  publishableKey: 'apx_pk_live_…',
  shopId: 'YOUR_SHOP_ID',
  logger: (line) => console.debug(line),
});

In the tables below, … and 4xx stand for the values in the real line, such as a delay or an HTTP status. Log lines never contain the key, the Authorization header, response bodies or exception details. Each network failure type logs at most once per 60 seconds, so a long outage does not flood the log. An error in your logger function does not affect the SDK.

Setup and network

Log line	Meaning and fix
`Apex configure: invalid options; SDK stopped`	An option is invalid, for example a key that does not start with `apx_pk_` or a missing shop ID. Fix the options. The SDK does no storage or network work.
`Apex SDK stopped: invalid_publishable_key`	Apex does not know the key, or it was revoked or expired. Create a new publishable key. Flag reads keep their last values.
`Apex SDK stopped: publishable_key_not_allowed`	The request used a route that does not accept publishable keys. Check that `baseUrl` is the Apex events host.
`Apex assignment fetch failed: network error; retry scheduled in …`	The app could not reach Apex. On Cordova, check the content security policy. Also check the device connection.
`Apex event delivery failed: network error; retry scheduled in …`	Events could not be sent. They stay in the queue and the SDK retries.
`Apex assignment fetch failed: HTTP 503; retry scheduled in …`	Apex is temporarily unavailable. The SDK waits and retries.
`Apex assignment fetch failed: HTTP 4xx; no retry scheduled`	Apex rejected the request. Check `shopId` and `environment`.
`Apex event delivery failed: HTTP 4xx; batch dropped`	Apex rejected a batch. The SDK removes it from the queue.
`Apex requires a browser or WebView; initialization skipped`	The SDK ran without a DOM, for example during server-side rendering. Configure it again in the browser.
`Apex initialization failed`	The SDK could not start, for example because device storage failed.

The SDK sends the publishable key only as an Authorization: Bearer header and sends no cookies. Cookie authentication does not work from capacitor://localhost.

Storage

Log line	Meaning and fix
`Apex identity storage unavailable; networking stopped`	The SDK could not read or write its device ID. Check your storage adapter.
`Apex identity could not be saved; the SDK stopped networking`	An `identify()` write failed. The SDK keeps the previous identity and stops networking until a later `identify()` saves.
`Apex could not persist events`	A queue write failed. The SDK keeps the previous queue.
`Apex dropped purchase: queue write failed`	A purchase could not be saved. Call `trackPurchase()` again with the same order ID.
`Apex could not load …`	A stored value could not be read. The SDK uses defaults.
`Apex dropped event rows: queue capacity`	The queue was full, so the SDK removed the oldest events.
`Apex dropped expired or oversized event rows`	Events were older than the retention window, or a purchase was too large.

Flags

Log line	Meaning and fix
`Apex typed flag 'key' unavailable or incompatible; using default`	The flag has no assignment, or its value does not match your default type or validator. Check the flag key, its API delivery, and the value type.
`Apex dropped exposure: session dedupe capacity`	One session recorded more than 4,096 different exposures. New exposures are dropped until the next session.

Events

Log line	Meaning and fix
`Apex dropped event: invalid event name`	The name is empty or longer than 256 characters.
`Apex dropped event: property email is not allowed`	A property key is blocked as personal data. Remove it.
`Apex dropped event: revenue must be a finite number`	The `revenue` property is not a valid number.
`Apex ignored non-JSON event properties`	Properties must be a plain JSON object.
`Apex dropped purchase: order_id must be a string`	The order ID is not a string, or it is longer than 1,024 characters.
`Apex dropped purchase: order_id is required`	The order ID is empty.
`Apex dropped purchase: revenue must be a finite non-negative number`	Revenue is negative, infinite or not a number.
`Apex dropped purchase: currency must be a 3-letter ISO 4217 code`	Use a code such as `EUR` or `USD`.
`Apex dropped purchase: group exceeds queue capacity or the 200-event request limit`	The purchase has more rows than the queue or one request can hold.

Other lines

Log line	Meaning and fix
`Apex ignored invalid identity or attributes`	The user ID is empty, too long or not a string. Use a non-empty string of up to 1,024 characters, or `null`.
`Apex ignored invalid app state`	`setAppState()` accepts only `foreground` or `background`.
`Apex ignored invalid change handler`	`onChange()` needs a function.
`Apex listener failed`	Your `onChange` handler threw an error. Other handlers still run.
`Apex shell lifecycle listener unavailable`	The Capacitor App listener could not be added. Forward lifecycle events yourself.

Common problems

Every request fails with a network error on Cordova. Add connect-src https://events.drip-apex.com to the content security policy.

Flags always return the default. Check that the flag is active and uses API delivery, that the key matches, and that the user matches the flag's targeting. Use the device lookup to see the device's exposures and events.

Screen URLs show app://unknown/home. The applicationId must contain only letters, digits, dots and hyphens, and must start and end with a letter or digit. Underscores are not allowed.

The app still runs the old SDK after you reinstall the same version. Clear Angular's .angular/cache folder and rebuild.

Results do not show test-build events. Test builds send QA traffic. Turn on the QA toggle in results.