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

> Create and manage PNLight Remote UI placements, configure per-locale variants, add runtime placeholders, set display rules, and control how remote screens appear in your app.

A Remote UI placement is a named app location where PNLight can return remote screens.

The placement in **Remote UI** is the source of truth for SDK requests. On a fresh fetch, if the app requests a placement that does not exist, is disabled, or has no usable locale config, PNLight returns no UI for that request.

## Create or edit a placement

<Steps>
  <Step title="Open Remote UI">
    Select the project and open **Remote UI**.
  </Step>

  <Step title="Choose a placement">
    Open an existing placement or create one with a stable placement ID such as `paywall`.
  </Step>

  <Step title="Name the placement">
    Use a readable name that dashboard users can recognize.
  </Step>

  <Step title="Add locale configs">
    Add JSON configs for the locales your app requests, such as `en` or `en-US`.
  </Step>

  <Step title="Add runtime placeholders">
    Define reusable values when the same JSON should use project-specific strings or product IDs.
  </Step>

  <Step title="Enable the placement">
    Turn on the placement when it is ready for app traffic.
  </Step>
</Steps>

## Placement controls

| Control                 | Use                                                                      |
| ----------------------- | ------------------------------------------------------------------------ |
| Enabled                 | Allows the placement to return configs to the SDK.                       |
| Debug                   | Lets you test the placement without the normal production display rules. |
| Show only once per user | Prevents the same user from seeing the placement repeatedly.             |
| Protection mode         | Controls secure rendering and capture handling for the placement.        |
| Default locale          | Fallback locale used when the requested locale does not have a config.   |

## Preview and validate a config

Use the editor preview before you enable a placement.

* Select a locale to edit its JSON config.
* Review the live preview next to the editor.
* Switch device presets to check common iPhone sizes.
* Use the preview event log to confirm render, click, and custom action callbacks.
* Fix validation messages before you save.

The preview is a dashboard validation tool. Always test the placement in your app before shipping a release.

## Runtime placeholders

Runtime placeholders let you reuse one JSON config while PNLight fills values before the SDK receives it. Insert a token in any JSON string value with `{{key}}`.

Placeholder keys must start with a letter. They can contain letters, numbers, and underscores.

| Source  | Use                                                                                   |
| ------- | ------------------------------------------------------------------------------------- |
| Literal | Replaces the token with a saved string value.                                         |
| Product | Replaces the token with an App Store product ID from [Products](/dashboard/products). |

For example, define a product placeholder with the key `monthlyProductId`. Then use `{{monthlyProductId}}` in a button action parameter.

<Warning>
  If a placement references a placeholder that cannot be resolved, PNLight does not return that config to the SDK. Check that every token has a matching placeholder and that product placeholders point to existing products.
</Warning>

### Protection modes

| Mode                           | Use                                                                                             |
| ------------------------------ | ----------------------------------------------------------------------------------------------- |
| Off                            | Do not apply Remote UI capture protection.                                                      |
| Secure only                    | Render the placement in secure mode when supported by the SDK wrapper.                          |
| Secure and block after capture | Render in secure mode and stop returning the placement after capture is detected for that user. |

## Targeting conditions

Targeting conditions restrict a placement to matching users. Add conditions when a placement should appear only for specific campaigns, devices, countries, or SDK versions.

Available fields:

* Ad campaign.
* Device family.
* Device model name.
* OS version.
* IP country.
* Store country.
* SDK version.

Each condition can include or exclude values. Numeric or version-like fields can also use greater-than-or-equal and less-than-or-equal modes.

<Tip>
  Use **Debug enabled** or a test device when you need to verify a placement before the targeting conditions are ready for production.
</Tip>

## Metrics

| Metric   | Meaning                                          |
| -------- | ------------------------------------------------ |
| Requests | Users who requested the placement.               |
| Shown    | Users who received a config that could be shown. |

For a time-series view of these metrics per placement, see [Remote UI analytics](/dashboard/analytics#remote-ui-analytics).

<Tip>
  Keep placement IDs stable. Changing a placement ID requires an app code change.
</Tip>

<Warning>
  Deleting a placement stops fresh SDK requests for that placement from returning UI. Disable the placement when you want to pause it without removing its setup.
</Warning>