nativescript-plugin-firebase

NativeScript Firebase plugin

The leading realtime app platform (Database, Auth & Hosting). Docs here.

If you can spare 41 seconds, please check this video of the demo app in action:

Use when

• you need to store JSON data in the cloud,
• you want to sync that data to other devices and platforms,
• you want to optionally protect that data by having users log in,
• you want to update clients at the moment the data changes (think chat and multiplayer games).

Prerequisites

Head on over to https://console.firebase.google.com/ and sign up for a free account. Your first 'Firebase' will be automatically created and made available via a URL like https://n-plugin-test.firebaseio.com.

Open your Firebase project at the Google console and click 'Add app' to add an iOS and / or Android app. Follow the steps (make sure the bundle id is the same as your nativescript.id in package.json and you'll be able to download:

• GoogleService-Info.plist which you'll add to your NativeScript project at app/App_Resources/iOS/GoogleService-Info.plist
• google-services.json which you'll add to your NativeScript project at platforms/android/google-services.json

Installation

From the command prompt go to your app's root folder and execute:

tns plugin add nativescript-plugin-firebase

Android

Install packages 'Google Play Services' and 'Google Repository' in your Android SDK Manager

Open app/App_Resources/Android/app.gradle

• Add applicationId "com.example.app" to the defaultConfig node (change the id to the same as in your app's package.json), so it becomes:

android {
    ...
    defaultConfig {
        applicationId "com.example.app"
        ...
    }
}

Open platforms/android/build.gradle

• Near the top there's a dependencies section, add classpath "com.google.gms:google-services:3.0.0" so it becomes something like:

  dependencies {
    classpath "com.android.tools.build:gradle:1.5.0"
    classpath "com.google.gms:google-services:3.0.0"
  }

• Add the very bottom of the same file add apply plugin: "com.google.gms.google-services"

Usage

If you want a quickstart, clone our demo app (the one in the YouTube video). And here's the comprehensive list of supported functions:

init

  var firebase = require("nativescript-plugin-firebase");

  firebase.init({
    persist: true, // Allow disk persistence. Default false.
    onAuthStateChanged: function(data) { // optional but useful to immediately re-logon the user when he re-visits your app
      console.log(data.loggedIn ? "Logged in to firebase" : "Logged out from firebase");
      if (data.loggedIn) {
        console.log("user's email address: " + (data.user.email ? data.user.email : "N/A"));
      }
    }
  }).then(
      function (instance) {
        console.log("firebase.init done");
      },
      function (error) {
        console.log("firebase.init error: " + error);
      }
  );

All further examples assume firebase has been required. Also, all functions support promises, but we're leaving out the .then() stuff for brevity where it doesn't add value.

getRemoteConfig

Since plugin version 3.2.0 you can retrieve 'Remote Config' properties. This feature lets you configure parameters in your Firebase instance like these:

Using this function you can retrieve the current values of the remote properties so you can change app behavior on the fly easily (feature toggles for instance).

  firebase.getRemoteConfig({
    developerMode: false, // play with this boolean to get more frequent updates during development
    cacheExpirationSeconds: 600, // 10 minutes, default is 12 hours.. set to a lower value during dev
    properties: [{
      key: "holiday_promo_enabled",
      default: false
    },
    {
      key: "coupons_left",
      default: 100
    },
    {
      key: "double_or_nothing",
      default: 9.99
    }]
  }).then(
      function (result) {
        console.log("Remote Config last fetched at " + result.lastFetch);
        console.log("Remote Config: " + JSON.stringify(result.properties));
        console.log("Remote Config property 'coupons_left': " + result.properties.coupons_left);
      }
  );

setValue

Data is stored as JSON data at a specific path (which is appended to the URL you passed to init). If you want to add data to a known path use this, otherwise use push (see below).

The plugin will take care of serializing JSON data to native data structures.

  // to store a JSON object
  firebase.setValue(
      '/companies',
      {'foo':'bar'}
  );

  // to store an array of JSON objects
  firebase.setValue(
      '/companies',
      [
        {name: 'Telerik', country: 'Bulgaria'},
        {name: 'Google', country: 'USA'}
      ]
  );

push

This function will store a JSON object at path <Firebase URL>/users/<Generated Key>

  firebase.push(
      '/users',
      {
        'first': 'Eddy',
        'last': 'Verbruggen',
        'birthYear': 1977,
        'isMale': true,
        'address': {
          'street': 'foostreet',
          'number': 123
        }
      }
  ).then(
      function (result) {
        console.log("created key: " + result.key);
      }
  );

query

Firebase supports querying data and this plugin does too, since v2.0.0.

Let's say we have the structure as defined at setValue, then use this query to retrieve the companies in country 'Bulgaria':

    var onQueryEvent = function(result) {
        // note that the query returns 1 match at a time
        // in the order specified in the query
        if (!result.error) {
            console.log("Event type: " + result.type);
            console.log("Key: " + result.key);
            console.log("Value: " + JSON.stringify(result.value));
        }
    };

    firebase.query(
        onQueryEvent,
        "/companies",
        {
            // set this to true if you want to check if the value exists or just want the event to fire once
            // default false, so it listens continuously
            singleEvent: true,
            // order by company.country
            orderBy: {
                type: firebase.QueryOrderByType.CHILD,
                value: 'country' // mandatory when type is 'child'
            },
            // but only companies named 'Telerik'
            // (this range relates to the orderBy clause)
            range: {
                type: firebase.QueryRangeType.EQUAL_TO,
                value: 'Bulgaria'
            },
            // only the first 2 matches
            // (note that there's only 1 in this case anyway)
            limit: {
                type: firebase.QueryLimitType.LAST,
                value: 2
            }
        }
    );

For supported values of the orderBy/range/limit's type properties, take a look at the firebase-common.d.ts TypeScript definitions in this repo.

update

Changes the values of the keys specified in the dictionary without overwriting other keys at this location.

  firebase.update(
      '/companies',
      {'foo':'baz'}
  );

addChildEventListener

To listen for changes in your database you can pass in a listener callback function. You get to control which path inside you database you want to listen to, by default it's / which is the entire database.

The plugin will take care of serializing native data structures to JSON data.

  var onChildEvent = function(result) {
    console.log("Event type: " + result.type);
    console.log("Key: " + result.key);
    console.log("Value: " + JSON.stringify(result.value));
  };

  // listen to changes in the /users path
  firebase.addChildEventListener(onChildEvent, "/users");

addValueEventListener

The difference with addChildEventListener is explained here. The link is for the iOS SDK, but it's the same for Android.

  var onValueEvent = function(result) {
    console.log("Event type: " + result.type);
    console.log("Key: " + result.key);
    console.log("Value: " + JSON.stringify(result.value));
  };

  // listen to changes in the /companies path
  firebase.addValueEventListener(onValueEvent, "/companies");

remove

You can remove the entire database content by passing in '/' as param, but if you only want to wipe everything at '/users', do this:

  firebase.remove("/users");

login

v 1.1.0 of this plugin adds the capability to log your users in, either

• anonymously,
• by email and password, or
• using a custom token,
• using Facebook (experimental)

You need to add support for those features in your Firebase instance at the 'Login & Auth' tab.

You can expect more login mechanisms to be added in the future.

Listening to auth state changes

As stated here

The recommended way to get the current user is by setting a listener on the Auth object

To listen to auth state changes you can register a listener like this (you may have done this already during init (see above):

	var listener = {
    onAuthStateChanged: function(data) {
      console.log(data.loggedIn ? "Logged in to firebase" : "Logged out from firebase");
      if (data.loggedIn) {
        console.log("User info", data.user);
      }
    },
    thisArg: this
  };

  firebase.addAuthStateListener(listener);

To stop listening to auth state changed:

  firebase.removeAuthStateListener(listener);

To check if already listening to auth state changes

  hasAuthStateListener(listener);

Anonymous login

  firebase.login({
    // note that you need to enable anonymous login in your firebase instance
    type: firebase.LoginType.ANONYMOUS
  }).then(
      function (result) {
        // the result object has these properties: uid, provider, expiresAtUnixEpochSeconds, profileImageURL, token
        JSON.stringify(result);
      },
      function (errorMessage) {
        console.log(errorMessage);
      }
  )

Password login

  firebase.login({
      // note that you need to enable email-password login in your firebase instance
    type: firebase.LoginType.PASSWORD,
    email: '[e-mail]',
    password: 'theirpassword'
  }).then(
      function (result) {
        // the result object has these properties: uid, provider, expiresAtUnixEpochSeconds, profileImageURL, token
        JSON.stringify(result);
      },
      function (errorMessage) {
        console.log(errorMessage);
      }
  )

Custom login

Use this login type to authenticate against firebase using a token generated by your own backend server. See these instructions on how to generate the authentication token.

  firebase.login({
      // note that you need to generate the login token in your existing backend server
    type: firebase.LoginType.CUSTOM,
    token: token
  }).then(
      function (result) {
        // the result object has these properties: uid, provider, expiresAtUnixEpochSeconds, profileImageURL, token
        JSON.stringify(result);
      },
      function (errorMessage) {
        console.log(errorMessage);
      }
  )

Custom login

Use this login type to authenticate against firebase using a token generated by your own backend server. See these instructions on how to generate the authentication token.

  firebase.login({
      // note that you need to generate the login token in your existing backend server
    type: firebase.LoginType.CUSTOM,
    token: token
  }).then(
      function (result) {
        // the result object has these properties: uid, provider, expiresAtUnixEpochSeconds, profileImageURL, token
        JSON.stringify(result);
      },
      function (errorMessage) {
        console.log(errorMessage);
      }
  )

Facebook login

On iOS this is rock solid, but on Android it's work in progress. If you want to use it for iOS open the Podfile in the plugin's platforms/ios folder and uncomment the Facebook line (you can't miss it).

  firebase.login({
    type: firebase.LoginType.FACEBOOK
  }).then(
      function (result) {
        JSON.stringify(result);
      },
      function (errorMessage) {
        console.log(errorMessage);
      }
  )

Resetting a password

  firebase.resetPassword({
    email: '[e-mail]'
  }).then(
      function () {
        // called when password reset was successful,
        // you could now prompt the user to check his email
      },
      function (errorMessage) {
        console.log(errorMessage);
      }
  )

Changing a password

  firebase.changePassword({
    email: '[e-mail]',
    oldPassword: 'myOldPassword',
    newPassword: 'myNewPassword'
  }).then(
      function () {
        // called when password change was successful
      },
      function (errorMessage) {
        console.log(errorMessage);
      }
  )

logout

Shouldn't be more complicated than:

  firebase.logout();

Known issues (all Android)

On Android you could run into an errors like these:

DexIndexOverflowException

com.android.dex.DexIndexOverflowException: method ID not in..

Congrats, you ran into this issue which can be solved by adding multiDexEnabled true to your app/App_Resources/Android/app.gradle so it becomes something like this:

android {  
  defaultConfig {  
    applicationId "my.package.id"
    multiDexEnabled true
    generatedDensities = []
  }  
  aaptOptions {  
    additionalParameters "--no-version-vectors"  
  }  
}

FirebaseApp with name [DEFAULT] doesn't exist

Another possible error is "FirebaseApp with name [DEFAULT] doesn't exist." which will be solved by placing google-services.json to platforms/android/google-services.json (see above), and making the changes to build.gradle which are mentioned above as well.

Could not find com.google...

And there's this one: "Could not find com.google.firebase:firebase-auth:9.0.2". That means making sure you have the latest Google Repository bits installed. Just run android from a command prompt and install any pending updates.

Found play-services:9.0.0, but version 9.0.2 is needed..

Update your Android bits like the issue above and reinstall the android platform in your project.

Pro tips

See what's happening

It's kinda cool to manipulate data while using multiple devices or your device and the Firebase Dashboard. You will instantly see the update on the other end. The Firebase Dashboard can be reached by simply loading your Firebase URL in a web browser.

Testing your app in the emulator

tns emulate ios --device "iPhone 6s"

tns emulate android --geny "Nexus 6_23"

or start a geny emulator first and do: tns run android

Future work

• Add support for removeEventListener.
• Possibly add more login mechanisms.
• Add other Firebase 3.x SDK features (there's already a few feature requests in the GitHub issue tracker.

Credits

The starting point for this plugin was this great Gist by John Bristowe.

Changelog

3.2.0 (2016, June 19)

Full changelog

SDK versions

If version numbers changed, clean your platform folders to avoid build errors.

• iOS: 3.2.0
• Android: 9.0.2

New

• #56 Remote Config (docs)