A RubyMotion wrapper for the Firebase SDK.
Adds more rubyesque methods to the built-in classes.
For a Ruby (MRI) Firebase wrapper, check out https://github.com/derailed/bigbertha.
The motion-firebase gem ships with "freeze dried" copies of the Firebase framework. This way we can guarantee that the version of motion-firebase is definitely compatible with the version of Firebase that is included. As new features get announced, we update the gem.
Also, it means that installation is easy! When you compile your RubyMotion project, the Firebase SDK gets included automatically.
Lots of changes in this version: 3.0.md
Firebase.new(url) # it's common to set a global firebase URL. Set it in your app delegate, # and calling `new` will use that default URL. Firebase.url = 'https://your-app.firebaseio.com' Firebase.url # => 'https://your-app.firebaseio.com' Firebase.new # these all work, too: Firebase.url = 'your-app.firebaseio.com' Firebase.url = 'your-app' Firebase.url # => 'https://your-app.firebaseio.com'
firebase[path] firebase[] # childByAutoId firebase['fred'] # childByAppendingPath('fred')
firebase << { key: 'value' } # => firebase.childByAutoId.setValue({ key: 'value'}), returns the new child # Since firebase works with simple objects, this is equivalent to # => firebase.childByAutoId.setValue({ 'key' => 'value'}) # if you want to listen for the completion handler firebase.push({ key: 'value' }) do |error, ref| end # => firebase.childByAutoId.setValue({ 'key' => 'value'}, withCompletionBlock: -> (error, ref) do # end) # set value firebase.value = value firebase.set(value) firebase.set(value) { 'completion block' } firebase.set(value, priority: priority) firebase.set(value, priority: priority) { 'completion block' } # set value of child node firebase['first_name'] = 'fred' # childByAppendingPath('fred').set('fred') # remove value firebase.clear! firebase.clear! { 'completion block' } # priority firebase.priority = priority firebase.priority(priority) firebase.priority(priority) { |error| 'completion block' } # "updating" is used to update some children, but leaving others unchanged. # (set, on the other hand, replaces the value entirely, so using set with a # hash will remove keys that weren't specified in the new hash) firebase.set({ first_name: 'motion', last_name: 'fireball' }) firebase.update(last_name: 'firebase') # only updates last_name, first_name is left unchanged firebase.update(last_name: 'firebase') { |error| 'completion block' } # for comparison: firebase.set(last_name: 'firebase') # first_name is now 'nil'
Events can have the value of:
:child_added, :added, FEventTypeChildAdded :child_moved, :moved, FEventTypeChildMoved :child_changed, :changed, FEventTypeChildChanged :child_removed, :removed, FEventTypeChildRemoved :value, FEventTypeValue
handle = firebase.on(event_type) { |snapshot| 'completion block' } handle = firebase.on(event_type) { |snapshot, previous_sibling_name| 'completion block' } handle = firebase.on(event_type, completion: proc { |snapshot, previous_sibling_name| 'completion block' }, disconnect: proc { 'completion block' } )
Sometimes you just need one to get an update, use once if you don't want to
subscribe to a stream of changes.
firebase.once(event_type) { |snapshot| 'completion block' } firebase.once(event_type) { |snapshot, previous_sibling_name| 'completion block' } firebase.once(event_type, completion: proc { |snapshot, previous_sibling_name| 'completion block' }, disconnect: proc { 'completion block' } )
firebase.off # => firebase.removeAllObservers firebase.off(handle) # => firebase.removeObserverWithHandle(handle)
firebase.start_at(priority) # => firebase.queryStartingAtPriority(priority) firebase.start_at(priority, child: child_name) # => firebase.queryStartingAtPriority(priority, andChildName: child_name) firebase.equal_to(priority) # => firebase.queryEqualToPriority(priority) firebase.equal_to(priority, child: child_name) # => firebase.queryEqualToPriority(priority, andChildName: child_name) firebase.end_at(priority) # => firebase.queryEndingAtPriority(priority) firebase.end_at(priority, child: child_name) # => firebase.queryEndingAtPriority(priority, andChildName: child_name) firebase.limit(limit) # => firebase.queryLimitedToNumberOfChildren(limit)
These methods were added to Firebase in version 2.0.1. NB: You can provide a
block and on: event value to create a listener.
firebase.query(order_by: 'key') # => firebase.queryOrderedByChild('key') firebase.query(first: value) # => firebase.queryLimitedToFirst(value) # create a listener by providing a block and :on value (default is :value if :on # isn't specified) firebase.query(first: value, on: :added) do |snapshot| end firebase.query(last: value) # => firebase.queryLimitedToLast(value) firebase.query(starting_at: value) firebase.query(starting_at: value, child: 'key') # => firebase.queryStartingAtValue(value) # => firebase.queryStartingAtValue(value, childKey: 'key') firebase.query(ending_at: value) firebase.query(ending_at: value, child: 'key') # => firebase.queryEndingAtValue(value) # => firebase.queryEndingAtValue(value, childKey: 'key') firebase.query(equal_to: value) firebase.query(equal_to: value, child: 'key') # => firebase.queryEqualToValue(value) # => firebase.queryEqualToValue(value, childKey: 'key') firebase.query(order_by_key: true) # => firebase.queryOrderedByKey firebase.query(order_by_priority: true) # => firebase.queryOrderedByPriority # and of course these can all be combined into one call: firebase.query( first: 5, starting_at: 'foo', ending_at: 'bar') # => firebase.queryLimitedToFirst(5) # .queryStartingAtValue('foo') # .queryEndingAtValue('bar')
SOO COOL! Play with these, you can easily create a presence system for your real-time app or game.
Firebase.online! Firebase.offline! Firebase.connected? # returns a Firebase ref that changes value depending on connectivity # or you can pass in a block, this block will be called with the connected # state as a bool: handler = Firebase.connected? do |connected| if connected # so awesome end end # you should turn it off when you're done, otherwise you'll have a memory leak Firebase.off(handler) # so what you do is get a ref to the authenticated user's "presence" value. # Then, on_disconnect, set the value to 'false'. firebase.on_disconnect(value) # set the ref to `value` when disconnected firebase.on_disconnect(value) { |error| 'completion block' } firebase.on_disconnect(value, priority: priority) firebase.on_disconnect(value, priority: priority) { |error| 'completion block' } # this removes the value on disconnect firebase.remove_on_disconnect # which is the same as, but not as obvious: firebase.on_disconnect(nil) firebase.remove_on_disconnect { |error| 'completion block' } firebase.on_disconnect({ child: values }) firebase.on_disconnect({ child: values }) { |error| 'completion block' } # sometimes you need to cancel these 'on_disconnect' operations firebase.cancel_disconnect firebase.cancel_disconnect { |error| 'completion block' }
firebase.transaction do |data| current_value = data.value current_value += 1 FTransactionResult.successWithValue(current_value) end firebase.transaction(local: false) do |data| #... end firebase.transaction( completion: proc { |error, committed, snapshot| } ) do |data| current_value = data.value current_value += 1 FTransactionResult.successWithValue(current_value) end firebase.transaction( transaction: proc { |data| 'transaction block' }, completion: proc { |error, committed, snapshot| } local: true || false, )
firebase.to_s firebase.inspect
firebase.parent firebase.root firebase.name
Firebase.dispatch_queue=(queue) Firebase.sdkVersion Motion::Firebase::SdkVersion # this string is more human readable than sdkVersion
Most of the authentication methods can be called statically as long as you have
set a default Firebase.url
Firebase.authenticated? # => true/false # you pretty much always need to hold a reference to the "handler" auth_handler = Firebase.authenticated? do |auth_data| if auth_data # authenticated! else # not so much end end # turn off the handler, otherwise, yeah, memory leaks. Firebase.off_auth(auth_handler)
Firebase.authenticate(token) do |error, auth_data| end
Firebase.logout
This is the most common way to login. It allows Firebase to create users and tokens.
Firebase.create_user(email: 'hello@example.com', password: '12345') { |error, auth_data| } Firebase.remove_user(email: 'hello@example.com', password: '12345') { |error, auth_data| } Firebase.login(email: 'hello@example.com', password: '12345') { |error, auth_data| } Firebase.login_anonymously { |error, auth_data| } Firebase.update_user(email: 'hello@example.com', old_password: '12345', new_password: '54321') { |error, success| } auth_data.uid # is a globally unique user identifier auth_data.token # can be stored (in a keychain!) to authenticate the same user again later
See https://www.firebase.com/docs/ios/api/#fauthdata_properties for other
auth_data properties.
This Facebook helper is a port of the Objective-C code from https://www.firebase.com/docs/ios/guide/login/facebook.html.
Firebase.open_facebook_session( permissions: ['public_profile'], # these are the default values. if allow_login_ui: true, # you're OK with them, they are ) do |error, auth_data| # optional, so just provide a block. end
This Twitter helper is a port of the Objective-C code from
https://www.firebase.com/docs/ios/guide/login/twitter.html. You should read
that page to see how Firebase recommends handling multiple accounts. It's a
little streamlined here, since open_twitter_session returns a block that you
can call with the chosen account.
# it's nice to be able to set-and-forget the twitter_api_key (in your # application delegate, for example) Firebase.twitter_api_key = 'your key!' # You must set Firebase.url=, or call open_twitter_session on an existing # Firebase ref. The first step is to get the Twitter accounts on this # device. Even if there is just one, you need to "choose" it here. Also, # you can pass the twitter api_key as an option, otherwise this method will # use Firebase.twitter_api_key Firebase.open_twitter_session(api_key: 'your key!') do |error, accounts, next_step| # next_step is a block you call with the chosen twitter account and a # firebase handler for the authentication success or failure if error # obviously do some stuff here else present_twitter_chooser(accounts, next_step) do |error, auth_data| # this block is passed to next_step in present_twitter_chooser if error # bummer else # awesome! end end else end def present_twitter_chooser(accounts, next_step, &firebase_handler) if accounts.length == 1 next_step.call(accounts[0], &firebase_handler) else # present a controller or action sheet or something like that ... awesome twitter account chooser code ... next_step.call(account, &firebase_handler) end end
Firebase doesn't provide much help on this one. I'm not even sure how to get
a github access token from the user... but anyway here's the motion-firebase
code based on https://www.firebase.com/docs/ios/guide/login/github.html.
Firebase.github_token = 'github oauth token' Firebase.open_github_session do |error, auth_data| end
This process is more involved, and relies on the GooglePlus framework. I didn't take the time to port the code this time, but I hope someone does someday! π
You can read Firebase's instructions here: https://www.firebase.com/docs/ios/guide/login/google.html
Firebase.google_token = 'google oauth token' Firebase.open_google_session do |error, auth_data| end
Usually you will use the helpers from above, but here are some lower level methods:
# using a token firebase_ref.login_to_oauth(provider, token: token) do |error, auth_data| .. end firebase_ref.login_to_oauth(provider, token) do |error, auth_data| .. end # using parameters firebase_ref.login_to_oauth(provider, oauth_token: token, oauth_token_secret: secret) do |error, auth_data| .. end params = { ... } firebase_ref.login_to_oauth(provider, params) do |error, auth_data| .. end # which is a wrapper for these SDK methods: firebase_ref.authWithOAuthProvider(provider, token: token, withCompletionBlock: block) firebase_ref.authWithOAuthProvider(provider, parameters: params, withCompletionBlock: block) # Again, the `open_*_session` methods are even more convenient. firebase_ref.login_to_facebook(facebook_access_token, &block) firebase_ref.login_to_twitter(token: token, secret: secret, &block) firebase_ref.login_to_github(github_oauth_token, &block) firebase_ref.login_to_google(google_oauth_token, &block)