Skip to main content
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 when the placement is enabled and a matching config is available. 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, and capture protection before it returns a config. See Remote UI placements for the dashboard controls.

​
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();
      }
    }
  },
)

​
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

A null or empty config means PNLight did not return UI for that placement. This can happen when the placement is disabled, targeting does not match, show-once rules suppress the placement, capture protection blocks the user, or no matching locale config exists. 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.