Screen schema

A referral screen is a small JSON document. You normally build it in the dashboard editor, but you can also create and publish screens through the API. Every ReferralPanda SDK draws the same document the same way.

{
  "schemaVersion": 1,
  "defaultLocale": "en",
  "strings": {
    "en": {
      "title": "Give a friend {{reward.referee.label}}",
      "share": "Share your link"
    },
    "es": { "title": "Regala {{reward.referee.label}}" }
  },
  "theme": {
    "colors": {
      "background": { "light": "#FFFFFF", "dark": "#0A0A0A" },
      "surface":    { "light": "#F5F5F5", "dark": "#171717" },
      "text":       { "light": "#0A0A0A", "dark": "#FAFAFA" },
      "muted":      { "light": "#666666", "dark": "#A3A3A3" },
      "primary":    { "light": "#0A0A0A", "dark": "#FAFAFA" },
      "on_primary": { "light": "#FFFFFF", "dark": "#0A0A0A" },
      "border":     { "light": "#E5E5E5", "dark": "#262626" },
      "success":    { "light": "#15803D", "dark": "#4ADE80" }
    },
    "radius": 16
  },
  "root": {
    "type": "scroll",
    "children": [
      { "type": "text", "text": "title", "style": "title" },
      { "type": "code_box" },
      { "type": "share_button", "label": "share" }
    ]
  }
}

Components

`stack`	Lays children out in a column or a row, with spacing, padding and alignment.
`scroll`	A scrolling column. Only as the root of a screen.
`card`	A rounded surface around its children.
`spacer`	Empty space from the spacing scale.
`text`	A string, as a title, heading, body or caption.
`image`	An uploaded image, with an aspect ratio and fit.
`lottie`	An uploaded Lottie animation.
`icon`	One of 16 built-in icons.
`code_box`	The person's referral code. Tap to copy.
`share_button`	Opens the share sheet, or one channel directly.
`channel_row`	A row of share channels: Messages, WhatsApp, copy link, more.
`progress`	Milestones against a stat, for example "3 friends unlocks a free year".
`reward_list`	The person's rewards, pending and issued.
`stats_row`	Up to four numbers: total, pending, qualified, rewarded.
`redeem_code_input`	A field to enter a friend's code.
`offer_code_redeem_button`	iOS only. Opens Apple's sheet for an offer code the person earned.

Strings and translation

Text is never written on a component. A component names a key, and strings holds the text for each locale. The default locale must have every key. Other locales can be partial: a missing string falls back to the same language without a region (pt-BR to pt), then to the default locale.

Tokens

Strings can include these values. A token that is not in this list is refused when you save, and a token with no value is left out, so braces never reach your users.

`{{referral.code}}`	The person's code.
`{{referral.link}}`	The person's share link.
`{{stats.total}}`	Friends they have referred.
`{{stats.pending}}`	Referrals that have not qualified yet.
`{{stats.qualified}}`	Referrals that qualified.
`{{stats.rewarded}}`	Referrals they were rewarded for.
`{{reward.referrer.label}}`	What the referrer gets, from your program.
`{{reward.referee.label}}`	What the friend gets, from your program.
`{{referrer.first_name}}`	First name of whoever invited them, if your app set it.
`{{program.name}}`	The name of your active program.

Theme

Eight named colors, each with a light and a dark value, a corner radius, and a font (system, or one you upload). Components refer to colors by name, so changing the theme restyles the whole screen and dark mode always works.

Images, animations and fonts

Upload them in the dashboard and refer to them as asset:<id>. A screen cannot load a file from any other address.

Limits

200 components, nested at most 12 levels deep.
100 strings per locale, each up to 500 characters. Up to 40 locales.
64 KB per screen.

Draft, publish, roll back

Saving creates a draft and changes nothing for your users. Publishing replaces the live version in one step, and apps pick it up within a minute. Rolling back publishes a copy of an earlier version, so your history stays intact. A placement, for example settings_referral, is the name your app asks for, and you choose which screen it shows.

The editor

You do not have to write any of this by hand. In the dashboard, open your project and choose Screens. Start from a template, select a component in the list on the left, and change it on the right. The preview in the middle is the same renderer your app uses, shown with sample values, on an iPhone or a Pixel, in light or dark.

Changes save to a draft as you make them. If something is not valid, the editor says what and where, and that draft cannot be published until it is fixed. Text fields edit the default language for now. Owners, admins and developers can edit. Viewers can look.

Preview on a device

To see a draft on a phone before you publish it, press Preview on device in the editor and scan the code with a phone that has the ReferralPanda Playground app. The phone shows the newest version of the screen with sample data, and follows your edits within a few seconds. Nothing reaches your users until you publish.

The code works for about an hour and opens that one screen only. Anyone on your team who can see the screen can make one. For now the Playground app is a development build from our repository; it will be in the App Store and Google Play later.