Remote Config reference¶
At a glance¶
RemoteConfig.remote_config(),RemoteConfig.setup(defaults, defaults_file, defaults_plist, minimum_fetch_interval, callback)- Settings:
minimum_fetch_interval,fetch_timeout,last_fetch_time,last_fetch_status - Defaults:
set_defaults(dict),set_defaults_from_plist(name),default_value(key),load_defaults(path),load_plist_defaults(name) - Fetch:
ensure_initialized(cb),fetch(cb, expiration_duration),activate(cb),fetch_and_activate(cb) - Values:
get_value(key, source)→RemoteConfigValue(string,number,boolean,data,source,json());get_string,get_boolean,get_number,get_long,get_data,get_json;all_keys(source),keys_with_prefix(prefix) - Real-time:
add_on_config_update_listener(listener)→ConfigUpdateListener(remove());ConfigUpdate.updated_keys set_custom_signals(signals, cb);RemoteConfigSource,RemoteConfigFetchStatus,RemoteConfigErrorCode
pyios_firebase.remote_config¶
Firebase Remote Config: change your app's behavior without an update.
from pyios_firebase.remote_config import RemoteConfig
config = RemoteConfig.setup(defaults_plist="RemoteConfigDefaults") # once, at app start
config.get_string("welcome_message")
# real-time updates: activate new values as soon as they are published
config.add_on_config_update_listener(
lambda update, error: config.activate() if update else None
)
The get_* methods never wait for the network: they answer from the last
activated values, then the in-app defaults, then an empty value.
In-app defaults can come from any mix of:
- a
.plistfile in the app bundle (defaults_plist=), the usual iOS way - a dict (
defaults=) - an Android-format
remote_config_defaults.xmlfile (defaults_file=), for teams that share one defaults file with an Android app
Needs the FirebaseRemoteConfig framework.
Classes:
| Name | Description |
|---|---|
RemoteConfigSource |
Where a value comes from ( |
RemoteConfigFetchStatus |
|
RemoteConfigErrorCode |
The |
RemoteConfigValue |
One parameter's value, read in every type at once. |
ConfigUpdate |
What a real-time update changed. |
ConfigUpdateListener |
Given back by |
RemoteConfig |
The app's Remote Config. Get it with |
Functions:
| Name | Description |
|---|---|
load_defaults |
Read an Android-format defaults XML file into a dict. |
load_plist_defaults |
Read a dictionary plist from the app bundle into a dict. |
Attributes:
| Name | Type | Description |
|---|---|---|
REMOTE_CONFIG_ERROR_DOMAIN |
Final
|
The |
FetchStatus |
The result of |
|
FetchCallback |
|
|
ActivateCallback |
|
|
STATUS_NAMES |
Final[dict[int, FetchStatus]]
|
|
REMOTE_CONFIG_ERROR_DOMAIN
module-attribute
¶
The error.domain of fetch and activate errors.
FetchStatus
module-attribute
¶
The result of fetch_and_activate.
FetchCallback
module-attribute
¶
FetchCallback = Callable[
[FetchStatus, FirebaseError | None], None
]
(status, error) for fetch_and_activate.
ActivateCallback
module-attribute
¶
ActivateCallback = Callable[
[bool, FirebaseError | None], None
]
(changed, error): whether activating changed any value, and the error.
STATUS_NAMES
module-attribute
¶
STATUS_NAMES: Final[dict[int, FetchStatus]] = {
0: "success_fetched_from_remote",
1: "success_using_pre_fetched_data",
2: "error",
}
FIRRemoteConfigFetchAndActivateStatus values, by number.
RemoteConfigSource
¶
RemoteConfigFetchStatus
¶
RemoteConfigErrorCode
¶
RemoteConfigValue
dataclass
¶
One parameter's value, read in every type at once.
Methods:
| Name | Description |
|---|---|
from_native |
Copy a native |
json |
The value parsed as JSON, or |
Attributes:
| Name | Type | Description |
|---|---|---|
string |
str
|
The value as a string ( |
number |
float
|
The value as a number ( |
boolean |
bool
|
The value as a bool ( |
data |
bytes
|
The value's UTF-8 bytes. |
source |
int
|
A |
from_native
classmethod
¶
from_native(native: ObjCObject) -> RemoteConfigValue
Copy a native FIRRemoteConfigValue.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
native
|
ObjCObject
|
the |
required |
json
¶
The value parsed as JSON, or default if it is empty or not JSON.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
default
|
Any
|
what to give back when the value is not JSON. |
None
|
ConfigUpdate
dataclass
¶
What a real-time update changed.
Attributes:
| Name | Type | Description |
|---|---|---|
updated_keys |
frozenset[str]
|
The parameters whose values changed on the server (added, removed or |
updated_keys
instance-attribute
¶
The parameters whose values changed on the server (added, removed or
changed): call activate to use the new values.
ConfigUpdateListener
¶
ConfigUpdateListener(
registration: ObjCObject, release: Callable[[], None]
)
Given back by add_on_config_update_listener. Call remove() to stop.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
registration
|
ObjCObject
|
the native |
required |
release
|
Callable[[], None]
|
releases the listener's callback block. |
required |
Methods:
| Name | Description |
|---|---|
remove |
Stop the updates (and the real-time connection, if it was the last |
remove
¶
Stop the updates (and the real-time connection, if it was the last listener). Safe to call more than once.
RemoteConfig
¶
RemoteConfig(native: ObjCObject)
The app's Remote Config. Get it with RemoteConfig.remote_config(),
or set it up with RemoteConfig.setup(...).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
native
|
ObjCObject
|
the native |
required |
Methods:
| Name | Description |
|---|---|
remote_config |
The shared instance for the default Firebase app. |
setup |
Install the in-app defaults, then fetch and activate in the background. |
set_minimum_fetch_interval |
Set |
set_defaults |
Set the in-app defaults: what |
set_defaults_from_plist |
Set the in-app defaults from a plist in the app bundle. |
default_value |
A parameter's in-app default. |
ensure_initialized |
Wait until the values saved by the last run are loaded (before reading |
fetch |
Fetch values from the server, without activating them. |
activate |
Make the last fetched values the ones |
fetch_and_activate |
Fetch values from the server and activate them. |
add_on_config_update_listener |
Listen for new values published on the server, in real time. |
set_custom_signals |
Set custom signals: values your Remote Config conditions can target. |
get_value |
A parameter's value, in every type, with where it came from. |
get_string |
A parameter's value as a string. |
get_boolean |
A parameter's value as a bool. |
get_number |
A parameter's value as a float. |
get_long |
A parameter's value as an int. |
get_data |
A parameter's value as bytes (its UTF-8 encoding). |
get_json |
A parameter's value parsed as JSON. |
all_keys |
The parameter names a source has. |
keys_with_prefix |
The activated parameter names that start with |
Attributes:
| Name | Type | Description |
|---|---|---|
native |
ObjCObject
|
The |
minimum_fetch_interval |
float
|
Seconds that must pass before a fetch reaches the server again |
fetch_timeout |
float
|
Seconds a fetch may take before it fails (default 60). |
last_fetch_time |
datetime | None
|
When the last successful fetch finished (UTC), or |
last_fetch_status |
int
|
A |
minimum_fetch_interval
property
writable
¶
Seconds that must pass before a fetch reaches the server again (Firebase's default is 12 hours).
fetch_timeout
property
writable
¶
Seconds a fetch may take before it fails (default 60).
last_fetch_time
property
¶
When the last successful fetch finished (UTC), or None.
remote_config
classmethod
¶
remote_config() -> RemoteConfig
The shared instance for the default Firebase app.
setup
classmethod
¶
setup(
defaults: Mapping[str, Any] | None = None,
defaults_file: str | PathLike[str] | None = None,
defaults_plist: str | None = None,
minimum_fetch_interval: float = 3600,
callback: FetchCallback | None = None,
) -> RemoteConfig
Install the in-app defaults, then fetch and activate in the background.
Call it once, at app start. When several sources give the same key,
defaults wins, then defaults_file, then defaults_plist.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
defaults
|
Mapping[str, Any] | None
|
default values. |
None
|
defaults_file
|
str | PathLike[str] | None
|
path to an Android-format defaults XML file. |
None
|
defaults_plist
|
str | None
|
name of a plist in the app bundle. |
None
|
minimum_fetch_interval
|
float
|
seconds between fetches. Lower it only while developing: Firebase throttles apps that fetch too often. |
3600
|
callback
|
FetchCallback | None
|
see |
None
|
Returns:
| Type | Description |
|---|---|
RemoteConfig
|
The shared |
set_minimum_fetch_interval
¶
Set minimum_fetch_interval.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
seconds
|
float
|
the interval. Use 0 only while developing. |
required |
set_defaults
¶
Set the in-app defaults: what get_* gives before any fetch.
Replaces earlier defaults (use setup to merge several sources).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
defaults
|
Mapping[str, Any]
|
|
required |
set_defaults_from_plist
¶
Set the in-app defaults from a plist in the app bundle.
Replaces earlier defaults.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_name
|
str
|
the plist's name, for example |
required |
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
the bundle has no such plist. |
ValueError
|
the plist is not a dictionary. |
default_value
¶
default_value(key: str) -> RemoteConfigValue | None
A parameter's in-app default.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
the parameter's name. |
required |
Returns:
| Type | Description |
|---|---|
RemoteConfigValue | None
|
The default, or |
ensure_initialized
¶
ensure_initialized(
callback: ErrorCallback | None = None,
) -> None
Wait until the values saved by the last run are loaded (before reading values very early at app start).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
callback
|
ErrorCallback | None
|
gets |
None
|
fetch
¶
fetch(
callback: Callable[[int, FirebaseError | None], None]
| None = None,
expiration_duration: float | None = None,
) -> None
Fetch values from the server, without activating them.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
callback
|
Callable[[int, FirebaseError | None], None] | None
|
gets |
None
|
expiration_duration
|
float | None
|
use cached values younger than this many
seconds instead of |
None
|
activate
¶
activate(callback: ActivateCallback | None = None) -> None
Make the last fetched values the ones get_* returns.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
callback
|
ActivateCallback | None
|
gets |
None
|
fetch_and_activate
¶
fetch_and_activate(
callback: FetchCallback | None = None,
) -> None
Fetch values from the server and activate them.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
callback
|
FetchCallback | None
|
gets |
None
|
add_on_config_update_listener
¶
add_on_config_update_listener(
listener: Callable[
[ConfigUpdate | None, FirebaseError | None], None
],
) -> ConfigUpdateListener
Listen for new values published on the server, in real time.
The first listener opens a connection to the server. New values are
fetched for you, but not activated: call activate in the listener.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
listener
|
Callable[[ConfigUpdate | None, FirebaseError | None], None]
|
gets |
required |
Returns:
| Type | Description |
|---|---|
ConfigUpdateListener
|
A |
set_custom_signals
¶
set_custom_signals(
signals: Mapping[str, str | int | float | None],
callback: ErrorCallback | None = None,
) -> None
Set custom signals: values your Remote Config conditions can target.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
signals
|
Mapping[str, str | int | float | None]
|
|
required |
callback
|
ErrorCallback | None
|
gets |
None
|
Raises:
| Type | Description |
|---|---|
TypeError
|
a value is not a string, number or |
get_value
¶
get_value(
key: str, source: int | None = None
) -> RemoteConfigValue
A parameter's value, in every type, with where it came from.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
the parameter's name. |
required |
source
|
int | None
|
read only from this |
None
|
Returns:
| Type | Description |
|---|---|
RemoteConfigValue
|
A |
get_string
¶
A parameter's value as a string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
the parameter's name, as in the Firebase console. |
required |
Returns:
| Type | Description |
|---|---|
str
|
The active value, else the default, else |
get_boolean
¶
A parameter's value as a bool.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
the parameter's name, as in the Firebase console. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True for values like |
bool
|
and when the key has no value. |
get_number
¶
A parameter's value as a float.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
the parameter's name, as in the Firebase console. |
required |
Returns:
| Type | Description |
|---|---|
float
|
The value as a float; |
get_long
¶
A parameter's value as an int.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
the parameter's name, as in the Firebase console. |
required |
Returns:
| Type | Description |
|---|---|
int
|
The value as an int; |
get_data
¶
A parameter's value as bytes (its UTF-8 encoding).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
the parameter's name, as in the Firebase console. |
required |
get_json
¶
A parameter's value parsed as JSON.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
the parameter's name, as in the Firebase console. |
required |
default
|
Any
|
what to give when the value is empty or not valid JSON. |
None
|
Returns:
| Type | Description |
|---|---|
Any
|
The parsed value (dict, list, str, number, bool or |
Any
|
|
all_keys
¶
all_keys(source: int = REMOTE) -> list[str]
The parameter names a source has.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source
|
int
|
|
REMOTE
|
Returns:
| Type | Description |
|---|---|
list[str]
|
The names. |
keys_with_prefix
¶
The activated parameter names that start with prefix.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prefix
|
str | None
|
the start of the names, or |
required |
Returns:
| Type | Description |
|---|---|
set[str]
|
The names. |
load_defaults
¶
Read an Android-format defaults XML file into a dict.
The format is Android's res/xml/remote_config_defaults.xml::
<defaults>
<entry><key>welcome_message</key><value>Hello</value></entry>
</defaults>
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | PathLike[str]
|
the file's path. |
required |
Returns:
| Type | Description |
|---|---|
dict[str, str]
|
|
dict[str, str]
|
skipped; a missing value is |
Raises:
| Type | Description |
|---|---|
OSError
|
the file cannot be read. |
ParseError
|
the file is not valid XML. |
load_plist_defaults
¶
Read a dictionary plist from the app bundle into a dict.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_name
|
str
|
the plist's name in the bundle, for example
|
required |
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
The plist's keys and values, as Python values. |
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
the bundle has no such plist. |
ValueError
|
the plist is not a dictionary. |