Skip to content
AppDues
Log in
Contact salesSign up

Personalize React Native Paywalls with Custom Variables

A paywall that greets a customer by name feels less like a generic gate and more like part of the product. Custom Variables let a React Native app send a value — a first name, a usage figure, a plan label — into a paywall built in the Paywall Editor. The editor owns the layout and a required fallback; the app owns the live value. This guide walks through the tipping example: a generic title becomes a personalized one, with a safe default if the name is unavailable.

What you need before you start

You need a React Native app that already presents a paywall, plus the Paywall Editor in the dashboard. Custom Variables are version-gated, so confirm the installed package meets the minimum below. The table is the reference for the versions that support the feature; check the linked release pages for the current state of each package.

[TABLE:table0001]

If your app is not React Native, the same concept applies but the call signature differs — use the platform-specific Custom Variables documentation rather than adapting the React Native snippet below.

The example: a tipping paywall

The demo app has a single action, a “Tip the developer” button. Tapping it opens a paywall configured in the editor. The starting title is deliberately generic — it addresses “You” rather than a named person. The goal is to replace that word with the customer’s actual name while keeping the sentence readable when no name is available.

That last point drives the design: personalization is an enhancement, not a dependency. The paywall must still render correctly for a signed-out user, a new account, or a value that never arrives.

Define the variable and its fallback

Open the Paywall Editor in your dashboard and go to the Variables section in the left sidebar. The “Create variable” button starts a new definition. Name it for the data it carries — in the example, customerName — because the app will later send a key with exactly that spelling.

A default value is mandatory. Treat it as part of the copy, not an afterthought: it is what every customer sees when the live value is missing. The example uses “You”, which keeps the title grammatical in both states. A blank or placeholder default would produce a broken-looking sentence, so choose a word that reads naturally on its own.

Insert the variable into a text layer

Return to the Layers view, select the title text layer, and place the cursor where the name should appear. Use the “Add variable” button to insert customerName in place of the static word. The layer now contains a reference rather than fixed text, so the same layout serves every customer.

Preview the result with the default value before publishing. Once the paywall looks right in both the fallback and a sample-name state, publish the changes so the app can fetch the updated version.

Pass the value from React Native

On the app side, presentPaywall accepts a customVariables key. It is an object whose keys are the variable names defined in the editor and whose values are wrapped in CustomVariableValue.string. The value can come from your user profile, authentication state, or wherever customer data lives.

The important contract is the name match: the key sent from the app must equal the variable defined in the editor. The default value keeps the paywall readable whenever the variable is not set. The exact call shape is preserved in the code module below.

[CODE:code0001]

Verify the personalized result

Save the app change and force a refresh so the client pulls the latest paywall version. Open the paywall through the tip button: the title should now show the supplied name. Then test the fallback path by presenting the paywall without the variable, or with a deliberately different key, and confirm the default word still reads well.

That two-state check is the real acceptance test. A personalized title that only works when data is present is fragile; a title that degrades gracefully is shippable.

Editor-to-code field map

Use this map when wiring a new variable, since three places must agree:

  • Editor variable name → the key in the app call. Example: customerName.
  • Editor default value → the text shown when no value is passed. Example: “You”.
  • Text layer placeholder → where the variable is inserted in the paywall copy.
  • App value → wrapped with CustomVariableValue.string and sent through customVariables in presentPaywall.

A quick checklist before publishing: the key spelling matches exactly; the default produces a complete sentence; the layer preview shows both states; the installed SDK meets the minimum version.

Three different failures, three different fixes

When the name does not appear, the cause is usually one of three things, and they are not interchangeable:

  1. No value sent. The app presented the paywall without customVariables. The default shows by design. Fix: pass the value at the call site.
  2. Key mismatch. A value was sent, but its key differs from the editor variable name. The default shows because nothing matched. Fix: align the spelling in both places.
  3. Stale paywall. The editor change was published, but the app is showing a cached version. Fix: force a refresh so the latest paywall is fetched.

Separating these keeps debugging short: check what was sent, then check the name, then check the version.

Beyond names: other useful values

A name is the simplest case, but the same mechanism carries any string the paywall copy can use. Consider a plan label, a streak count, a usage total, or a status word. The constraint is editorial: the default must still make sense for a customer who has none of that data, and the sentence must not depend on a specific value to be grammatical.

Keep the set small and purposeful. Each variable is another place where editor and app must agree, so add one only when it changes what the customer reads in a meaningful way.

Minimum SDK versions for Custom Variables
SDKMinimum version
purchases-ios5.57.0
purchases-android9.21.0
react-native-purchases9.10.0
purchases-flutter9.12.0

Version requirements as published with the original guide; confirm against the linked release pages before upgrading.

Frequently asked questions

Why does the editor require a default value?

The default is the fallback shown whenever the app does not supply a value — for example, a signed-out user or a missing key. It keeps the paywall copy complete and readable instead of leaving a gap in the sentence.

What happens if the app key does not match the editor variable name?

The key sent from the app must match the variable name defined in the editor. When the variable is not set, the default value keeps the paywall copy readable. Align the spelling in both places so the value is applied.

Can I pass numbers or other types?

The React Native example wraps the value with CustomVariableValue.string, so the payload is a string. Format numbers or statuses as strings before passing them, and make sure the default reads correctly for that format.

Does this work outside React Native?

Yes, the concept is platform-independent, but the call signature differs. Use the platform-specific Custom Variables documentation for iOS, Android, or Flutter rather than adapting the React Native snippet.

SDKMimimum version
purchases-ios5.57.0
purchases-android9.21.0
react-native-purchases9.10.0
purchases-flutter9.12.0