From 166f17ddf5fe6d7b0f8e6e6e6e25df945318619b Mon Sep 17 00:00:00 2001 From: Ombuweb Date: Tue, 2 May 2023 17:05:08 +0200 Subject: [PATCH 1/5] docs(firebase-remote-config): update --- packages/firebase-remote-config/README.md | 281 +++++++++++++++++++++- 1 file changed, 273 insertions(+), 8 deletions(-) diff --git a/packages/firebase-remote-config/README.md b/packages/firebase-remote-config/README.md index 47ec10ae..a94c4a53 100644 --- a/packages/firebase-remote-config/README.md +++ b/packages/firebase-remote-config/README.md @@ -1,26 +1,45 @@ # @nativescript/firebase-remote-config +## Intro + +This plugin allows you to use the [Firebase Remote Config](https://firebase.google.com/docs/remote-config/) API in your NativeScript app. + +[![image](https://img.youtube.com/vi/_CXXVFPO6f0/hqdefault.jpg)](https://www.youtube.com/watch?v=_CXXVFPO6f0) + +## Set up your app for Firebase + +You need to set up your app for Firebase before you can enable Firebase Remote Config. To set up and initialize Firebase for your NativeScript app, follow the instructions on the documentation of the [@nativescript/firebase-core](../firebase-core/) plugin. + +## Add the Firebase Remote Config SDK to your app + +To add the Firebase Remote Config to your app, follow these steps: + +1. Install the `@nativescript/firebase-remote-config` plugin by running the following command in the root directory of your project. + ```cli npm install @nativescript/firebase-remote-config ``` -### What does it do +2. Add the SDK by importing the `@nativescript/firebase-remote-config` module. You should import this module once in your app, ideally in the main file (e.g. `app.ts` or `main.ts`). -Remote Config allows you to change the appearance and/or functionality of your app without requiring an app update. Remote Config values are input into the Firebase console and accessible via a JavaScript API. This gives you full control over when and how these Remote Config values are applied and affect your application. +```ts +import '@nativescript/firebase-remote-config'; +``` -[![image](https://img.youtube.com/vi/_CXXVFPO6f0/hqdefault.jpg)](https://www.youtube.com/watch?v=_CXXVFPO6f0) +## Create default parameters -## Usage +To create default Remote Config parameters, follow the steps: -To get started, you need to define some parameters over on the [Firebase Console](https://console.firebase.google.com/project/_/config). +1. [Firebase Console](https://console.firebase.google.com/project/_/config) and select your project. +2. On the **Remote Config** page, click **Create configuration** to create a parameter. -## Default values +### Set default values Before fetching the parameters from Firebase, it is first important to set some default values. Default values help ensure that your application code runs as expected in scenarios where the device has not yet retrieved the values. -An example of this is having no network or you have not yet fetched them within your own code. +An example of this is having no network or you have not yet fetched them within your code. -Setting default values helps to ensure that both the local device & Firebase servers are both in sync. Call the setDefaults method early on in your application: +Setting default values helps to ensure that both the local device & Firebase servers are both in sync. Call the [setDefaults](#setdefaults) method early on in your application: ```ts import { firebase } from '@nativescript/firebase-core'; @@ -138,6 +157,252 @@ import { firebase } from '@nativescript/firebase-core'; remoteConfig().settings.minimumFetchIntervalMillis = 30000; ``` +## API + +### RemoteConfig class + +#### android + +```ts +import { firebase } from '@nativescript/firebase-core'; + +remoteConfigAndroid: com.google.firebase.remoteconfig.FirebaseRemoteConfig = firebase().remoteConfig().android; +``` +A `read-only` property that returns the naive object for Android wrapped by the instance of the RemoteConfig class. + +--- +#### ios + +```ts +import { firebase } from '@nativescript/firebase-core'; + +remoteConfigIos: FIRRemoteConfig = firebase().remoteConfig().ios; +``` +A `read-only` property that returns the naive object for iOS wrapped by the instance of the RemoteConfig class. + +--- +#### app + +```ts +import { firebase } from '@nativescript/firebase-core'; + +remoteConfigApp: FirebaseApp = firebase().remoteConfig().app; +``` +A `read-only` property that returns the FirebaseApp instance for the current app. + +--- +#### fetchTimeMillis + +```ts +import { firebase } from '@nativescript/firebase-core'; + +remoteConfigFetchTimeMillis: number = firebase().remoteConfig().fetchTimeMillis; +``` +A `read-only` property that returns the timestamp (milliseconds since epoch) of the last successful fetch, regardless of whether the fetch was activated or not. + +--- +#### lastFetchStatus + +```ts +import { firebase } from '@nativescript/firebase-core'; + +remoteConfigLastFetchStatus: 'success' | 'failure' | 'no_fetch_yet' | 'throttled' = firebase().remoteConfig().lastFetchStatus; +``` +A `read-only` property that returns the status of the most recent fetch attempt. + +--- +#### settings + +```ts +import { firebase } from '@nativescript/firebase-core'; + +remoteConfigSettings: ConfigSettings = firebase().remoteConfig().settings; +// or +firebase().remoteConfig().settings = { + minimumFetchIntervalMillis: 30000, +}; +``` + +--- +#### activate() + +```ts +import { firebase } from '@nativescript/firebase-core'; + +activated: boolean = await firebase().remoteConfig().activate(); +``` + +--- +#### ensureInitialized() + +```ts +import { firebase } from '@nativescript/firebase-core'; + +await firebase().remoteConfig().ensureInitialized(); +``` + +--- +#### fetch() + +```ts +import { firebase } from '@nativescript/firebase-core'; + +await firebase().remoteConfig().fetch(expirationDurationSeconds); +``` + +| Parameter | Type | Description | +| --- | --- | --- | +| `expirationDurationSeconds` | `number` | + +--- +#### fetchAndActivate() + +```ts +import { firebase } from '@nativescript/firebase-core'; + +activated: boolean = await firebase().remoteConfig().fetchAndActivate(); +``` + +--- +#### getAll() + +```ts +import { firebase } from '@nativescript/firebase-core'; + +parameters: Record = firebase().remoteConfig().getAll(); +``` + +--- +#### getBoolean() + +```ts +import { firebase } from '@nativescript/firebase-core'; + +value: boolean = firebase().remoteConfig().getBoolean(key); +``` + +| Parameter | Type | Description | +| --- | --- | --- | +| `key` | `string` | + +--- +#### getNumber() + +```ts +import { firebase } from '@nativescript/firebase-core'; + +value: number = firebase().remoteConfig().getNumber(key); +``` + +| Parameter | Type | Description | +| --- | --- | --- | +| `key` | `string` | + +--- +#### getString() + +```ts +import { firebase } from '@nativescript/firebase-core'; + +value: string = firebase().remoteConfig().getString(key); +``` + +| Parameter | Type | Description | +| --- | --- | --- | +| `key` | `string` | + +--- +#### getValue() + +```ts +import { firebase } from '@nativescript/firebase-core'; + +value: ConfigValue = firebase().remoteConfig().getValue(key); +``` + +| Parameter | Type | Description | +| --- | --- | --- | +| `key` | `string` | + +--- +#### reset() + +```ts +import { firebase } from '@nativescript/firebase-core'; + +await firebase().remoteConfig().reset(); +``` + +--- +#### setDefaults() + +```ts +import { firebase } from '@nativescript/firebase-core'; + +await firebase().remoteConfig().setDefaults(defaults); +``` + +| Parameter | Type | Description | +| --- | --- | --- | +| `defaults` | `ConfigDefaults` | + + +--- +#### setDefaultsFromResource() + +```ts +import { firebase } from '@nativescript/firebase-core'; + +await firebase().remoteConfig().setDefaultsFromResource(resourceName); +``` + +| Parameter | Type | Description | +| --- | --- | --- | +| `resourceName` | `string` | + + + +```ts +export class RemoteConfig implements IRemoteConfig { + constructor(app?: FirebaseApp); + + readonly native; + readonly ios; + readonly android; + + readonly app: FirebaseApp; + + readonly fetchTimeMillis: number; + + readonly lastFetchStatus: 'success' | 'failure' | 'no_fetch_yet' | 'throttled'; + + settings: ConfigSettings; + + activate(): Promise; + + ensureInitialized(): Promise; + + fetch(expirationDurationSeconds?: number): Promise; + + fetchAndActivate(): Promise; + + getAll(): Record; + + getBoolean(key: string): boolean; + + getNumber(key: string): number; + + getString(key: string): string; + + getValue(key: string): ConfigValue; + + reset(): Promise; + + setDefaults(defaults: ConfigDefaults): Promise; + + setDefaultsFromResource(resourceName: string): Promise; +} +``` ## License Apache License Version 2.0 From de52bb9cd99034528c689d4bacb9ebce2efe2655 Mon Sep 17 00:00:00 2001 From: Ombuweb Date: Wed, 3 May 2023 11:25:33 +0200 Subject: [PATCH 2/5] chore: update --- packages/firebase-remote-config/README.md | 105 +++++++++------------- 1 file changed, 42 insertions(+), 63 deletions(-) diff --git a/packages/firebase-remote-config/README.md b/packages/firebase-remote-config/README.md index a94c4a53..f34d78cd 100644 --- a/packages/firebase-remote-config/README.md +++ b/packages/firebase-remote-config/README.md @@ -26,24 +26,26 @@ npm install @nativescript/firebase-remote-config import '@nativescript/firebase-remote-config'; ``` -## Create default parameters +## Create in-app default parameters -To create default Remote Config parameters, follow the steps: +Default values help ensure that your application code runs as expected in scenarios where the device has not yet retrieved the values from the remote server. + +To create default in-app Remote Config parameters, follow the steps: 1. [Firebase Console](https://console.firebase.google.com/project/_/config) and select your project. 2. On the **Remote Config** page, click **Create configuration** to create a parameter. +3. Download the `.xml` file with the parameter values by following the instructions [Firebase Console](https://firebase.google.com/docs/remote-config/get-started?platform=android#firebase-console). +4. Add the `.xml` file to your app in an `App_Resources/Android/res/xml` folder. +5. Send the in-app default parameters to the Remote Config backend by calling the [setDefaultsFromResource](#setdefaultsfromresource) method in your bootstrap file (e.g. `app.ts` or `main.ts`). -### Set default values - -Before fetching the parameters from Firebase, it is first important to set some default values. Default values help ensure that your application code runs as expected in scenarios where the device has not yet retrieved the values. +```ts -An example of this is having no network or you have not yet fetched them within your code. +### Set parameter values in the Remote Config backend -Setting default values helps to ensure that both the local device & Firebase servers are both in sync. Call the [setDefaults](#setdefaults) method early on in your application: +To add values to the Remote Config backend, call the [setDefaults](#setdefaults) method with an object specifying the name of the parameters and their values, in the bootstrap file before the app starts.: ```ts import { firebase } from '@nativescript/firebase-core'; -import '@nativescript/firebase-remote-config'; // only needs to be imported 1x firebase() .remoteConfig() @@ -55,9 +57,9 @@ firebase() }); ``` -### Fetch & Activate +### Fetch and activate values -Before reading the values from Firebase, we first need to pull them from Firebase (fetching) & then enable them on the device (activating). The fetchAndActivate API combines both tasks into a single flow: +Before reading the values from Firebase, we first need to pull them from Firebase (fetching) & then enable them on the device (activating). The [fetchAndActivate](#fetchandactivate) method combines both tasks into a single flow: ```ts import { firebase } from '@nativescript/firebase-core'; @@ -79,7 +81,7 @@ firebase() ### Reading values -With the defaults set and the remote values fetched from Firebase, we can now use the getValue method to get the value and use a number of methods to retrieve the value (same API as Firebase Remote Config web SDK) +With the defaults set and the remote values fetched from Firebase, we can now use the [getValue](#getvalue) method to get the value and use several methods to retrieve the value (same API as Firebase Remote Config web SDK) ```ts import { firebase } from '@nativescript/firebase-core'; @@ -103,7 +105,7 @@ if (awesomeNewFeature.asBoolean() === true) { } ``` -The API also provides a getAll method to read all parameters at once rather than by key: +The API also provides a [getAll](#getall) method to read all parameters at once rather than by key: ```ts import { firebase } from '@nativescript/firebase-core'; @@ -120,7 +122,7 @@ Object.entries(parameters).forEach((item) => { ### Value source -When a value is read, it contains source data about the parameter. As explained above, if a value is read before it has been fetched & activated then the value will fallback to the default value set. If you need to validate whether the value returned from the module was local or remote, the getSource() method can be conditionally checked: +When a value is read, it contains source data about the parameter. As explained above, if a value is read before it has been fetched & activated then the value will fall back to the default value set. If you need to validate whether the value returned from the module was local or remote, the getSource() method can be conditionally checked: ```ts import { firebase } from '@nativescript/firebase-core'; @@ -219,9 +221,11 @@ import { firebase } from '@nativescript/firebase-core'; remoteConfigSettings: ConfigSettings = firebase().remoteConfig().settings; // or firebase().remoteConfig().settings = { + fetchTimeMillis: 43200000, minimumFetchIntervalMillis: 30000, }; ``` +Gets or sets the settings for this RemoteConfig instance. --- #### activate() @@ -231,6 +235,7 @@ import { firebase } from '@nativescript/firebase-core'; activated: boolean = await firebase().remoteConfig().activate(); ``` +Asynchronously activates the most recently fetched configs, so that the fetched key-value pairs take effect. For more information, see [activate()](https://firebase.google.com/docs/reference/android/com/google/firebase/remoteconfig/FirebaseRemoteConfig#activate()) on the Firebase website. --- #### ensureInitialized() @@ -249,10 +254,11 @@ import { firebase } from '@nativescript/firebase-core'; await firebase().remoteConfig().fetch(expirationDurationSeconds); ``` +Fetches configs, adhering to the default or specified minimum fetch interval. For more information, see [fetch()](https://firebase.google.com/docs/reference/android/com/google/firebase/remoteconfig/FirebaseRemoteConfig#fetch(long)) on the Firebase website. | Parameter | Type | Description | | --- | --- | --- | -| `expirationDurationSeconds` | `number` | +| `expirationDurationSeconds` | `number` | --- #### fetchAndActivate() @@ -262,6 +268,7 @@ import { firebase } from '@nativescript/firebase-core'; activated: boolean = await firebase().remoteConfig().fetchAndActivate(); ``` +Asynchronously fetches and then activates the fetched configs. For more information, see [fetchAndActivate()](https://firebase.google.com/docs/reference/android/com/google/firebase/remoteconfig/FirebaseRemoteConfig#fetchAndActivate()) on the Firebase website. --- #### getAll() @@ -271,6 +278,7 @@ import { firebase } from '@nativescript/firebase-core'; parameters: Record = firebase().remoteConfig().getAll(); ``` +Returns an object with all the parameters in the Remote Config. --- #### getBoolean() @@ -280,10 +288,11 @@ import { firebase } from '@nativescript/firebase-core'; value: boolean = firebase().remoteConfig().getBoolean(key); ``` +Returns the parameter value for the given key as a boolean. | Parameter | Type | Description | | --- | --- | --- | -| `key` | `string` | +| `key` | `string` | The key of the parameter to get. | --- #### getNumber() @@ -293,10 +302,11 @@ import { firebase } from '@nativescript/firebase-core'; value: number = firebase().remoteConfig().getNumber(key); ``` +Returns the parameter value for the given key as a number. | Parameter | Type | Description | | --- | --- | --- | -| `key` | `string` | +| `key` | `string` | The key of the parameter to get. | --- #### getString() @@ -306,10 +316,11 @@ import { firebase } from '@nativescript/firebase-core'; value: string = firebase().remoteConfig().getString(key); ``` +Returns the parameter value for the given key as a string. | Parameter | Type | Description | | --- | --- | --- | -| `key` | `string` | +| `key` | `string` | The key of the parameter to get. | --- #### getValue() @@ -319,10 +330,11 @@ import { firebase } from '@nativescript/firebase-core'; value: ConfigValue = firebase().remoteConfig().getValue(key); ``` +Returns the parameter value for the given key as a [ConfigValue](). | Parameter | Type | Description | | --- | --- | --- | -| `key` | `string` | +| `key` | `string` | The key of the parameter to get. | --- #### reset() @@ -332,6 +344,7 @@ import { firebase } from '@nativescript/firebase-core'; await firebase().remoteConfig().reset(); ``` +Deletes all activated, fetched and default configurations and resets all Firebase Remote Config settings. --- #### setDefaults() @@ -342,10 +355,18 @@ import { firebase } from '@nativescript/firebase-core'; await firebase().remoteConfig().setDefaults(defaults); ``` +Sets default configs from a [ConfigDefaults](#configdefaults) object. + | Parameter | Type | Description | | --- | --- | --- | -| `defaults` | `ConfigDefaults` | +| `defaults` | [ConfigDefaults](#configdefaults) | The default configs object to set. | +#### ConfigDefaults +```ts +interface ConfigDefaults { + [key: string]: number | string | boolean; +} +``` --- #### setDefaultsFromResource() @@ -355,54 +376,12 @@ import { firebase } from '@nativescript/firebase-core'; await firebase().remoteConfig().setDefaultsFromResource(resourceName); ``` +Sets default configs using an `XML` resource. | Parameter | Type | Description | | --- | --- | --- | -| `resourceName` | `string` | - - - -```ts -export class RemoteConfig implements IRemoteConfig { - constructor(app?: FirebaseApp); - - readonly native; - readonly ios; - readonly android; - - readonly app: FirebaseApp; - - readonly fetchTimeMillis: number; - - readonly lastFetchStatus: 'success' | 'failure' | 'no_fetch_yet' | 'throttled'; +| `resourceName` | `string` | The resource name of the XML resource in the package's res folder. | - settings: ConfigSettings; - - activate(): Promise; - - ensureInitialized(): Promise; - - fetch(expirationDurationSeconds?: number): Promise; - - fetchAndActivate(): Promise; - - getAll(): Record; - - getBoolean(key: string): boolean; - - getNumber(key: string): number; - - getString(key: string): string; - - getValue(key: string): ConfigValue; - - reset(): Promise; - - setDefaults(defaults: ConfigDefaults): Promise; - - setDefaultsFromResource(resourceName: string): Promise; -} -``` ## License Apache License Version 2.0 From 49cdc9c8dbef55a6539413d2d92b07f129deb0ee Mon Sep 17 00:00:00 2001 From: Ombuweb Date: Wed, 3 May 2023 22:54:14 +0200 Subject: [PATCH 3/5] chore: update --- packages/firebase-remote-config/README.md | 72 ++++++++++++++++++----- 1 file changed, 58 insertions(+), 14 deletions(-) diff --git a/packages/firebase-remote-config/README.md b/packages/firebase-remote-config/README.md index f34d78cd..f434ae78 100644 --- a/packages/firebase-remote-config/README.md +++ b/packages/firebase-remote-config/README.md @@ -1,5 +1,39 @@ # @nativescript/firebase-remote-config +## Contents +* [Intro](#intro) +* [Set up your app for Firebase](#set-up-your-app-for-firebase) +* [Add the Firebase Remote Config SDK to your app](#add-the-firebase-remote-config-sdk-to-your-app) +* [Create in-app default parameters](#create-in-app-default-parameters) +* [Set parameter values in the Remote Config backend](#set-parameter-values-in-the-remote-config-backend) +* [Fetch and activate values](#fetch-and-activate-values) +* [Reading values](#reading-values) +* [Determine the source of a parameter's value](#determine-the-source-of-a-parameters-value) +* [Set a minimum fetch interval](#set-a-minimum-fetch-interval) +* [API](#api) + * [RemoteConfig class](#remoteconfig-class) + * [android](#android) + * [ios](#ios) + * [app](#app) + * [fetchTimeMillis](#fetchtimemillis) + * [lastFetchStatus](#lastfetchstatus) + * [settings](#settings) + * [activate()](#activate) + * [ensureInitialized()](#ensureinitialized) + * [fetch()](#fetch) + * [fetchAndActivate()](#fetchandactivate) + * [getAll()](#getall) + * [getBoolean()](#getboolean) + * [getNumber()](#getnumber) + * [getString()](#getstring) + * [getValue()](#getvalue) + * [reset()](#reset) + * [setDefaults()](#setdefaults) + * [setDefaultsFromResource()](#setdefaultsfromresource) + +* [License](#license) + + ## Intro This plugin allows you to use the [Firebase Remote Config](https://firebase.google.com/docs/remote-config/) API in your NativeScript app. @@ -28,21 +62,30 @@ import '@nativescript/firebase-remote-config'; ## Create in-app default parameters -Default values help ensure that your application code runs as expected in scenarios where the device has not yet retrieved the values from the remote server. +Default in-app values help ensure that your application code runs as expected in scenarios where the device has not yet retrieved the values from the remote server. To create default in-app Remote Config parameters, follow the steps: 1. [Firebase Console](https://console.firebase.google.com/project/_/config) and select your project. -2. On the **Remote Config** page, click **Create configuration** to create a parameter. +2. On the **Remote Config** dashboard, click **Create configuration** to create a parameter. 3. Download the `.xml` file with the parameter values by following the instructions [Firebase Console](https://firebase.google.com/docs/remote-config/get-started?platform=android#firebase-console). 4. Add the `.xml` file to your app in an `App_Resources/Android/res/xml` folder. -5. Send the in-app default parameters to the Remote Config backend by calling the [setDefaultsFromResource](#setdefaultsfromresource) method in your bootstrap file (e.g. `app.ts` or `main.ts`). +5. Send the in-app default parameters in the `.xml` file to the Remote Config backend by calling the [setDefaultsFromResource](#setdefaultsfromresource) method in your bootstrap file (e.g. `app.ts` or `main.ts`). ```ts +import { firebase } from '@nativescript/firebase-core'; + +firebase() + .remoteConfig() + .setDefaultsFromResource("remote_config_defaults") + .then(() => { + console.log('Default values set.'); + }); +``` ### Set parameter values in the Remote Config backend -To add values to the Remote Config backend, call the [setDefaults](#setdefaults) method with an object specifying the name of the parameters and their values, in the bootstrap file before the app starts.: +To add values to the Remote Config backend programmatically, call the [setDefaults](#setdefaults) method with an object specifying the name of the parameters and their values, in the bootstrap file before the app starts: ```ts import { firebase } from '@nativescript/firebase-core'; @@ -59,7 +102,7 @@ firebase() ### Fetch and activate values -Before reading the values from Firebase, we first need to pull them from Firebase (fetching) & then enable them on the device (activating). The [fetchAndActivate](#fetchandactivate) method combines both tasks into a single flow: +Before reading the values from Firebase, you need to pull them from Firebase (fetching) & then enable them on the device (activating). The [fetchAndActivate](#fetchandactivate) method combines both tasks into a single flow: ```ts import { firebase } from '@nativescript/firebase-core'; @@ -81,7 +124,7 @@ firebase() ### Reading values -With the defaults set and the remote values fetched from Firebase, we can now use the [getValue](#getvalue) method to get the value and use several methods to retrieve the value (same API as Firebase Remote Config web SDK) +With the defaults set and the remote values fetched from Firebase, we can now use the [getValue](#getvalue) method to get the value and use several methods to retrieve the value. ```ts import { firebase } from '@nativescript/firebase-core'; @@ -120,14 +163,14 @@ Object.entries(parameters).forEach((item) => { }); ``` -### Value source +### Determine the source of a parameter's value -When a value is read, it contains source data about the parameter. As explained above, if a value is read before it has been fetched & activated then the value will fall back to the default value set. If you need to validate whether the value returned from the module was local or remote, the getSource() method can be conditionally checked: +When a value is read, it contains source data about the parameter. If a value is read before it has been fetched & activated then the value will fall back to the default in-app value set. If you need to validate whether the value returned from the module was local or remote, call the [getSource]() method on the [ConfigValue]() object: ```ts import { firebase } from '@nativescript/firebase-core'; -const awesomeNewFeature = firebase().remoteConfig().getValue('awesome_new_feature'); +const awesomeNewFeature: ConfigValue = firebase().remoteConfig().getValue('awesome_new_feature'); if (awesomeNewFeature.getSource() === 'remote') { console.log('Parameter value was from the Firebase servers.'); @@ -138,11 +181,11 @@ if (awesomeNewFeature.getSource() === 'remote') { } ``` -### Caching +### Set a minimum fetch interval -Although Remote Config is a data-store, it is not designed for frequent reads - Firebase heavily caches the parameters (default is 12 hours). By design, this prevents the values being able to change frequently and potentially cause users confusion. +Although Remote Config is a data storage, it is not designed for frequent reads. By default, Firebase caches the parameters for 12 hours. By design, this prevents the values from being able to change frequently and potentially causes users confusion. -You can however specify your own cache length by specifically calling the fetch method with the number of seconds to cache the values for: +- To set a different minimum fetch interval, pass it, in seconds, to the [fetch](#fetch) method: ```ts import { firebase } from '@nativescript/firebase-core'; @@ -150,9 +193,10 @@ import { firebase } from '@nativescript/firebase-core'; await firebase().remoteConfig().fetch(300); ``` -To bypass caching fully, you can pass a value of 0. Be warned Firebase may start to reject your requests if values are requested too frequently. +- To bypass caching fully, you can pass a value of `0`. +> **Note** Be warned Firebase may start to reject your requests if values are requested too frequently. -You can also apply a global cache frequency by calling the setConfigSettings method with the minimumFetchIntervalMillis property: +- You can also apply a global cache frequency by setting the `minimumFetchIntervalMillis` property of the `RemoteConfigSettings` object to the number of milliseconds to cache the values for. This can be done in the bootstrap file before the app starts: ```ts import { firebase } from '@nativescript/firebase-core'; From f16678cab0300a92b273514eb63f213a3876a387 Mon Sep 17 00:00:00 2001 From: Ombuweb Date: Thu, 4 May 2023 07:44:52 +0200 Subject: [PATCH 4/5] chore: update --- packages/firebase-remote-config/README.md | 79 +++++++++++++++++++++-- 1 file changed, 75 insertions(+), 4 deletions(-) diff --git a/packages/firebase-remote-config/README.md b/packages/firebase-remote-config/README.md index f434ae78..801d84e5 100644 --- a/packages/firebase-remote-config/README.md +++ b/packages/firebase-remote-config/README.md @@ -8,7 +8,7 @@ * [Set parameter values in the Remote Config backend](#set-parameter-values-in-the-remote-config-backend) * [Fetch and activate values](#fetch-and-activate-values) * [Reading values](#reading-values) -* [Determine the source of a parameter's value](#determine-the-source-of-a-parameters-value) +* [Get the source of a parameter's value](#get-the-source-of-a-parameters-value) * [Set a minimum fetch interval](#set-a-minimum-fetch-interval) * [API](#api) * [RemoteConfig class](#remoteconfig-class) @@ -30,6 +30,14 @@ * [reset()](#reset) * [setDefaults()](#setdefaults) * [setDefaultsFromResource()](#setdefaultsfromresource) + * [ConfigValue object](#configvalue-object) + * [android](#android-1) + * [ios](#ios-1) + * [asBoolean()](#asboolean) + * [asNumber()](#asnumber) + * [asString()](#asstring) + * [getSource()](#getsource) + * [License](#license) @@ -163,9 +171,9 @@ Object.entries(parameters).forEach((item) => { }); ``` -### Determine the source of a parameter's value +### Get the source of a parameter's value -When a value is read, it contains source data about the parameter. If a value is read before it has been fetched & activated then the value will fall back to the default in-app value set. If you need to validate whether the value returned from the module was local or remote, call the [getSource]() method on the [ConfigValue]() object: +When a value is read, it contains source data about the parameter. If a value is read before it has been fetched & activated then the value will fall back to the default in-app value set. If you need to validate whether the value returned from the module was local or remote, call the [getSource](#getsource) method on the [ConfigValue](#configvalue-object) object: ```ts import { firebase } from '@nativescript/firebase-core'; @@ -374,7 +382,7 @@ import { firebase } from '@nativescript/firebase-core'; value: ConfigValue = firebase().remoteConfig().getValue(key); ``` -Returns the parameter value for the given key as a [ConfigValue](). +Returns the parameter value for the given key as a [ConfigValue](#configvalue-object). | Parameter | Type | Description | | --- | --- | --- | @@ -426,6 +434,69 @@ Sets default configs using an `XML` resource. | --- | --- | --- | | `resourceName` | `string` | The resource name of the XML resource in the package's res folder. | +--- +### ConfigValue object + +This object is returned by the [getValue()](#getvalue) method and represents a parameter value for a given key. It provides several methods to get the value as a boolean, number or string. + +#### android +```ts +configValue: ConfigValue = firebase().remoteConfig().getValue(key) + +configValueAndroid: com.google.firebase.remoteconfig.FirebaseRemoteConfigValue = configValue.android; +``` +Returns an instance of ConfigValue for Android. + +--- +#### ios +```ts +configValue: ConfigValue = firebase().remoteConfig().getValue(key) + +configValueIOS: FIRRemoteConfigValue = configValue.ios; +``` +Returns an instance of ConfigValue for iOS. + +--- +#### asBoolean() + +```ts +configValue: ConfigValue = firebase().remoteConfig().getValue(key) + +value: boolean = configValue.asBoolean(); +``` +Gets the parameter value as a boolean. + +--- +#### asNumber() + +```ts +configValue: ConfigValue = firebase().remoteConfig().getValue(key) + +value: number = configValue.asNumber(); +``` +Gets the parameter value as a number. + +--- +#### asString() + +```ts +configValue: ConfigValue = firebase().remoteConfig().getValue(key) + +value: string = configValue.asString(); +``` +Gets the parameter value as a string. + +--- +#### getSource() + +```ts +configValue: ConfigValue = firebase().remoteConfig().getValue(key) + +source: 'default' | 'static' | 'remote' = configValue.getSource(); +``` +Gets the source of the parameter value. + +--- ## License Apache License Version 2.0 From 174af8d4e9da402497cae588aeec89284de314d1 Mon Sep 17 00:00:00 2001 From: Ombuweb Date: Thu, 4 May 2023 09:29:00 +0200 Subject: [PATCH 5/5] chore: update --- packages/firebase-remote-config/README.md | 129 ++++++++++++---------- 1 file changed, 68 insertions(+), 61 deletions(-) diff --git a/packages/firebase-remote-config/README.md b/packages/firebase-remote-config/README.md index 801d84e5..4f01c07a 100644 --- a/packages/firebase-remote-config/README.md +++ b/packages/firebase-remote-config/README.md @@ -7,7 +7,10 @@ * [Create in-app default parameters](#create-in-app-default-parameters) * [Set parameter values in the Remote Config backend](#set-parameter-values-in-the-remote-config-backend) * [Fetch and activate values](#fetch-and-activate-values) -* [Reading values](#reading-values) + * [Set a minimum fetch interval](#set-a-minimum-fetch-interval) +* [Reading parameters values](#reading-parameters-values) + * [Read a single parameter](#read-a-single-parameter) + * [Read all parameters at once](#read-all-parameters-at-once) * [Get the source of a parameter's value](#get-the-source-of-a-parameters-value) * [Set a minimum fetch interval](#set-a-minimum-fetch-interval) * [API](#api) @@ -76,63 +79,88 @@ To create default in-app Remote Config parameters, follow the steps: 1. [Firebase Console](https://console.firebase.google.com/project/_/config) and select your project. 2. On the **Remote Config** dashboard, click **Create configuration** to create a parameter. -3. Download the `.xml` file with the parameter values by following the instructions [Firebase Console](https://firebase.google.com/docs/remote-config/get-started?platform=android#firebase-console). -4. Add the `.xml` file to your app in an `App_Resources/Android/res/xml` folder. -5. Send the in-app default parameters in the `.xml` file to the Remote Config backend by calling the [setDefaultsFromResource](#setdefaultsfromresource) method in your bootstrap file (e.g. `app.ts` or `main.ts`). +3. You can add default in-app parameter values through either of the two options below. In both options, add the values to the Remote Config object early in your app's lifecycle, ideally in your bootstrap file (e.g. `app.ts` or `main.ts`) + 1. Download and add the `.xml` file with the parameter values to your app. + * Add the in-app default parameters in the `.xml` file to the Remote Config object by calling the [setDefaultsFromResource](#setdefaultsfromresource) method. + ```ts + import { firebase } from '@nativescript/firebase-core'; + + firebase() + .remoteConfig() + .setDefaultsFromResource("remote_config_defaults") + .then(() => { + console.log('Default values set.'); + }); + ``` + 2. Add the in-app parameter values to the Remote Config object by passing them in an object to the [setDefaults](#setdefaults) method. + ```ts + import { firebase } from '@nativescript/firebase-core'; + + firebase() + .remoteConfig() + .setDefaults({ + awesome_new_feature: 'disabled', + }) + .then(() => { + console.log('Default values set.'); + }); + ``` + +## Set parameter values in the Remote Config backend + +To create new server-side default values that override the in-app values, see [Set parameter values in the Remote Config backend](https://firebase.google.com/docs/remote-config/get-started?platform=android#set-backend-par-values) + +## Fetch and activate values + +Once you've created your parameters in the Remote Config backend, you can fetch them from the server and activate them in your app. You can first fetch the values from the server and then activate them, or you can combine the two tasks into a single flow with the [fetchAndActivate](#fetchandactivate) method. ```ts import { firebase } from '@nativescript/firebase-core'; firebase() .remoteConfig() - .setDefaultsFromResource("remote_config_defaults") - .then(() => { - console.log('Default values set.'); + .setDefaults({ + awesome_new_feature: 'disabled', + }) + .then(() => remoteConfig().fetchAndActivate()) + .then((fetchedRemotely) => { + if (fetchedRemotely) { + console.log('Configs were retrieved from the backend and activated.'); + } else { + console.log('No configs were fetched from the backend, and the local configs were already activated'); + } }); ``` -### Set parameter values in the Remote Config backend +### Set a minimum fetch interval + +Although Remote Config is a data storage, it is not designed for frequent reads. By default, Firebase caches the parameters for 12 hours. By design, this prevents the values from being able to change frequently and potentially causes users confusion. -To add values to the Remote Config backend programmatically, call the [setDefaults](#setdefaults) method with an object specifying the name of the parameters and their values, in the bootstrap file before the app starts: +- To set a different minimum fetch interval, pass it, in seconds, to the [fetch](#fetch) method: ```ts import { firebase } from '@nativescript/firebase-core'; - -firebase() - .remoteConfig() - .setDefaults({ - awesome_new_feature: 'disabled', - }) - .then(() => { - console.log('Default values set.'); - }); +// Fetch and cache for 5 minutes +await firebase().remoteConfig().fetch(300); ``` -### Fetch and activate values +- To bypass caching fully, you can pass a value of `0`. +> **Note** Be warned Firebase may start to reject your requests if values are requested too frequently. -Before reading the values from Firebase, you need to pull them from Firebase (fetching) & then enable them on the device (activating). The [fetchAndActivate](#fetchandactivate) method combines both tasks into a single flow: +- You can also apply a global cache frequency by setting the `minimumFetchIntervalMillis` property of the `RemoteConfigSettings` object to the number of milliseconds to cache the values for. This can be done in the bootstrap file before the app starts: ```ts import { firebase } from '@nativescript/firebase-core'; - -firebase() - .remoteConfig() - .setDefaults({ - awesome_new_feature: 'disabled', - }) - .then(() => remoteConfig().fetchAndActivate()) - .then((fetchedRemotely) => { - if (fetchedRemotely) { - console.log('Configs were retrieved from the backend and activated.'); - } else { - console.log('No configs were fetched from the backend, and the local configs were already activated'); - } - }); +remoteConfig().settings.minimumFetchIntervalMillis = 30000; ``` -### Reading values +## Reading parameters values + +To read the fetched and activated parameters in your app, you can [Read a single parameter](#read-a-single-parameter) or [Read all parameters at once](#read-all-parameters-at-once). + +### Read a single parameter -With the defaults set and the remote values fetched from Firebase, we can now use the [getValue](#getvalue) method to get the value and use several methods to retrieve the value. +To read a single parameter value from the activated parameter values, call the [getValue](#getvalue) method on the Remote Config object. The [getValue](#getvalue) method returns a [ConfigValue](#configvalue-object) object, which you can use to get the value as a specific type (e.g. string, number, boolean, etc). ```ts import { firebase } from '@nativescript/firebase-core'; @@ -156,7 +184,9 @@ if (awesomeNewFeature.asBoolean() === true) { } ``` -The API also provides a [getAll](#getall) method to read all parameters at once rather than by key: +### Read all parameters at once + +To read all the parameters from the Remote Config object at once, call the [getAll](#getall) method. The [getAll](#getall) method returns an object with the parameter keys as the object keys and the [ConfigValue](#configvalue-object) objects as the object values. ```ts import { firebase } from '@nativescript/firebase-core'; @@ -188,29 +218,6 @@ if (awesomeNewFeature.getSource() === 'remote') { console.log('Parameter value was from a locally cached value.'); } ``` - -### Set a minimum fetch interval - -Although Remote Config is a data storage, it is not designed for frequent reads. By default, Firebase caches the parameters for 12 hours. By design, this prevents the values from being able to change frequently and potentially causes users confusion. - -- To set a different minimum fetch interval, pass it, in seconds, to the [fetch](#fetch) method: - -```ts -import { firebase } from '@nativescript/firebase-core'; -// Fetch and cache for 5 minutes -await firebase().remoteConfig().fetch(300); -``` - -- To bypass caching fully, you can pass a value of `0`. -> **Note** Be warned Firebase may start to reject your requests if values are requested too frequently. - -- You can also apply a global cache frequency by setting the `minimumFetchIntervalMillis` property of the `RemoteConfigSettings` object to the number of milliseconds to cache the values for. This can be done in the bootstrap file before the app starts: - -```ts -import { firebase } from '@nativescript/firebase-core'; -remoteConfig().settings.minimumFetchIntervalMillis = 30000; -``` - ## API ### RemoteConfig class @@ -306,7 +313,7 @@ import { firebase } from '@nativescript/firebase-core'; await firebase().remoteConfig().fetch(expirationDurationSeconds); ``` -Fetches configs, adhering to the default or specified minimum fetch interval. For more information, see [fetch()](https://firebase.google.com/docs/reference/android/com/google/firebase/remoteconfig/FirebaseRemoteConfig#fetch(long)) on the Firebase website. +Fetches parameter values from the Remote Config backend, adhering to the default or specified minimum fetch interval. For more information, see [fetch()](https://firebase.google.com/docs/reference/android/com/google/firebase/remoteconfig/FirebaseRemoteConfig#fetch(long)) on the Firebase website. | Parameter | Type | Description | | --- | --- | --- |