Code Climate Build Status

BookingSync Engine

Requirements

This engine requires Rails >= 4.0.0 and Ruby >= 2.0.0.

Documentation

API documentation is available at rdoc.info.

Installation

BookingSync Engine works with Rails 4.0 onwards and Ruby 2.0 onwards. To get started, add it to your Gemfile with:

gem 'bookingsync-engine'

Then bundle install:

bundle install

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 Account class:

rails g migration AddOAuthFieldsToAccounts provider:string uid:integer:index \
  name:string oauth_access_token:string oauth_refresh_token:string \
  oauth_expires_at:string

and migrate:

rake db:migrate

And include BookingSync::Engine::Account in your Account model:

class  < ActiveRecord::Base
  include BookingSync::Engine::Model
end

Configuration

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

The engine is set up by default to work with Embedded app for the BookingSync app store. This means that the OAuth flow will redirect using javascript redirect to break out of the iframe.

Embedded 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:

after_action :allow_bookingsync_iframe

Standalone apps

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:

BookingSync::Engine.standalone!

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 before_filter:

before_action :authenticate_account!

It will make sure an account is authenticated (using OAuth).

To retrieve the current signed-in account, this helper is available:

Securing applications

Session cookies

You should make sure session cookies for you application have the secure 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 session_store.rb initializer:

Rails.application.config.session_store :cookie_store,
  key: '_your-app_session', secure: true

Contributing

We would love to see you contributing. Please, just follow the guidelines from https://github.com/BookingSync/contributing

Testing

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