Skip to content

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 .plist file in the app bundle (defaults_plist=), the usual iOS way
  • a dict (defaults=)
  • an Android-format remote_config_defaults.xml file (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 (RemoteConfigValue.source).

RemoteConfigFetchStatus

RemoteConfig.last_fetch_status values.

RemoteConfigErrorCode

The error.code values of Remote Config errors.

RemoteConfigValue

One parameter's value, read in every type at once.

ConfigUpdate

What a real-time update changed.

ConfigUpdateListener

Given back by add_on_config_update_listener. Call remove() to stop.

RemoteConfig

The app's Remote Config. Get it with RemoteConfig.remote_config(),

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 error.domain of fetch and activate errors.

FetchStatus

The result of fetch_and_activate.

FetchCallback

(status, error) for fetch_and_activate.

ActivateCallback

(changed, error): whether activating changed any value, and the error.

STATUS_NAMES Final[dict[int, FetchStatus]]

FIRRemoteConfigFetchAndActivateStatus values, by number.

REMOTE_CONFIG_ERROR_DOMAIN module-attribute

REMOTE_CONFIG_ERROR_DOMAIN: Final = (
    "com.google.remoteconfig.ErrorDomain"
)

The error.domain of fetch and activate errors.

FetchStatus module-attribute

FetchStatus = Literal[
    "success_fetched_from_remote",
    "success_using_pre_fetched_data",
    "error",
]

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

Where a value comes from (RemoteConfigValue.source).

Attributes:

Name Type Description
REMOTE Final

Fetched from the server and activated.

DEFAULT Final

An in-app default.

STATIC Final

Neither: the empty / zero / False value.

REMOTE class-attribute instance-attribute

REMOTE: Final = 0

Fetched from the server and activated.

DEFAULT class-attribute instance-attribute

DEFAULT: Final = 1

An in-app default.

STATIC class-attribute instance-attribute

STATIC: Final = 2

Neither: the empty / zero / False value.

RemoteConfigFetchStatus

RemoteConfig.last_fetch_status values.

Attributes:

Name Type Description
THROTTLED Final

Too many fetches: wait, or lower minimum_fetch_interval only while developing.

THROTTLED class-attribute instance-attribute

THROTTLED: Final = 3

Too many fetches: wait, or lower minimum_fetch_interval only while developing.

RemoteConfigErrorCode

The error.code values of Remote Config errors.

Attributes:

Name Type Description
THROTTLED Final

Fetched too often (see RemoteConfigFetchStatus.THROTTLED).

THROTTLED class-attribute instance-attribute

THROTTLED: Final = 8002

Fetched too often (see RemoteConfigFetchStatus.THROTTLED).

RemoteConfigValue dataclass

RemoteConfigValue(
    string: str,
    number: float,
    boolean: bool,
    data: bytes,
    source: int,
)

One parameter's value, read in every type at once.

Methods:

Name Description
from_native

Copy a native FIRRemoteConfigValue.

json

The value parsed as JSON, or default if it is empty or not JSON.

Attributes:

Name Type Description
string str

The value as a string ("" if none).

number float

The value as a number (0.0 if it is not one).

boolean bool

The value as a bool ("true", "1", "yes"... are True).

data bytes

The value's UTF-8 bytes.

source int

A RemoteConfigSource value.

string instance-attribute

string: str

The value as a string ("" if none).

number instance-attribute

number: float

The value as a number (0.0 if it is not one).

boolean instance-attribute

boolean: bool

The value as a bool ("true", "1", "yes"... are True).

data instance-attribute

data: bytes

The value's UTF-8 bytes.

source instance-attribute

source: int

A RemoteConfigSource value.

from_native classmethod

from_native(native: ObjCObject) -> RemoteConfigValue

Copy a native FIRRemoteConfigValue.

Parameters:

Name Type Description Default
native ObjCObject

the FIRRemoteConfigValue.

required

json

json(default: Any = None) -> Any

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

ConfigUpdate(updated_keys: frozenset[str])

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

updated_keys: frozenset[str]

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 FIRConfigUpdateListenerRegistration.

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

remove() -> None

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 FIRRemoteConfig.

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 minimum_fetch_interval.

set_defaults

Set the in-app defaults: what get_* gives before any fetch.

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 get_* returns.

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 prefix.

Attributes:

Name Type Description
native ObjCObject

The FIRRemoteConfig.

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 None.

last_fetch_status int

A RemoteConfigFetchStatus value.

native property

native: ObjCObject

The FIRRemoteConfig.

minimum_fetch_interval property writable

minimum_fetch_interval: float

Seconds that must pass before a fetch reaches the server again (Firebase's default is 12 hours).

fetch_timeout property writable

fetch_timeout: float

Seconds a fetch may take before it fails (default 60).

last_fetch_time property

last_fetch_time: datetime | None

When the last successful fetch finished (UTC), or None.

last_fetch_status property

last_fetch_status: int

A RemoteConfigFetchStatus value.

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 fetch_and_activate.

None

Returns:

Type Description
RemoteConfig

The shared RemoteConfig.

set_minimum_fetch_interval

set_minimum_fetch_interval(seconds: float) -> None

Set minimum_fetch_interval.

Parameters:

Name Type Description Default
seconds float

the interval. Use 0 only while developing.

required

set_defaults

set_defaults(defaults: Mapping[str, Any]) -> None

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]

{key: value}. Values can be strings, numbers or bools.

required

set_defaults_from_plist

set_defaults_from_plist(file_name: str) -> None

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 "RemoteConfigDefaults" (".plist" is optional).

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 None if it has none.

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 once loaded, or the error.

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 (RemoteConfigFetchStatus, error).

None
expiration_duration float | None

use cached values younger than this many seconds instead of minimum_fetch_interval; 0 always fetches (only while developing).

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 (changed, error).

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 (status, error); status is a FetchStatus. Offline it gives an error, and the defaults or the last activated values keep being used.

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 (ConfigUpdate, None) for each update, or (None, error).

required

Returns:

Type Description
ConfigUpdateListener

A ConfigUpdateListener. Call .remove() to stop.

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]

{name: value}. Values are strings or numbers; None removes the signal.

required
callback ErrorCallback | None

gets None once saved, or the error.

None

Raises:

Type Description
TypeError

a value is not a string, number or None.

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 RemoteConfigSource, or None for the active value (remote, else default, else static).

None

Returns:

Type Description
RemoteConfigValue

A RemoteConfigValue.

get_string

get_string(key: str) -> str

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

get_boolean(key: str) -> bool

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 "true", "1" or "yes"; False otherwise,

bool

and when the key has no value.

get_number

get_number(key: str) -> float

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; 0.0 if it is missing or not a number.

get_long

get_long(key: str) -> int

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; 0 if it is missing or not a number.

get_data

get_data(key: str) -> bytes

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

get_json(key: str, default: Any = None) -> Any

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 None), or

Any

default.

all_keys

all_keys(source: int = REMOTE) -> list[str]

The parameter names a source has.

Parameters:

Name Type Description Default
source int

RemoteConfigSource.REMOTE (activated values, the default), DEFAULT (in-app defaults) or STATIC.

REMOTE

Returns:

Type Description
list[str]

The names.

keys_with_prefix

keys_with_prefix(prefix: str | None) -> set[str]

The activated parameter names that start with prefix.

Parameters:

Name Type Description Default
prefix str | None

the start of the names, or None for all of them.

required

Returns:

Type Description
set[str]

The names.

load_defaults

load_defaults(path: str | PathLike[str]) -> dict[str, str]

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]

{key: value}, all values as strings. Entries without a key are

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

load_plist_defaults(file_name: str) -> dict[str, Any]

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 "RemoteConfigDefaults" (".plist" is optional).

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.