> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pnlight.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Remote UI

> Render PNLight Remote UI placements such as paywalls and onboarding screens in your iOS, React Native, or Flutter app and handle user actions.

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](/dashboard/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.

<CodeGroup>
  ```swift SwiftUI theme={null}
  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()
              }
          }
      }
  }
  ```

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

  ```dart Flutter theme={null}
  RemoteUiView(
    placement: 'paywall',
    cardId: 'paywall_card',
    onAction: (event) async {
      if (event.path == 'purchase') {
        final success = await startPurchase(event.params['id']);
        if (success) {
          openMainScreen();
        }
      }
    },
  )
  ```
</CodeGroup>

## 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.

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

## 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`.

<CodeGroup>
  ```swift Swift theme={null}
  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
  )
  ```

  ```tsx React Native theme={null}
  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);
  ```

  ```dart Flutter theme={null}
  await Future<void>.delayed(const Duration(seconds: 5));

  final config = await PNLightSDK.getUIConfig('paywall');
  final freshConfig = await PNLightSDK.getUIConfig(
    'paywall',
    ignoreCache: true,
  );
  ```
</CodeGroup>

## 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:

```swift theme={null}
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](/dashboard/remote-ui-placements) for the dashboard workflow.