This engine requires Rails
>= 5.0.0 and Ruby
BookingSync Engine works with Rails 4.2 onwards and Ruby 2.2 onwards. To get started, add it to your Gemfile with:
Then bundle install:
Then mount BookingSync Authorization routes inside
mount :: => '/'
This will add the following routes:
BookingSync Engine uses the
Account model to authenticate each BookingSync Account, if you do not have an
Account model yet, create one:
rails g model Account
Then, generate a migration to add OAuth fields for the
rails g migration AddOAuthFieldsToAccounts provider:string synced_id:integer:index \ name:string oauth_access_token:string oauth_refresh_token:string \ oauth_expires_at:string
BookingSync::Engine::Account in your
class Account < ActiveRecord::Base include :::: end
When saving new token, this gem uses a separate thread with new db connection to ensure token save (in case of a rollback in the main transaction). To make room for the new connections, it is recommended to increase db
pool size by 2-3.
The engine is configured by the following ENV variables:
BOOKINGSYNC_URL- the url of the website, should be
BOOKINGSYNC_APP_ID- BookingSync Application's Client ID
BOOKINGSYNC_APP_SECRET- BookingSync Application's Client Secret
BOOKINGSYNC_VERIFY_SSL- Verify SSL (available only in development or test). Default to false
BOOKINGSYNC_SCOPE- Space separated list of required scopes. Defaults to nil, which means the public scope.
You might want to use dotenv-rails to make ENV variables management easy.
Embedded vs Standalone apps
Embedded apps will need to allow BookingSync to load them in an iframe.
This only has to be applied to the part of the application used in BookingSync
You can use the following helper in your controller to do just that:
Standalone applications will be working outside of BookingSync website. While it's not the recommended approach, some applications can benefit from this.
To make your application standalone, you must set the standalone mode by adding the following code to an initializer:
Authentication in apps
BookingSync Engine will create some helpers to use inside your controllers and views.
To set up a controller with BookingSync account authentication, just add this
It will make sure an account is authenticated (using OAuth2).
New authorization process
If the user is not currently authenticated, 3 responses can be expected:
1) Through Ajax requests
By Ajax request, we consider them when the
X-Requested-With header contains
In this case, the authorization path will be returned a plain text with a 401 Unauthorized status.
2) Embedded Application
Embedded applications will be given a script tag forcing them to change their parent location to the authorization path. This is necessary so the authorization happens in the main window, not within an iFrame.
3) Standalone Application
Standalone applications will simply be redirected to the authorization path.
Accessing the current account
To retrieve the current signed-in account, this helper is available:
You should make sure session cookies for you application have the
flag. This will be done by Rails automatically if you have configured
your environment with
config.force_ssl = true. If not, you can change your
Rails.application.config.session_store :cookie_store, key: '_your-app_session', secure: true
We would love to see you contributing. Please, just follow the guidelines from https://github.com/BookingSync/contributing
By default, your tests will run against the Rails version used in the main Gemfile.lock, to test against all supported Rails version, please run the tests with Appraisals with:
appraisal rake spec