Branding a tenancy
In the portal: Settings, then Configurations.
What it is
A tenancy is one customer's own space in the platform, with its own participants, its own content, its own colours and its own sign-up link. Most apps hold one. If your app covers several clinics or employers, give a tenancy to each one that needs its own look. The rest become cohorts, and a cohort uses the branding of the tenancy it sits in.
You set branding on a tenancy. A cohort cannot have its own. So branding is part of deciding which of the two a new clinic or employer gets. If it needs its own logo, colours or tab names, it needs a tenancy. If it needs only its own sign-up link and its own starting journeys, a cohort is enough. Most groups need only a cohort. Standing up a tenancy has the full table.
Your customer will have their own word for a tenancy: clinic, employer, practice, school or region. Use their word when you are talking to them. Use "tenancy" when you are in the portal, because that is the word on the screens.
Everything you can brand is set per tenancy: the colours and shapes, the pictures, four pieces of copy, five information pages, the rows in the Settings screen, the credit on the co-branding bar, and whether Android may use the phone's own wallpaper colours.
You can change all of these on an app that is already installed. No app-store release is needed. If the app is open, the change lands within seconds. If it is closed, it lands the next time the app syncs. So you can correct a colour, a logo, a piece of copy or a whole legal page in the afternoon, and every participant has it on their phone the same day.
Make colour changes when nobody is mid-demonstration, because an open app will repaint while they are watching it.
Four things are not on this page. The typeface, the app icon, the app's name and the sign-in screen are all decided when the app is built. The app's own brand covers them. Read that page before you commission any design work, because changing any of those four needs a new version of the app rather than a change in the portal.
Where to find each setting
Each setting is a row in Settings, then Configurations. Type the setting's name,
for example theme.tokens, into the search box to find its row.
| Setting | What it holds |
|---|---|
theme.tokens | Colours, corner rounding, text size, the logo and the sign-in picture |
branding.strings | Four pieces of copy |
content.pages | Five information pages, written in markdown |
settings.links | The rows in the Settings screen |
branding.attribution | The credit on the co-branding bar, naming whose app this is |
theme.material_you_enabled | Whether Android may take its colours from the phone's wallpaper instead of yours |
How to edit a setting
Click the row to open the editor. A setting that holds only true or false gives you a tick box. Every other setting gives you a box of JSON to edit by hand. There is no form behind it.
Do these three things every time.
Copy the old value out before you change anything. The box holds the whole setting. What you save replaces everything that was in it, so paste the whole value back, including the colours you are not changing.
Change one thing at a time and look at a phone. If the whole value is not valid JSON, the portal refuses to save it. If one field name inside it is misspelt, the platform uses its built-in default for that field and saves the rest, so nothing on screen changes and nothing warns you. When a change does not show up, check the spelling of the field name first.
Keep each setting under 64 KB. Real settings are far smaller than that. If yours is getting close, you have probably pasted a picture in as text instead of uploading it to the media library.
What a setting actually looks like
Here is a whole theme.tokens value, with the parts described below it. This is the
shape you are editing, and the shape you paste back.
{
"version": 1,
"colors": {
"light": {
"primary": "#1F6FEB",
"onPrimary": "#FFFFFF",
"brand": "#0F2664",
"onBrand": "#FFFFFF",
"accent": "#5FD4E0",
"background": "#E6E8EA",
"surface": "#FFFFFF",
"onSurface": "#1D252D",
"surfaceVariant": "#EFF2FC",
"onSurfaceVariant": "#53565A",
"outline": "#BBBCBC",
"error": "#F65275"
},
"dark": {}
},
"typography": { "scale": 1 },
"shape": { "radiusSmall": 8, "radiusMedium": 12, "radiusLarge": 20 },
"images": { "logoAssetId": "0b6f2c14-9e3a-4d51-b8c7-2f5e91a4d033" }
}
Three things to notice before you edit one.
The twelve colours sit inside colors.light, not at the top level. Check the
nesting before you save.
Leave colors.dark empty. Both phones use the light palette whatever the phone
is set to, so anything you put in dark is never drawn.
You can leave out anything you are not setting. A field you omit keeps its built-in default. What you must not do is leave out a field you meant to keep, because saving replaces the whole value.
Colours
There are twelve colour roles, and this is the complete list. Together they are the app's whole palette.
| Role | Where it shows |
|---|---|
primary | The main action colour |
onPrimary | Text and icons drawn on primary |
brand | The home header strip and the bottom bar |
onBrand | Text and icons drawn on brand |
accent | Highlights, the selected tab, the home header button |
background | The page behind the content |
surface | The card colour |
onSurface | Text on a card |
surfaceVariant | A second, quieter card colour |
onSurfaceVariant | Text on that quieter colour |
outline | Hairlines and borders |
error | Error text and error states |
Write every colour as #RRGGBB, or #RRGGBBAA when you want transparency.
Those are the only two forms the apps read. If you write a colour any other way, such
as the word red, that role falls back to its built-in colour.
Colours are held in two blocks, light and dark.
Keep brand and accent visibly different from each other. The button in the home
header draws accent behind and brand on top. If those two colours are close to each
other, the button is hard to see, so check this pair on a phone.
Two other places handle this for you. The selected tab and the small credit chips on
cards compare accent with the colour behind them, and switch to primary when the
two are too close. You do not need to check those.
iPhone and Android both use the light palette, whatever the phone's own dark-mode
setting says. So spend your design time on the light block.
Build the palette on primary, brand and accent, because those three reach the
screen on both phones. iPhone draws background, surface, onSurface,
surfaceVariant and outline with its own system materials, so those five show on
Android only. Look at any tinted card design on an iPhone and an Android phone before
you commit to it.
Some colours are fixed and you cannot change them, so that a warning always looks like a warning: the sync status colours, success and warning, the tones on an insight card, the breathing feedback, and the chart series.
Your colours also change the portal. The portal uses primary and accent from
whichever tenancy you are working in. A very pale primary makes the portal harder to
read, so check it on your own staff's screens as well as on a phone.
Shape and text size
| Field | What it accepts | Default | What changes on screen |
|---|---|---|---|
shape.radiusSmall | 0 to 32 | 8 | Corner rounding on small controls |
shape.radiusMedium | 0 to 32 | 12 | Corner rounding on cards |
shape.radiusLarge | 0 to 32 | 20 | Corner rounding on sheets and large panels |
typography.scale | 0.85 to 1.3 | 1 | Multiplies every text size in the app |
shape.spacingUnit | 4 to 12 | 8 | Nothing on screen. See below |
typography.fontFamily | text | none | Nothing on screen. The typeface comes from the app build. See below |
If you type a number outside the range, the platform uses the nearest number in the
range. radiusLarge: 60 gives you 32.
Leave spacingUnit at its default of 8. Spacing comes from the app's own
layout. If you want a roomier or tighter screen, use typography.scale.
The typeface comes from the font files built into the app, not from fontFamily.
fontFamily records the name of the typeface for your own reference, and nothing
else. To give a tenancy its own typeface, send us the font files and we build a new
version of the app. See the app's own brand.
Three things you can skip
Skip these three and spend your design time on the settings that show on screen.
| Setting | Where | What to do instead |
|---|---|---|
typography.fontFamily | theme.tokens | The typeface is built into the app. A tenancy that wants its own face supplies the font files and gets a build: see the app's own brand. |
shape.spacingUnit | theme.tokens | Leave it at its default. Neither phone spaces anything by it. |
the whole dark colour block | theme.tokens | Spend the design time on light. Both phones render the light palette, whatever the phone's own setting says. |
Pictures
theme.tokens holds two pictures:
| Field | What it is |
|---|---|
images.logoAssetId | The brand mark on the sign-in screen and the home co-branding strip |
images.loginHeroAssetId | A picture above the sign-in form. Leave it out and the sign-in form has no picture above it |
Both fields name an item in the media library, and that item must be public. If a picture does not appear, check that first.
One more logo is set outside this page. The tenancy record has its own Logo field, filled in on the tenancy form. That logo shows on the sign-up page people reach through your sign-up link, and it is the small picture beside the tenancy's name in the portal's tenancy switcher. Filling in one of these two logos does not fill in the other. If a customer tells you the logo is missing, ask which screen they were looking at.
The four pieces of copy
branding.strings holds exactly four keys, and this is all of them.
| Key | Default | Where it shows |
|---|---|---|
coachTitle | Coach | What an unnamed staff member is called in a chat |
aiCoachName | AI Coach | The title of the assistant chat |
tagline | Your digital health, coaching and wellness platform. | Under the logo on both sign-in screens |
appGreeting | Good morning, Good afternoon or Good evening by the hour | The greeting at the top of the home screen |
Each of the four is capped at 80 characters, and spaces at either end are removed.
If you set appGreeting, participants see your line at every hour of the day instead
of Good morning, Good afternoon and Good evening.
The five information pages
content.pages holds five markdown bodies: consent, privacyPolicy, terms,
about and helplines. Each page can run to 32,768 characters, which is long
enough for a full white-label terms document.
A page longer than that does not get cut short. The app treats it as empty and drops its row from the Settings screen. So if your terms document grows past the limit, its row disappears from the phone. If a page you have filled in has no row on the phone, check its length first.
consent is the screen shown straight after sign-in, before the app opens. It is
the only one of the five a participant cannot skip, and the only one that is not a
row. The sign-in screen itself shows your logo, your tagline and the sign-in fields,
and nothing else.
The other four are rows in the Settings screen, under About, in a fixed order: privacy policy, terms, about, then helplines. Leave a page empty and its row does not appear, which is how you hide one you do not need.
The row titles are fixed, and they are in English. The pages themselves are drawn in your tenancy's colours and typeface, from the markdown you write. You supply the words.
The rows in the Settings screen
settings.links puts a section headed Services into the Settings screen, between
About and Privacy. It takes up to twelve rows. Each row is one of three kinds:
| Kind | What tapping it does |
|---|---|
booking | Opens a booking flow for this tenancy, signed in |
web | Opens a web address. It must begin https:// |
phone | Opens the phone's dialler |
Leave the list empty and the Services section does not appear.
You can put a list of group codes on any row. Only participants in one of those groups then see that row. A row with no group codes is shown to everyone. This is how you keep a helpline meant for one cohort off everybody else's screen. The platform removes the rows a participant should not see before it sends the list, so their phone never receives them.
The co-branding bar
The bar under the greeting on the home screen carries two names, and neither of them is Intervengine's.
The left side shows the tenancy. It draws the logo from images.logoAssetId at 32
by 32 pixels on a white tile, and beside it the tenancy's name, spelt exactly as the
tenancy record spells it. This is the clinic, employer or practice the participant
belongs to.
The right side shows the credit. branding.attribution holds a label and an
optional logoAssetId. Write the label as By and the name of whoever the app
belongs to. This tells a participant whose app they are in.
| Field | What it holds |
|---|---|
label | The line on the right of the bar. Written as By <name> |
logoAssetId | An optional small mark beside that line, at 24 by 24 |
Leave branding.attribution empty and the bar does not appear. Do that when only
one brand is involved. The header already carries the tenancy's colours, and there is
no second brand to name.
The bar scrolls away with the content. It sits in the feed rather than staying pinned to the header.
A tenancy with no branding.attribution of its own uses the one set on the default
tenancy. So for an app that runs many clinics, you set the credit once instead of
setting it on every clinic.
What you can now do
You can now change how the app looks and reads for one tenancy, from the portal, and see it on a phone the same day. You control the twelve colours, the two pictures, the four pieces of copy, the five information pages, the rows in the Settings screen and the co-branding credit, and none of them needs an app-store release.
Adding another branded clinic or employer means changing a handful of colours. Of the two apps running live today, one tenancy sets three of the twelve colours and the other sets four. Leave the rest at their defaults. Those defaults are what make a card read as a card and a warning read as a warning.
Before you commission any design work, read the app's own brand and settle the typeface and the app icon. Those two need a new version of the app, so they take much longer than a change in the portal.