Configuration

config/ruby_native.yml is the whole native configuration. Your app fetches it as JSON from /native/config.json on every launch, so a change reaches a running app on its next start with no rebuild.

Setup walks through writing the file for the first time, and each feature page documents its own block in context. This page is the list of everything the file accepts, and of which mistakes stop the app from starting.

The file is evaluated as ERB before it is parsed, so a value can come from a Rails helper. The motivating case is the navigation bar logo, where image_url gives you a fingerprinted URL the app caches until the image changes. See Appearance.

#Top level

Key Configures See
app Launch URL and navigation mode Advanced Mode
appearance Colors, theme, orientation, bar branding, splash Appearance
tabs The native tab bar Tabs
auth OAuth authorize paths OAuth
errors The native error screen Error screen
analytics Whether the app reports its launch Setup
ios Bundle ID and team ID Linked domains
android Package name and signing certificate Linked domains
linked_paths Narrow universal links to some paths Linked domains
ruby_native Holds app_id, written by deploy CLI

Every block is optional. A key the app does not recognize is ignored, at this level and every level below it.

#app

Key Values Default
name Your app's name None
mode normal or advanced normal
entry_path The path the app opens on launch The first tab's path

#appearance

Key Values Default
tint_color A color The system tint
background_color A color White
theme auto, light, dark auto
landscape true or false false
navbar A block, below None
splash A block, below None
android Android-only bar colors. See Appearance None

A color is a six-digit hex string like "#007AFF", or a mapping with both light and dark for a per-theme pair. Three-digit shorthand does not work.

#appearance.navbar

Key Values
logo An image URL, shown instead of the page title
background_color A color
foreground_color A color
status_bar light or dark

#appearance.splash

Key Values Default
enabled true or false false
spinner_color A color Picked for contrast
status_bar light or dark Picked for contrast

#tabs

A list. Each entry:

Key Values Default
title The tab's label From key and your locale files
path Where the tab goes. Required None
icon An icon name. Required, unless icons is set None
icons ios: and android: icon names, when they differ None
key Names this tab's copy in your locale files None
eager Load on launch instead of on first visit false
search Show a search field in the navigation bar false
badge Allow a notification badge false
auto_route false, or a list of path prefixes that switch to this tab Prefix match on path

#auth

Key Values
oauth_paths A list of authorize paths, each triggering a native sign-in session

List only the authorize path for each provider. Callbacks are handled automatically, and a listed one is dropped.

#errors

Per-state icons for the native error screen: offline for no connectivity, generic for any other load failure. Each takes an icon, or icons with ios: and android:. The copy comes from your own locale files under ruby_native.errors.*, not from this file. See Error screen.

Key Sub-keys
ios bundle_id, team_id
android package, cert_fingerprint
linked_paths A list of path prefixes, when you do not want your whole domain linked

Your app serves /.well-known/apple-app-site-association only once both ios keys are set, and /.well-known/assetlinks.json only once both android keys are set.

#What breaks the app, and what is ignored

The app decodes this file into a fixed shape. Anything that does not fit stops the decode, and the user gets the error screen instead of your app on their next launch. It is reported to your dashboard, which Debugging covers.

These stop the app from starting:

  • A tab with no path, or with no icon and no icons
  • A theme that is not auto, light, or dark
  • A status_bar that is not light or dark
  • landscape, splash.enabled, or a tab's eager, search, or badge set to something other than true or false
  • auto_route: true, which is rejected outright. Use false, or a list of prefixes
  • A color that is neither a hex string nor a mapping, or a per-theme mapping missing light or dark

These are ignored, with nothing said anywhere:

  • Any key the app does not recognize, at any level
  • A mode that is not normal or advanced, which runs Normal Mode
  • A color that is not six hex digits, which falls back to the default
  • analytics set to anything other than true or false, including the string "false", which leaves reporting on
  • A tab with no title and no key, which renders as "Untitled"
  • Two tabs sharing a key, which then share their translations

A coding agent can check the file against all of this before a build. See validate_config.