bg-common 0.1.0

data/README.md

@@ -0,0 +1,274 @@
+# BG::Common
+
+A Ruby library of common behaviors, especially for Ruby on Rails applications.
+
+# Table of Contents
+
+<!-- MarkdownTOC depth=4 autolink=true bracket=round -->
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [I. Basic Auth](#i-basic-auth)
+  - [II. Analytics](#ii-analytics)
+    - [Google Analytics](#google-analytics)
+    - [Intercom](#intercom)
+    - [Keen.io](#keenio)
+- [Development](#development)
+- [Contributing](#contributing)
+
+<!-- /MarkdownTOC -->
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'bg-common'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install bg-common
+
+## Usage
+
+### I. Basic Auth
+
+To hide an app from bots and people who are trying to troll us, we want to hide the app behind a "firewall". Typically we want to do that for staging or any other environment that is not public.
+
+The best way to do that is to put the app behind Basic Auth.
+
+To enable Basic Auth, add the following as an ENV variable:
+
+```
+BASIC_AUTH_ENABLED=true
+BASIC_AUTH_USERNAME=user
+BASIC_AUTH_PASSWORD=password
+```
+
+make sure to change `user` and `password` to something a bit more secure!
+
+### II. Analytics
+
+This library provides a common interface for sending events to different analytics/user tracking platforms (eg. Google Analytics, Intercom, Keen.io).
+
+**Caveat:** Although the interface is the same, the data sent to each one is different. Some accept custom attributes, and others don't. So for that reason, you will still need to have knowledge of what each platform accepts as params. Those are explained below for each one of them.
+
+To track an event on all of the supported platforms, all you need to do is call the `Tracker` class, with the proper params.
+
+```ruby
+require 'bg/common/analytics'
+
+user = current_user # or whatever the logged in user object is in your case.
+
+# Track on the various analytics tools:
+tracker_data = {
+  ga: {
+    category: 'Users',
+    action:   'User Logged In',
+    label:    user.email,
+    value:    nil,
+    bounce:   false,
+  },
+  intercom: {
+    event_name: 'user-logged-in',
+    created_at: Time.now.to_i,
+    email:      user.email,
+  },
+  keen: {
+    event: 'user_logged_in',
+    data:  {
+      user_id: user.id,
+      email:   user.email,
+      date:    Time.now.utc.to_i, # Cannot be a time object, so cast as
+                                  # Integer or String because of the following:
+                                  # ActiveJob::SerializationError
+                                  # (Unsupported argument type: Time)
+    }
+  }
+}
+
+BG::Common::Analytics::Tracker.new.call(tracker_data)
+```
+
+The call above detects whether you have background jobs enabled by checking if the `ActiveJob::Base` class is defined. If it is, it will execute the calls to each platform by creating a background job for each one. This is beneficial to make sure that these non critical third party calls do not block the user action.
+
+If `ActiveJob::Base` is not defined, the calls would be perform inline.
+
+**What if I do not want Google to creep on my users???**
+
+Well that's easy, do not enable it. For each supported platform, the gem determines if it's enabled by checking on a couple of things (see the sections below for more detail) and if the checks pass, then that platform is included in the tracker call. Otherwise, that platform is ignored.
+
+**Oh boy! That's a long namespace!**
+
+`BG::Common::Analytics::Tracker` is a lot to type, but we expect that you will setup your class that will inherit from this one, and create your own methods that determine how the data is structured for each event. Something like this:
+
+```ruby
+class MyAnalytics < BG::Common::Analytics::Tracker
+  def track_login user
+    tracker_data = {
+      ga: {
+        category: 'Users',
+        action:   'User Logged In',
+        label:    user.email,
+        value:    nil,
+        bounce:   false,
+      },
+      intercom: {
+        event_name: 'user-logged-in',
+        created_at: Time.now.to_i,
+        email:      user.email,
+      },
+      keen: {
+        event: 'user_logged_in',
+        data:  {
+          user_id: user.id,
+          email:   user.email,
+          date:    Time.now.utc.to_i,
+        }
+      }
+    }
+
+    call tracker_data
+  end
+end
+
+MyAnalytics.new.track_login user
+```
+
+or if you want to build something more extendable:
+
+```
+# lib/my_app/analytics/base.rb
+module MyApp
+  module Analytics
+    class Base < ::BG::Common::Analytics::Tracker
+      def initialize user:, additional_data:
+        super()
+
+        @user            = user
+        @additional_data = additional_data
+      end
+
+      def call
+        default_keen_data = extract_default_keen_data user: @user, additional_data: @additional_data
+        extra_keen_data   = extract_extra_keen_data additional_data: @additional_data
+
+        tracker_data = {
+          ga:       { ... },
+          intercom: { ... },
+          keen:     {
+            event: event_name,
+            data:  default_keen_data.merge(extra_keen_data),
+          },
+        }
+
+        super tracker_data
+      end
+
+      private
+
+      def extract_extra_keen_data additional_data:
+        raise NotImplementedError
+      end
+
+      def event_name
+        raise NotImplementedError
+      end
+
+      def extract_default_keen_data user:, additional_data:
+        {
+          user_id:    user.id,
+          user_email: user.email,
+          datestamp:  Time.now.utc.to_i,
+        }
+      end
+    end
+  end
+end
+
+# lib/my_app/analytics/comment.rb
+module MyApp
+  module Analytics
+    module Comment
+      class Create < Base
+        private
+
+        def extract_extra_keen_data additional_data:
+          {
+            comment_id: additional_data[:comment_id]
+          }
+        end
+
+        def event_name
+          'new_comment'
+        end
+      end
+    end
+  end
+end
+
+# in comments_controller.rb
+MyApp::Analytics::Comment::Create.new(user: current_user, additional_data: {
+  comment_id: @comment.id,
+}).call
+```
+
+#### Google Analytics
+
+All you need to have GA support is to add the `gabba` gem to your `Gemfile`, and the following `ENV` variables:
+
+```ruby
+# Gemfile
+gem 'gabba'
+```
+
+```
+# .env
+GA_TRACKER_CODE=...
+GA_DOMAIN=...
+```
+
+which are required to configure the GA client.
+
+#### Intercom
+
+All you need to have Intercom support is to include the `intercom` gem:
+
+```ruby
+# Gemfile
+gem 'intercom'
+```
+
+**PS:** make sure you configure the gem in the initializer as specified by the Intercom docs.
+
+#### Keen.io
+
+All you need to have GA support is to add the `keen` gem to your `Gemfile`, and the following `ENV` variables:
+
+```ruby
+# Gemfile
+gem 'keen'
+```
+
+```
+# .env
+KEEN_PROJECT_ID=...
+```
+
+which are required to configure the Keen client.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/bg-common. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :default => :test

data/app/jobs/bg/common/analytics/ga_event_job.rb

@@ -0,0 +1,13 @@
+module BG
+  module Common
+    module Analytics
+      class GAEventJob < ::ActiveJob::Base
+        queue_as :analytics
+
+        def perform data
+          GA::Client.new.call data
+        end
+      end
+    end
+  end
+end

data/app/jobs/bg/common/analytics/intercom_create_user_job.rb

@@ -0,0 +1,15 @@
+module BG
+  module Common
+    module Analytics
+      class IntercomCreateUserJob < ::ActiveJob::Base
+        queue_as :analytics
+
+        def perform data
+          Intercom::Client.new.make_intercom_call do |client|
+            client.users.create data
+          end
+        end
+      end
+    end
+  end
+end

data/app/jobs/bg/common/analytics/intercom_event_job.rb

@@ -0,0 +1,13 @@
+module BG
+  module Common
+    module Analytics
+      class IntercomEventJob < ::ActiveJob::Base
+        queue_as :analytics
+
+        def perform data
+          Intercom::Client.new.call data
+        end
+      end
+    end
+  end
+end

data/app/jobs/bg/common/analytics/intercom_export_users_job.rb

@@ -0,0 +1,15 @@
+module BG
+  module Common
+    module Analytics
+      class IntercomExportUsersJob < ::ActiveJob::Base
+        queue_as :analytics
+
+        def perform data
+          Intercom::Client.new.make_intercom_call do |client|
+            client.users.submit_bulk_job(create_items: data)
+          end
+        end
+      end
+    end
+  end
+end

data/app/jobs/bg/common/analytics/intercom_update_users_job.rb

@@ -0,0 +1,17 @@
+module BG
+  module Common
+    module Analytics
+      class IntercomSyncUsersJob < ::ActiveJob::Base
+        queue_as :analytics
+
+        def perform
+          users = User.all
+
+          users.each do |user|
+            Analytics::Intercom.update_user user
+          end unless users.blank?
+        end
+      end
+    end
+  end
+end

data/app/jobs/bg/common/analytics/keen_event_job.rb

@@ -0,0 +1,13 @@
+module BG
+  module Common
+    module Analytics
+      class KeenEventJob < ::ActiveJob::Base
+        queue_as :analytics
+
+        def perform event, data
+          Keen::Client.new.call event, data
+        end
+      end
+    end
+  end
+end

data/bg-common.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'bg/common/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "bg-common"
+  spec.version       = BG::Common::VERSION
+  spec.authors       = ["Youssef Chaker"]
+  spec.email         = ["youssef@bearandgiraffe.com"]
+
+  spec.summary       = 'A Ruby library of common behaviors, especially for Ruby on Rails applications.'
+  spec.description   = 'A Ruby library of common behaviors, especially for Ruby on Rails applications.'
+  spec.homepage      = 'https://github.com/bearandgiraffe/bg-common'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.14'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'minitest', '~> 5.0'
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "bg/common"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/bg/common/analytics/ga.rb

@@ -0,0 +1,12 @@
+require_relative 'google_analytics/client'
+require_relative 'google_analytics/events'
+
+module BG
+  module Common
+    module Analytics
+      module GA
+        extend Events
+      end
+    end
+  end
+end

data/lib/bg/common/analytics/google_analytics/client.rb

@@ -0,0 +1,27 @@
+module BG
+  module Common
+    module Analytics
+      module GA
+        class Client
+          def initialize
+            @ga = ::Gabba::Gabba.new(ENV['GA_TRACKER_CODE'], ENV['GA_DOMAIN'])
+          end
+
+          def ga
+            @ga ||= ::Gabba::Gabba.new(ENV['GA_TRACKER_CODE'], ENV['GA_DOMAIN'])
+          end
+
+          def call data
+            ga.event(
+              data[:category],
+              data[:action],
+              data[:label],
+              data[:value],
+              data[:bounce] || false
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bg/common/analytics/google_analytics/events.rb

@@ -0,0 +1,40 @@
+#
+# Module that wraps the GA events API to create specific events related
+# to actions from the app.
+#
+module BG
+  module Common
+    module Analytics
+      module GA
+        module Events
+          #
+          # Creates an event in GA
+          #
+          # @param data, Hash
+          #
+          # The data param includes the information for the event to register on GA.
+          # It should have the following attributes:
+          #
+          # category: String
+          # action:   String
+          # label:    String
+          # value:    Integer
+          # bounce:   Boolean
+          #
+          # more info here:
+          # https://support.google.com/analytics/answer/1033068#Anatomy
+          # https://developers.google.com/analytics/devguides/collection/analyticsjs/events
+          #
+          def create_event data
+            if BG::Common.active_job?
+              GAEventJob.perform_later data
+            else
+              Client.new.call data
+            end
+          end
+        end
+      end
+    end
+  end
+end
+

data/lib/bg/common/analytics/intercom/client.rb

@@ -0,0 +1,39 @@
+module BG
+  module Common
+    module Analytics
+      module Intercom
+        class Client
+          def initialize
+            @intercom = ::Intercom::Client.new(app_id: config.app_id, api_key: config.api_key)
+          end
+
+          def intercom
+            @intercom ||= ::Intercom::Client.new(app_id: config.app_id, api_key: config.api_key)
+          end
+
+          def call data
+            make_intercom_call do |client|
+              client.events.create data
+            end
+          end
+
+          def make_intercom_call &block
+            begin
+              yield self.intercom
+            rescue ::Intercom::IntercomError => e
+              # TODO: report this to newrelic so we won't lose any important
+              # errors that we might have to fix.
+              BG::Common.logger.debug "Intercom call failed: #{e.inspect}"
+            end
+          end
+
+          private
+
+          def config
+            ::IntercomRails.config
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bg/common/analytics/intercom/events.rb

@@ -0,0 +1,36 @@
+#
+# Module that wraps the Intercom events API to create specific
+# events related to app actions.
+#
+module BG
+  module Common
+    module Analytics
+      module Intercom
+        module Events
+          #
+          # Creates an event in Intercom
+          #
+          # @param data, Hash
+          #
+          # The data param includes the information for the event to register on
+          # Intercom. It should have the following attributes:
+          #
+          # event_name: String
+          # created_at: Timestamp
+          # email:      String
+          # metadata:   Object
+          #
+          # more info here: https://doc.intercom.io/api/#submitting-events
+          #
+          def create_event data
+            if BG::Common.active_job?
+              IntercomEventJob.perform_later data
+            else
+              Client.new.call data
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bg/common/analytics/intercom/user.rb

@@ -0,0 +1,67 @@
+#
+# Module that wraps the Intercom users API.
+#
+module BG
+  module Common
+    module Analytics
+      module Intercom
+        module User
+          #
+          # Exports users to Intercom.
+          #
+          # @param limit, Integer, Sets the limit of users to export.
+          #
+          def export_users limit=nil
+            users = ::User.all
+
+            if limit
+              users = users.limit(limit)
+            end
+
+            data = users.map { |user| intercom_user_object user }
+
+            IntercomExportUsersJob.perform_later data
+          end
+
+          #
+          # Creates user in Intercom.
+          #
+          # @param user,    User
+          #
+          def create_user user
+            data = intercom_user_object user
+
+            IntercomCreateUserJob.perform_later data
+          end
+
+          #
+          # Updates user in Intercom.
+          #
+          # @param user,    User
+          #
+          def update_user user
+            create_user user
+          end
+
+          private
+
+          def intercom_user_object user
+            {
+              user_id:           user.id,
+              email:             user.username,
+              name:              user.name,
+              signed_up_at:      user.created_at.to_i,
+              custom_attributes: custom_attributes(user)
+            }
+          end
+
+          def custom_attributes user
+            # Override this method in your app to provide custom attributes
+            # specific to your app to be passed on to Intercom.
+            { }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bg/common/analytics/intercom.rb

@@ -0,0 +1,14 @@
+require_relative 'intercom/client'
+require_relative 'intercom/user'
+require_relative 'intercom/events'
+
+module BG
+  module Common
+    module Analytics
+      module Intercom
+        extend User
+        extend Events
+      end
+    end
+  end
+end

data/lib/bg/common/analytics/keen/client.rb

@@ -0,0 +1,16 @@
+module BG
+  module Common
+    module Analytics
+      module Keen
+        class Client
+          def initialize
+          end
+
+          def call event, data = {}
+            ::Keen.publish event.to_sym, data
+          end
+        end
+      end
+    end
+  end
+end