Remote Config¶
Remote Config changes how the app looks and behaves without an App Store update: you publish values in the console, and the app reads them, with in-app defaults until the first fetch. Conditions target values by country, app version, user property, percentage of users (rollouts and A/B tests), or your own custom signals.
from pyios_firebase.remote_config import RemoteConfig
config = RemoteConfig.setup(defaults_plist="RemoteConfigDefaults", minimum_fetch_interval=3600)
if config.get_boolean("new_checkout"):
show_new_checkout()
title.text = config.get_string("welcome_message")
Installation¶
Add the FirebaseRemoteConfig Swift package product
(Installation). Remote Config uses
Firebase Installations, which needs the real API key from
GoogleService-Info.plist.
App configuration¶
What the app's build needs for this product. To combine several products, list
them all in one products; see App configuration.
[[tool.kivy.ios.include_files]]
dest = "."
sources = ["GoogleService-Info.plist"]
[tool.kivy.ios.native.swift_packages.Firebase]
url = "https://github.com/firebase/firebase-ios-sdk.git"
requirement = { from = "13.1.1" }
products = ["FirebaseRemoteConfig"]
[tool.kivy.ios.xcode.build_settings]
OTHER_LDFLAGS = "$(inherited) -ObjC"
# in-app defaults, read with defaults_plist="RemoteConfigDefaults"
[[tool.kivy.ios.include_files]]
dest = "."
sources = ["RemoteConfigDefaults.plist"]
- File > Add Package Dependencies...,
https://github.com/firebase/firebase-ios-sdk.git, and pickFirebaseRemoteConfig. - Build Settings > Other Linker Flags: add
-ObjC. - Add
GoogleService-Info.plistto the app target. - Add
RemoteConfigDefaults.plistto the app target (if you use a defaults plist).
How values flow¶
flowchart LR
D["In-app defaults"] --> A["Active values<br/>(what get_* returns)"]
S["Console"] -- "fetch" --> F["Fetched values"]
F -- "activate" --> A
The app always reads the active values. Fetching downloads new values without changing what the app sees; activating makes them active. That split lets you choose when the UI changes (at the next launch, or at once).
Set up¶
setup installs the defaults, then fetches and activates in the background:
config = RemoteConfig.setup(
defaults={"welcome_message": "Welcome", "max_items": 25}, # in code
defaults_plist="RemoteConfigDefaults", # RemoteConfigDefaults.plist in the app
defaults_file="remote_config_defaults.xml", # Android-format XML
minimum_fetch_interval=3600,
callback=lambda status, error: print("Remote Config:", status),
)
When several sources set the same key: defaults wins, then
defaults_file, then defaults_plist.
The defaults plist is a dictionary of keys to values: add
RemoteConfigDefaults.plist to the app bundle (kivyforge: include_files).
Download it from the console (Remote Config > ... > Download default
values) to start from what you published.
Read values¶
config.get_string("welcome_message") # "Welcome"
config.get_boolean("new_checkout") # True for "true", "1", "yes"...
config.get_number("discount") # 0.15
config.get_long("max_items") # 25
config.get_json("ui_theme") # a JSON string value, parsed
config.get_data("banner") # bytes
Missing keys give the type's empty value ("", False, 0). To know where a
value came from:
from pyios_firebase.remote_config import RemoteConfigSource
value = config.get_value("max_items")
value.string, value.number, value.boolean, value.json()
value.source # REMOTE, DEFAULT or STATIC (no value at all)
config.get_value("max_items", source=RemoteConfigSource.DEFAULT) # the default, whatever is active
config.all_keys(RemoteConfigSource.REMOTE)
config.keys_with_prefix("ui_")
Fetch and activate¶
def on_fetched(status, error):
# "success_fetched_from_remote", "success_using_pre_fetched_data" or "error"
if status != "error":
refresh_screen()
config.fetch_and_activate(on_fetched)
Or separately, to apply new values only at the next launch:
config.fetch() # at start-up: download for next time
config.activate() # at the next start-up, before reading
| Method | Callback |
|---|---|
fetch_and_activate(callback) |
(status, error), status a FetchStatus string |
fetch(callback, expiration_duration=) |
(RemoteConfigFetchStatus, error) |
activate(callback) |
(changed, error): whether any value changed |
ensure_initialized(callback) |
(error), once the values saved on the device are loaded |
last_fetch_time and last_fetch_status tell when and how the last fetch
went.
Throttling¶
Fetches are cached for minimum_fetch_interval seconds (12 hours by
default): fetching again sooner reuses the cache. Firebase also limits each
app to a few fetches an hour; past that, fetches fail with THROTTLED. Lower
the interval only while developing:
Real-time updates¶
Published changes reach the app within seconds while it runs:
def on_update(update, error):
if error is not None:
return
if "welcome_message" in update.updated_keys:
config.activate(lambda changed, error: refresh_screen())
listener = config.add_on_config_update_listener(on_update)
...
listener.remove()
The listener only says what changed; call activate to use the new values.
Custom signals¶
Target conditions at your own attributes, set from the app:
Values are str, int or float (not bool: use "true" / "false" or
1 / 0). In the console, add a condition Custom signal: plan == pro.
Errors¶
RemoteConfigErrorCode |
Means |
|---|---|
THROTTLED |
Too many fetches: the cached values are still used |
UNKNOWN |
The fetch failed (offline, or a bad configuration) |
INTERNAL_ERROR |
The server failed |
A failed fetch is not fatal: the app keeps the active values (the defaults at first). Show the defaults rather than an error.
Development¶
Remote Config has no emulator. Develop with the in-app defaults, and against
a real project with minimum_fetch_interval = 0.
A/B testing, personalization, rollouts¶
Set them up in the console. The app only reads values: nothing to change in the code.