Skip to main content
Use this page when a Remote UI placement does not render or actions do not work.

​
Placement does not render

Check:
  • The app requests the same placement ID that exists in Remote UI.
  • The placement is enabled.
  • The requested locale has a config, or the placement has a default locale.
  • The config JSON is valid.
  • Runtime placeholders have matching definitions.
  • Product placeholders point to existing products.
  • The user has not already seen a placement configured as Show only once per user.
  • The user matches the placement targeting conditions.
  • Capture protection has not blocked this user.

​
Requests increase but shown does not

This usually means PNLight received the request but had no config it could return for display. Common causes:
  • Placement missing from Remote UI.
  • Placement disabled.
  • Missing locale config.
  • Missing or unresolved runtime placeholder.
  • Attribution is required but not resolved yet.
  • Show-once rules suppress the placement for that user.
  • Targeting conditions do not match the user.
  • Capture protection blocks the user after capture is detected.

​
Placeholder does not resolve

Check the placement in Remote UI:
  • Every placeholder token uses the {{key}} format.
  • Each token has a matching placeholder definition.
  • Placeholder keys start with a letter and contain only letters, numbers, and underscores.
  • Product placeholders point to products that still exist in Products.
If PNLight cannot resolve a placeholder, it does not return that placement config.

​
Config request fails

Recent SDK wrappers separate loading errors from “no UI for this placement”.
  • In Swift, use getUIConfigResult when you fetch configs manually.
  • In React Native and Flutter, handle onError on RemoteUiView.
  • During QA, pass ignoreCache when you need a fresh server response.

​
Actions do not work

Check your app action handler:
  • Handle the expected logId, path, or action value.
  • Read parameters defensively.
  • Provide a fallback for unknown actions.

​
Purchase follow-ups do not run

Check the Remote UI document:
  • on_success needs "schemaVersion": 3 or "schemaVersion": 4.
  • on_fail and on_cancel need "schemaVersion": 4. Schema v3 configs still run on_success only.
  • A pending StoreKit purchase runs no follow-up. The current screen stays in place until Apple approves or fails the transaction.

​
Flow navigation does not work

For server-driven flows, check:
  • The config uses schemaVersion: 2 and type: "flow".
  • The destination route exists in the routes object.
  • The navigation URL is inside a valid flow route.
  • The app uses the current Swift SDK, React Native wrapper, or Flutter wrapper for its integration.
PNLight handles pnlight://navigation/... URLs inside flows before they reach onAction. Use app-specific URLs, action IDs, or action paths for actions the host app should handle.
Use debug mode or a test device while testing display rules. Turn debug mode off before production traffic unless your team intentionally needs it.