Remote UI

PNLight Remote UI lets your app render screens configured in the dashboard. Use it for paywalls, prompts, upgrade screens, and other app surfaces that you want to update without a new app release.

How Remote UI is selected

The app requests a placement with a locale and user ID. PNLight returns a config from the matching dashboard placement when the placement is enabled and a matching config is available. Create every placement that your app can request in Remote UI. On a fresh fetch from PNLight (for example, when you pass ignoreCache), if the placement is missing, disabled, deleted, or missing a usable locale config, PNLight returns no UI for that request. The dashboard tracks:

Requests: users who requested the placement.
Shown: users who received a UI config that could be shown.

PNLight can also apply targeting, show-once rules, capture protection, and runtime placeholder resolution before it returns a config. See Remote UI placements for the dashboard controls. Runtime placeholders are resolved on the server. The SDK receives the final config values, such as product IDs, after PNLight replaces tokens like {{monthlyProductId}}.

Render a placement

RemoteUiView calls getUIConfig internally. On the first app launch, when you use attribution from AppsFlyer, wait 4-5 seconds after AppsFlyer initialization before showing the placement so conversion data has time to arrive. When attributionRequired is true, the SDK also waits for attribution internally before requesting the config.

RemoteUiView(placement: "paywall", cardId: "paywall_card") { action in
    if action.logId == "purchase_button" {
        let productId = action.params["id"] ?? ""
        Task {
            let success = await purchase(productId)
            if success {
                showMainScreen()
            }
        }
    }
}

<RemoteUiView
  placement="paywall"
  cardId="paywall_card"
  style={{ flex: 1 }}
  onAction={(event) => {
    if (event.logId === "purchase_button") {
      startPurchase(event.params.id).then(() => {
        navigation.navigate("Main");
      });
    }
  }}
/>

RemoteUiView(
  placement: 'paywall',
  cardId: 'paywall_card',
  onAction: (event) async {
    if (event.path == 'purchase') {
      final success = await startPurchase(event.params['id']);
      if (success) {
        openMainScreen();
      }
    }
  },
)

Remote UI components

Use Remote UI components to add PNLight components to a config and review their properties.

Handle actions

Remote UI actions are delivered to your app. Use action IDs, paths, or query parameters to decide what the app should do. Different placements can return different actions, so keep the handler explicit. Common actions:

Start a purchase.
Return the user to the main app screen after a successful subscription.
Close the screen.
Open another app screen.
Track a product interaction.

Always handle unknown actions. A safe fallback is to close the Remote UI screen or ignore the action.

Fetch configs manually

Use getUIConfig if you need to fetch the placement configuration yourself. On the first app launch, when attribution is required, call it after sending attribution and wait 4-5 seconds after AppsFlyer initialization before requesting the config. The SDK still waits for attribution internally when attributionRequired is true.

try? await Task.sleep(nanoseconds: 5_000_000_000)

let config = await PNLightSDK.shared.getUIConfig(placement: "paywall")
let freshConfig = await PNLightSDK.shared.getUIConfig(
    placement: "paywall",
    ignoreCache: true
)

import { getUIConfig } from "@pnlight/sdk-react-native";

await new Promise((resolve) => setTimeout(resolve, 5000));

const config = await getUIConfig("paywall");
const freshConfig = await getUIConfig("paywall", true, true);

await Future<void>.delayed(const Duration(seconds: 5));

final config = await PNLightSDK.getUIConfig('paywall');
final freshConfig = await PNLightSDK.getUIConfig(
  'paywall',
  ignoreCache: true,
);

Config cache behavior

Remote UI configs are cache-first by default. If a cached config exists, the SDK can return it immediately and refresh it in the background with an ETag request. This keeps repeat displays responsive while still picking up dashboard changes. Use ignoreCache when the app must wait for the latest server response, such as during QA or after the user changes a state that should affect targeting.

Handle missing configs and errors

On a fresh fetch from PNLight, a null or empty config means PNLight did not return UI for that placement. This can happen when the placement does not exist in Remote UI, the placement is disabled, targeting does not match, show-once rules suppress the placement, capture protection blocks the user, no matching locale config exists, or a runtime placeholder cannot be resolved. React Native and Flutter wrappers surface loading errors separately from missing UI. Use onError on RemoteUiView or handle getUIConfig errors when you fetch manually. Swift apps that fetch manually can use getUIConfigResult to distinguish all outcomes:

let result = await PNLightSDK.shared.getUIConfigResult(placement: "paywall")

switch result {
case .success(let config?):
    render(config)
case .success(nil):
    showLocalFallback()
case .failure:
    showErrorFallback()
}

Dashboard setup

Create and manage placements in Remote UI. See Remote UI placements for the dashboard workflow.

Start here

SDK integration

Dashboard

Troubleshooting

Changelog

How Remote UI is selected

Render a placement

Remote UI components

Handle actions

Fetch configs manually

Config cache behavior

Handle missing configs and errors

Dashboard setup

​How Remote UI is selected

​Render a placement

​Remote UI components

​Handle actions

​Fetch configs manually

​Config cache behavior

​Handle missing configs and errors

​Dashboard setup

How Remote UI is selected

Render a placement

Remote UI components

Handle actions

Fetch configs manually

Config cache behavior

Handle missing configs and errors

Dashboard setup