Troubleshooting (Android)

Work top-down. Start with the raw curl from Integration → Verifying the fetch — it tells you whether the problem is the server (auth / campaign) or the client (SDK config / device).

---

1. The fetch returns 401 {"message":"Invalid sdkKey"}

The key does not resolve to an active source in the environment you are hitting. Check, in order:

1. Right key — sdkKey (or the SDK apiKey it defaults to) is the public key for a real, active in-app source.
2. Right environment — the source exists in the environment your fetchEndpoint targets (e.g. an EU key against api-eu, not a prod key against EU).
3. Right URL — the URL includes the correct prefix. Most deployments need /engage in the path (…/engage/v1/push/inapp/fetch). A 404 or HTML response means the prefix/host is wrong.

Until the fetch stops returning 401, nothing can render on any device.

---

2. The fetch returns 201 but messages is empty

Auth is fine; no campaign matched. Re-check the Campaign Setup checklist. In practice the cause is almost always one of:

Cause	Fix
Campaign is not API-pull (delivery mode is FCM)	Author it with delivery mode API pull (deliveryMode: "api").
Campaign is not LIVE	Set status to LIVE.
Campaign is action/trigger-based	Pull only supports Everyone / Audience.
Audience campaign, user not a member	Test with Everyone first; ensure the user is identify()-ed and lives in the right environment.
condition.target is set but the fetch sent a different / no target	Match the screen name, or clear the target.
Time window closed	displayTime in the past, expireDate in the future.
Wrong project / environment	The sdkKey resolves to a different project than the one that owns the campaign — see Environment matching.
Already delivered to this user	Each campaign is delivered to a distinctId once. Test with a fresh distinctId (or reinstall).
Just published — list cache	The active-campaign list can be cached briefly; wait up to a few minutes.

---

3. The fetch returns a message but nothing shows

Symptom	Cause / fix
Nothing renders, banner is blank	The campaign matched but has empty layout content. Author real content.
It showed once and never again	1-hour per-pushId de-dup, and permanent per-user server de-dup. Use a fresh distinctId to re-test.
It renders on the wrong screen	Rendering uses the foreground Activity at render time; check excludedActivities and your screen-targeting call.

Turn on debugLogging = true and watch logcat for the fetch, the status code, de-dup skips, and render decisions.

---

4. Android-specific gotchas

• API level 29+ required. On API 24–28 the entire pull lifecycle is inert, even with a correct config. Test on an API 29+ device/emulator.
• Jetpack Compose navigation (single ComponentActivity, no Fragments) does not fire the Activity/Fragment screen-change hook, so the automatic screen-change fetch won't trigger on Compose route changes. Use a manual refreshEngageInAppMessages(context, target) on route change (see Screen targeting).

---

5. Nothing happens at all (no request)

• engageInAppConfig is null → the feature is off. Set it before setup().
• distinctId is empty → the fetch is skipped. Ensure the SDK has an anonymous or identified id.
• autoFetchOnForeground = false and you never call refreshEngageInAppMessages(...) → there is no trigger. Either enable auto-fetch or add a manual call.
• Device is on API < 29 → the pull flow is inert.