thisdata 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fef5e01bc1e5fc5a2ec1298351dd1ac7bfc06a47
-  data.tar.gz: 07881c984c030b535c60b002b50b0a95e2eab107
+  metadata.gz: c769ec94d780ff1f93699730acb971cf09d0d580
+  data.tar.gz: 1d4a7fa9e5b57fc1e6d563d02dd50473f4a1f809
 SHA512:
-  metadata.gz: 81a2cc15499d5777ae5c454e8bd80405339a25bcee6e5cd224dec41624088373a2e509099d89c67243f0961c850fab84e4b3ca0ac732f80514232f19d31419d3
-  data.tar.gz: ec762b91037a20c3f0aa151f87e52db117d187fede934eb89b0a787325fdc15c9f0f5b8c3e5ba7c9bc04bf95db72f531cf7e61f6162754c0af988aa6e3c53cba
+  metadata.gz: b06b6d18354099b7dafb19eb982710606d1cba120fe9b0c99db8f3e7107f0c5a3b748b136eb4a554ad6ac3d73b6bab727a7169da9e146d80dd99b49944f1b01d
+  data.tar.gz: ad687196cfd094456dc13046e76ccc12ca60a92fbc718bf770e0d3c109e6e4f7afa3bffe4cc679338a3b17d56faf78998e737d0b7ebc8c770f1d208d2f61f4ed

data/CHANGELOG

@@ -1,3 +1,12 @@
+# 0.1.3
+
+In the `ThisData::TrackRequest` module, make tracking a bit easier especially
+in the case where `current_user` will return nil - e.g. when someone failed to
+log in to that account.
+
+Also update the documentation and default configuration options to better enable
+people getting started with the ThisData gem.
+
 # 0.1.2
 
 Fix a typo in the configuration generator (`asyc` instead of `async`)

data/README.md

@@ -20,83 +20,124 @@ Or install it yourself as:
 
 ## Usage
 
-### Ruby
+Our API endpoint documentation, tutorials, and sample code can all be found at
+http://help.thisdata.com
+
+### Plain Old Ruby
+
+#### Configuration
 
 Configure ThisData as follows:
 
-```
+```ruby
 ThisData.setup do |config|
-  config.api_key = "API_KEY_HERE"
+  config.api_key = "API_KEY_HERE" # Don't commit your key to source control!
+  config.logger  = Logger.new($stdout)
+  config.async   = false
 end
 ```
 
+See `this_data/configuration.rb` for more options, and some suggested
+Ruby on Rails options in `this_data/generators/install_generator.rb`.
+
+For example, in production you will probably want asynchronous and non-logging
+behaviour.
+
+#### Tracking an Event
+
 You can then track any event by calling `ThisData.track` and passing a Hash which
-contains an event. See examples and required fields on our API documentation:
-http://help.thisdata.com/docs/apiv1events
+contains an event. In the following example, we're tracking a user logging in
+to our app:
+
+```ruby
+ThisData.track(
+  {
+    ip: request.remote_ip,
+    user_agent: request.user_agent,
+    verb: ThisData::Verbs::LOG_IN,
+    user: {
+      id: user.id.to_s,
+      name: user.name,
+      email: user.email
+      mobile: user.mobile
+    }
+  }
+)
+```
 
-**Important!** You should not commit your API keys to source control. Where
-possible, use environment variables / a non-committed secrets file / something
-similar.
 
 ### Rails
 
+#### Set Up
+
+We have a generator which will set some nice configuration options for Ruby on
+Rails users.
+
 Find your API key by going to [ThisData](https://thisdata.com) >
   Integrations > Login Intelligence API.
 
 Run:
 
-    rails g this_data:install YOUR_API_KEY_HERE
+```ruby
+rails g this_data:install YOUR_API_KEY_HERE
+```
 
 The generator will create a file in `config/initializers` called "this_data.rb".
 If you need to do any further configuration or customization of ThisData,
 that's the place to do it!
 
-The ThisData::TrackRequest module can be included in a ActionController, giving
-you a handy way to track requests.
+#### Tracking
 
-e.g. in `app/controllers/application_controller.rb`
-```
-class ApplicationController < ActionController::Base
-  include ThisData::TrackRequest
+**The recommended way to track events is as above - explicitly calling
+`ThisData.track`.**
 
-  ...
-end
-```
+However, we do provide a `ThisData::TrackRequest` module which, when included in
+an ActionController, gives you a simple way to track requests.
 
-and in your sessions controller:
-```
+You include the module, then call `thisdata_track`. Easy!
+
+e.g. in your sessions controller:
+
+```ruby
 class SessionsController < ApplicationController
+  include ThisData::TrackRequest
+
+  def create
+    if User.authenticate(params[:email], params[:password])
+      # Do the things one usually does for a successful auth
 
-  def finalize
-    if login_was_valid?
-      # do login stuff
+      # And also track the login
       thisdata_track
     else
-      thisdata_track('login-denied')
+      # Their credentials are wrong. Are they trying to access
+      # a valid account?
+      if attempted_user = User.find_by(email: params[:email])
+        thisdata_track(
+          verb: ThisData::Verbs::LOG_IN_DENIED,
+          user: attempted_user
+        )
+      else
+        # email and password were both incorrect
+      end
     end
   end
-
 end
 ```
 
-### Stuck?
+Note: as with many sensitive operations, taking different actions when an
+account exists vs. when an account doesn't exist can lead to a information
+disclosure through timing attacks.
 
-By default there is no logger configured, and requests are performed
-asynchronously. The following config settings can be helpful in debugging issues:
 
-`config/initializers/this_data.rb`
-```
-ThisData.setup do |config|
-  # ...
+### Stuck?
 
-  config.logger = Rails.logger # or Logger.new($stdout)
-  config.async  = false
-end
-```
+The API endpoint validates the events you send, and will return errors in the
+body of the response. Enabling logging will help you debug this.
 
-Our documentation can be read at http://help.thisdata.com.
+Our documentation can be read at http://help.thisdata.com. Our API will return
+error messages you can inspect if the payload is missing required attributes.
 
-Reach out to developers@thisdata.com if you need any help.
+Reach out to developers@thisdata.com if you need any help, or open an issue!
 
 ## Development
 

data/lib/generators/this_data/install_generator.rb

@@ -7,24 +7,51 @@ module ThisData
     def create_configuration_file
       initializer "this_data.rb" do
         <<-EOS
+# Specifies configuration options for the ThisData gem.
 ThisData.setup do |config|
+
+  # This is where your API key goes. You should almost certainly not have it
+  # committed to source control, but instead load it from a secret store.
+  # Default: nil
   config.api_key = "#{api_key}"
 
-  # user_method will be called on a controller when using TrackRequest
+  # Define a Logger instance if you want to debug or track errors
+  # This tells ThisData to log in the development environment.
+  # Comment it out to use the default behaviour across all environments.
+  # Default: nil
+  config.logger = Rails.logger if Rails.env.development?
+
+  # When true, will perform track events asynchronously.
+  # It is true by default, but here we explicitly tell ThisData to make it
+  # synchronous in test and development mode, to aide getting started.
+  # Comment it out to use the default behaviour across all environments.
+  # Default: true
+  config.async  = !(Rails.env.test? || Rails.env.development?)
+
+
+  # These configuration options are used when for the TrackRequest module.
+
+  # user_method will be called on a controller to get a user object.
+  # Default: :current_user
   # config.user_method =        :current_user
 
   # The following methods will be called on the object returned by user_method,
   # to capture details about the user
+
+  # Required. This method should return a unique ID for a user.
+  # Default: :id
   # config.user_id_method =     :id
+
+  # Optional. This method should return the user's name.
+  # Default: :name
   # config.user_name_method =   :name
+  # This method should return the user's email.
+  # Default: :email
   # config.user_email_method =  :email
+  # This method should return the user's mobile phone number.
+  # Default: :mobile
   # config.user_mobile_method = :mobile
 
-  # Define a Logger instance if you want to debug / track errors
-  # config.logger = Rails.logger unless Rails.env.production?
-
-  # Set this to false if you want ThisData.track to perform in the same thread
-  # config.async =               false
 end
 EOS
       end

data/lib/this_data.rb

@@ -74,7 +74,11 @@ module ThisData
       # Returns an HTTPResponse
       def track_with_response(event)
         response = Client.new.track(event)
-        log("Tracked event!")
+        if response.try(:success?)
+          log("Tracked event! #{response.response.inspect}")
+        else
+          warn("Track failure! #{response.response.inspect} #{response.body}")
+        end
         response
       rescue => e
         ThisData.error("Failed to track event:")

data/lib/this_data/track_request.rb

@@ -11,12 +11,27 @@ module ThisData
 
     # Will pull request and user details from the controller, and send an event
     # to ThisData.
-    def thisdata_track(verb: ThisData::Verbs::LOG_IN)
+    # Arguments:
+    #   verb: (String, Required). Defaults to ThisData::Verbs::LOG_IN.
+    #   user: (Object, Optional). If you want to override the user record
+    #     that we would usually fetch, you can pass it here.
+    #     Unless a user is specified here we'll attempt to get the user record
+    #       as specified in the ThisData gem configuration. This defaults to
+    #       `current_user`.
+    #     The object must respond to at least
+    #       `ThisData.configuration.user_id_method`, which defaults to `id`.
+    #
+    # Returns the result of ThisData.track (an HTTPartyResponse)
+    def thisdata_track(verb: ThisData::Verbs::LOG_IN, user: nil)
+      if user.nil?
+        user = send(ThisData.configuration.user_method)
+      end
+
       event = {
         verb:       verb,
         ip:         request.remote_ip,
         user_agent: request.user_agent,
-        user:       user_details
+        user:       user_details(user)
       }
 
       ThisData.track(event)
@@ -29,12 +44,11 @@ module ThisData
 
     private
 
-      # Will fetch a user and return a Hash of details for the User returned
-      # by `ThisData.configuration.user_method`.
-      # Will raise a NoMethodError if controller does not return a user,
-      #  or we can't get a user id.
-      def user_details
-        user = send(ThisData.configuration.user_method)
+      # Will return a Hash of details for a user using the methods specified
+      # in the gem configuration.
+      # Will raise a NoMethodError if user does not respond the
+      # specified `user_id_method`. A user id is required for all events.
+      def user_details(user)
         {
           id:     user.send(ThisData.configuration.user_id_method),
           name:   value_if_configured(user, "user_name_method"),

data/lib/this_data/version.rb

@@ -1,3 +1,3 @@
 module ThisData
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: thisdata
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - ThisData Ltd
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-02-25 00:00:00.000000000 Z
+date: 2016-02-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty