Firebase JSON REST access library for Apps Script

The BigQuiz app uses Firebase for keep track of the question, category and game scores of individual players. In Firebase custom authentication with goa I showed how to use Goa to manage authentication for Firebase. This firebase access library works with goa, or you can use a different JWT generator if you aleady have one. 

cGoa library is available with this key, and on github.

MZx5DzNPsYjVyZaR67xXJQai_d-phDA33

cFirebase library is available with this key, and on github.

MBz9GwQn5jZOg-riXY3pBTCz3TLx7pV4j

Why Firebase?

I had originally planned to use the JSON API for Google Game Play Services but I really think Google have got it all wrong for this API.
  • The Game play services API is extremely complicated to set up. There are multiple consoles and credentials, and registrations and thumbnail images and other boring stuff to go through – even if you just want to try it out – I think many people who may otherwise go on to use it, are going to be put off by this and just do something else – as I did.
  • There is a $25 registration fee to get started. Even if you just want to have a look at it to see if you want to use it. Surely marketing 101 says that you don’t charge people to have a look at something. By all means charge if it gets used, but not just to look. 
If I’d persevered and swallowed the registration charge and worked through all the complex console stuff, then I probably would have got game play services to work, but a simple solution with Firebase is just fine for my demo BigQuiz app
 
Try the App here.
 
So this very simple library happened because the entry barrier for Game Play Services was just too high to be bothered with. 
 
cFireBase supports returning both promises and regular results (the default).

Getting a handle to the database

The first step is to get credentials set up. I won’t go through that again, but it’s very simple and covered in Firebase custom authentication with goa. Here’s how I get a handle to my database in BigQuiz app
ns.init = function () {
    
    // make a goa and get a firebase handle
    var goa =  cGoa.make (Demo.PACKAGE_PLAY.name,Demo.PACKAGE_PLAY.props);
    
    // use this handle for everything
    ns.handle = new cFireBase.FireBase().setAuthData (goa);
    
    return ns;
  };  
 
cFirebase also has its own JWT generator, which you can use if not using cGoa. Note that you’ll have to manage your own secret and rules if you do this.
 
 var handle = new cFireBase
    .FireBase()
    .generateJWT('https://bigquiz.firebaseio.com/',{uid:"bruce"},'aK.....h0h');
 
If not using goa and have your own JWT generator, then you can set up a handle like this.
var handle = new cFireBase.FireBase().setAuthData ( {
       root:"your firebase url",  
       key:your JWT authorization string  
    });

Library methods

If you already use Firebase, you’ll know that the url is used for queries. I’ll use this snippet from the database for the examples
 
 

MethodExampleDescription
gethandle.get()get all the data
gethandle.get (‘players/112066118406610145134/ games/jeopardy/categories/AROUND%20THE%20WORLD/summary’)get the object at the given location
puthandle.put (newObject, ‘players/112066118406610145134/
games/jeopardy/categories/AROUND%20THE%20WORLD/summary’)
the new object replaces the data at the given location
posthandle.post (newObject, ‘players/112066118406610145134/
games/jeopardy/categories/AROUND%20THE%20WORLD/summary’)
the new object adds to the data at the given location. This is how firebase deals with arrays
patchhandle.patch (partialObject, ‘players/112066118406610145134/
games/jeopardy/categories/AROUND%20THE%20WORLD/summary’)
the data at the given location is partially updated with the values inthe partial object
removehandle.remove (‘players/112066118406610145134’)Remove the data at the given location. this would remove all data for the selected player.
removeAllhandle.removeAll()remove all the data in the database
setAuthDatahandle.setAuthData (goa)set the root and key using a goa object
setAuthData handle.setAuthData ({key:jwt,root:”https://bigquiz.firebase.io”})
setPromiseModehandle.setPromiseMode(true)

Responses

All data requests return an object with these properties. Exponential backoff is automatically applied to all requests.
 
 property description
 ok true if everything has worked fine
 data the data returned from firebase
 response the httprresponse from the request
 path the url that was fetched from

Promise mode

By default, a request like this will result in a response as above.
var result = handle.get();
 
However it is possible to use Promise mode in order to return a promise rather than a result. This can sometimes be more convenient as described in Using es6 promises server side in Apps Script, although since Apps Script is currently not asynchonous, there are no performance benefits currently (but  preparing for the future is never a bad thing).
Promise mode is turned on like this
 
handle.setPromiseMode (true);
 
and responses will be delivered like this
 
handle.get()
.then (
  function (result) {
    // this is a response like the one documented above
  },
 function (err) {
   // deal with the error
 }
);

The code

The polyfill for Using es6 promises server side in Apps Script is inlined also, but not shown here. The full code is available on github.

cFireBase created by GasGit automation
https://github.com/brucemcpherson/cFireBase
1 forks.
2 stars.
0 open issues.
Recent commits:

 

For more like this, see Google Apps Scripts snippets