Skip to content

Latest commit

 

History

History
509 lines (374 loc) · 16.3 KB

README.md

File metadata and controls

509 lines (374 loc) · 16.3 KB
Raw

@nativescript/firebase-remote-config

Contents

Intro

This plugin allows you to use the Firebase Remote Config API in your NativeScript app.

image

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 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.
npm install @nativescript/firebase-remote-config
  1. 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).
import '@nativescript/firebase-remote-config';

Create in-app default parameters

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 and select your project.
  2. On the Remote Config dashboard, click Create configuration to create a parameter.
  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 method.
      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 method. 
      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

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

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');
		}
	});

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 method:
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:
import { firebase } from '@nativescript/firebase-core';
remoteConfig().settings.minimumFetchIntervalMillis = 30000;

Reading parameters values

To read the fetched and activated parameters in your app, you can Read a single parameter or Read all parameters at once.

Read a single parameter

To read a single parameter value from the activated parameter values, call the getValue method on the Remote Config object. The getValue method returns a ConfigValue object, which you can use to get the value as a specific type (e.g. string, number, boolean, etc).

import { firebase } from '@nativescript/firebase-core';

const awesomeNewFeature = firebase().remoteConfig().getValue('awesome_new_feature');

// resolves value to string
if (awesomeNewFeature.asString() === 'enabled') {
	enableAwesomeNewFeature();
}
// resolves value to number
// if it is not a number or source is 'static', the value will be 0
if (awesomeNewFeature.asNumber() === 5) {
	enableAwesomeNewFeature();
}
// resolves value to boolean
// if value is any of the following: '1', 'true', 't', 'yes', 'y', 'on', it will resolve to true
// if source is 'static', value will be false
if (awesomeNewFeature.asBoolean() === true) {
	enableAwesomeNewFeature();
}

Read all parameters at once

To read all the parameters from the Remote Config object at once, call the getAll method. The getAll method returns an object with the parameter keys as the object keys and the ConfigValue objects as the object values.

import { firebase } from '@nativescript/firebase-core';

const parameters = firebase().remoteConfig().getAll();

Object.entries(parameters).forEach((item) => {
	const [key, entry] = item;
	console.log('Key: ', key);
	console.log('Source: ', entry.getSource());
	console.log('Value: ', entry.asString());
});

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:

import { firebase } from '@nativescript/firebase-core';

const awesomeNewFeature: ConfigValue = firebase().remoteConfig().getValue('awesome_new_feature');

if (awesomeNewFeature.getSource() === 'remote') {
	console.log('Parameter value was from the Firebase servers.');
} else if (awesomeNewFeature.getSource() === 'default') {
	console.log('Parameter value was from a default value.');
} else {
	console.log('Parameter value was from a locally cached value.');
}

API

RemoteConfig class

android

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

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

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

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

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

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()

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() on the Firebase website.

ensureInitialized()

import { firebase } from '@nativescript/firebase-core';

await firebase().remoteConfig().ensureInitialized();

fetch()

import { firebase } from '@nativescript/firebase-core';

await firebase().remoteConfig().fetch(expirationDurationSeconds);

Fetches parameter values from the Remote Config backend, adhering to the default or specified minimum fetch interval. For more information, see fetch() on the Firebase website.

Parameter Type Description
expirationDurationSeconds number

fetchAndActivate()

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() on the Firebase website.

getAll()

import { firebase } from '@nativescript/firebase-core';

parameters: Record<string, ConfigValue> = firebase().remoteConfig().getAll();

Returns an object with all the parameters in the Remote Config.

getBoolean()

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 The key of the parameter to get.

getNumber()

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 The key of the parameter to get.

getString()

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 The key of the parameter to get.

getValue()

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 The key of the parameter to get.

reset()

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()

import { firebase } from '@nativescript/firebase-core';

await firebase().remoteConfig().setDefaults(defaults);

Sets default configs from a ConfigDefaults object.

Parameter Type Description
defaults ConfigDefaults The default configs object to set.

ConfigDefaults

interface ConfigDefaults {
	[key: string]: number | string | boolean;
}

setDefaultsFromResource()

import { firebase } from '@nativescript/firebase-core';

await firebase().remoteConfig().setDefaultsFromResource(resourceName);

Sets default configs using an XML resource.

Parameter Type Description
resourceName string The resource name of the XML resource in the package's res folder.

ConfigValue object

This object is returned by the 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

configValue: ConfigValue = firebase().remoteConfig().getValue(key)

configValueAndroid: com.google.firebase.remoteconfig.FirebaseRemoteConfigValue = configValue.android;

Returns an instance of ConfigValue for Android.

ios

configValue: ConfigValue = firebase().remoteConfig().getValue(key)

configValueIOS: FIRRemoteConfigValue = configValue.ios;

Returns an instance of ConfigValue for iOS.

asBoolean()

configValue: ConfigValue = firebase().remoteConfig().getValue(key)

value: boolean = configValue.asBoolean();

Gets the parameter value as a boolean.

asNumber()

configValue: ConfigValue = firebase().remoteConfig().getValue(key)

value: number = configValue.asNumber();

Gets the parameter value as a number.

asString()

configValue: ConfigValue = firebase().remoteConfig().getValue(key)

value: string = configValue.asString();

Gets the parameter value as a string.

getSource()

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