leanplum_api 1.3.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: eaef8b007ad46754ae7107b22f86db959f8805c9
+  data.tar.gz: 503030e7e4f4a85640e42aa2e2d60da7911bad5d
+SHA512:
+  metadata.gz: 3d9b7d5ad103922bf4888953aaad2e5130b98c2136a8b18a0b02ba30e9d55d6d2d041403eddad4799457c51290b42491570a42a9a68bb63315b3843130cf0814
+  data.tar.gz: dc14c91eb847b399af97a187bed901f948f88a34462539a2489d72fd587c07a885537e3b3b2f34dac4e8bad3dd4795f0a918ccbd0395e3d99bd64046f876efa7

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Lumos Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,133 @@
+# leanplum_api
+
+Gem for the Leanplum API.
+
+## Notes
+
+Leanplum calls it a REST API but it is not very RESTful.
+
+The gem uses the ```multi``` method with a POST for all requests except data export.  Check Leanplum's docs for more information on ```multi```.
+
+Tested with Leanplum API version 1.0.6.
+
+required_ruby_version is set to 1.9 but this code has only been tested with Ruby 2.1.5!
+
+## Configuration
+
+You need to obtain (at a minimum) the PRODUCTION and APP_ID from Leanplum.  You may also want to configure the DATA_EXPORT_KEY, CONTENT_READ_ONLY_KEY, and DEVELOPMENT_KEY if you plan on calling methods that require those keys.  Then you can setup the gem for use in your application like so:
+
+```ruby
+require 'leanplum_api'
+
+LeanplumApi.configure do |config|
+  config.production_key = 'MY_CLIENT_KEY'
+  config.app_id = 'MY_APP_ID'
+  config.data_export_key = 'MY_DATA_KEY'          # Optional; necessary only if you want to call data export methods.
+  config.content_read_only_key = 'MY_CONTENT_KEY' # Optional; necessary for retrieving AB test info
+  config.development_key = 'MY_CONTENT_KEY'       # Optional; needed for resetting anomalous events
+
+  # Optional configuration variables
+  config.log_path = '/log/path'  # Defaults to 'log/'
+  attr_accessor :timeout_seconds # Defaults to 600
+  config.api_version             # Defaults to 1.0.6
+  attr_accessor :developer_mode  # Defaults to false
+
+  # S3 export required options
+  config.s3_bucket_name = 'my_bucket'
+  config.s3_access_id = 'access_id'
+  config.s3_access_key = 'access_key'
+
+  # Set this to true to send events and user attributes to the test environment
+  # Defaults to false.  See "Debugging" below for more info.
+  config.developer_mode = true
+end
+```
+
+## Usage
+
+Tracking events and user attributes:
+
+```ruby
+api = LeanplumApi::API.new
+
+# You must provide either :user_id or :device_id for requests involving
+# attribute updates or event tracking.
+attribute_hash = {
+  user_id: 12345,
+  first_name: 'Mike',
+  last_name: 'Jones',
+  gender: 'm',
+  birthday: Date.today, # Dates and times in user attributes will be formatted as strings; Leanplum doesn't support date or time types
+  email: 'still_tippin@test.com'
+}
+api.set_user_attributes(attribute_hash)
+
+# You must also provide the :event property for event tracking
+event = {
+  user_id: 12345,
+  event: 'purchase',
+  time: Time.now.utc, # Event timestamps will be converted to epoch seconds by the gem.
+  params: {
+    'some_event_property' => 'boss_hog_on_candy'
+  }
+}
+api.track_events(event)
+
+# You can also track events and user attributes at the same time
+api.track_multi(event, attribute_hash)
+```
+
+Data export:
+```ruby
+api = LeanplumApi::API.new
+job_id = api.export_data(start_time, end_time)
+response = wait_for_job(job_id)
+```
+
+## Logging
+
+When you instantiate a ```LeanplumApi::API``` object, you can pass a ```Logger``` object to redirect the logging as you see fit.
+
+```ruby
+api = LeanplumApi::API.new(logger: Logger.new('/path/to/my/log_file.log))
+```
+
+Alternatively, you can configure a log_path in the configure block.
+```ruby
+LeanplumApi.configure do |config|
+  config.log_path = '/path/to/my/logs'
+end
+```
+
+And logs will be sent to ```/path/to/my/logs/{PID}_leanplum_{timestamp}.log```
+
+The default log_path is ```log/```
+
+## Tests
+
+To run tests, you must set the LEANPLUM_PRODUCTION_KEY, LEANPLUM_APP_ID, LEANPLUM_CONTENT_READ_ONLY_KEY, LEANPLUM_DEVELOPMENT_KEY, and LEANPLUM_DATA_EXPORT_KEY environment variables (preferably to some development only keys) to something and then run rspec.
+Because of the nature of VCR/Webmock, you can set them to anything (including invalid keys) as long as you are not changing anything substantive or writing new specs.  If you want to make substantive changes/add new specs, VCR will need to be able to generate fixture data so you will need to use a real set of Leanplum keys.
+
+> BE AWARE THAT IF YOU WRITE A NEW SPEC OR DELETE A VCR FILE, IT'S POSSIBLE THAT REAL DATA WILL BE WRITTEN TO THE LEANPLUM_APP_ID YOU CONFIGURE!  Certainly a real request will be made to rebuild the VCR file, and while specs run with ```devMode=true```, it's usually a good idea to create a fake app for testing/running specs against.
+
+```bash
+export LEANPLUM_PRODUCTION_KEY=dev_somethingsomeg123456
+export LEANPLUM_APP_ID=app_somethingsomething2039410238
+export LEANPLUM_DATA_EXPORT_KEY=data_something_3238mmmX
+export LEANPLUM_CONTENT_READ_ONLY_KEY=sometingsome23xx9
+export LEANPLUM_DEVELOPMENT_KEY=sometingsome23xx923n23i
+
+bundle exec rspec
+```
+
+## Debugging
+
+The LEANPLUM_API_DEBUG environment variable will trigger full printouts of Faraday's debug output to STDERR and to the configured logger.
+
+```bash
+cd /my/app
+export LEANPLUM_API_DEBUG=true
+bundle exec rails whatever
+```
+
+You can also configure "developer mode".  This will use the "devMode=true" parameter on all requests, which sends them to a separate queue (and probably means actions logged as development tests don't count towards your bill).

data/Rakefile

@@ -0,0 +1,11 @@
+require 'bundler/gem_tasks'
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+task prep: %w(spec)
+
+task default: :spec

data/lib/leanplum_api.rb

@@ -0,0 +1,15 @@
+require 'faraday'
+require 'active_support/all'
+
+require 'leanplum_api/api'
+require 'leanplum_api/configuration'
+require 'leanplum_api/content_read_only'
+require 'leanplum_api/data_export'
+require 'leanplum_api/development'
+require 'leanplum_api/exception'
+require 'leanplum_api/http'
+require 'leanplum_api/logger'
+require 'leanplum_api/version'
+
+module LeanplumApi
+end

data/lib/leanplum_api/api.rb

@@ -0,0 +1,251 @@
+module LeanplumApi
+  class API
+    EXPORT_PENDING = 'PENDING'
+    EXPORT_RUNNING = 'RUNNING'
+    EXPORT_FINISHED = 'FINISHED'
+
+    def initialize(options = {})
+      fail 'LeanplumApi not configured yet!' unless LeanplumApi.configuration
+
+      @logger = options[:logger] || LeanplumApiLogger.new(File.join(LeanplumApi.configuration.log_path, "#{$$}_leanplum_#{Time.now.utc.strftime('%Y-%m-%d_%H:%M:%S')}.log"))
+      @http = LeanplumApi::HTTP.new(logger: @logger)
+    end
+
+    def set_user_attributes(user_attributes, options = {})
+      track_multi(nil, user_attributes, options)
+    end
+
+    def track_events(events, options = {})
+      track_multi(events, nil, options)
+    end
+
+    # This method is for tracking events and/or updating user attributes at the same time, batched together like leanplum
+    # recommends.
+    # Set the :force_anomalous_override to catch warnings from leanplum about anomalous events and force them to not
+    # be considered anomalous
+    def track_multi(events = nil, user_attributes = nil, options = {})
+      events = arrayify(events)
+      user_attributes = arrayify(user_attributes)
+
+      request_data = user_attributes.map { |h| build_user_attributes_hash(h) } + events.map { |h| build_event_attributes_hash(h) }
+      response = @http.post(request_data)
+      validate_response(events + user_attributes, response)
+
+      if options[:force_anomalous_override]
+        user_ids_to_reset = []
+        response.body['response'].each_with_index do |indicator, i|
+          if indicator['warning'] && indicator['warning']['message'] =~ /Anomaly detected/i
+            user_ids_to_reset << (events + user_attributes)[i][:user_id]
+          end
+        end
+        reset_anomalous_users(user_ids_to_reset)
+      end
+    end
+
+    # Returns the jobId
+    # Leanplum has confirmed that using startTime and endTime, especially trying to be relatively up to the minute,
+    # leads to sort of unprocessed information that can be incomplete.
+    # They recommend using the automatic export to S3 if possible.
+    def export_data(start_time, end_time = nil)
+      fail "Start time #{start_time} after end time #{end_time}" if end_time && start_time > end_time
+      @logger.info("Requesting data export from #{start_time} to #{end_time}...")
+
+      # Because of open questions about how startTime and endTime work (or don't work, as the case may be), we
+      # only want to pass the dates unless start and end times are specifically requested.
+      params = { action: 'exportData', startDate: start_time.strftime('%Y%m%d') }
+      params[:startTime] = start_time.strftime('%s') if start_time.is_a?(DateTime) || start_time.is_a?(Time)
+      if end_time
+        params[:endDate] = end_time.strftime('%Y%m%d')
+        params[:endTime] = end_time.strftime('%s') if end_time.is_a?(DateTime) || end_time.is_a?(Time)
+      end
+
+      # Handle optional S3 export params
+      if LeanplumApi.configuration.s3_bucket_name
+        fail 's3_bucket_name set but s3_access_id not configured!' unless LeanplumApi.configuration.s3_access_id
+        fail 's3_bucket_name set but s3_access_key not configured!' unless LeanplumApi.configuration.s3_access_key
+
+        params.merge!(
+          s3BucketName: LeanplumApi.configuration.s3_bucket_name,
+          s3AccessId: LeanplumApi.configuration.s3_access_id,
+          s3AccessKey: LeanplumApi.configuration.s3_access_key
+        )
+        params.merge!(s3ObjectPrefix: LeanplumApi.configuration.s3_object_prefix) if LeanplumApi.configuration.s3_object_prefix
+      end
+
+      response = data_export_connection.get(params).body['response'].first
+      if response['success'] == true
+        response['jobId']
+      else
+        fail "No success message!  Response: #{response}"
+      end
+    end
+
+    # See leanplum docs.
+    # The segment syntax is identical to that produced by the "Insert Value" feature on the dashboard.
+    # Examples: 'Country = "US"', '{Country = “US”} and {App version = 1}'.
+    def export_users(segment, ab_test_id)
+      data_export_connection.get(action: 'exportUsers', segment: segment, ab_test_id: ab_test_id)
+    end
+
+    def get_export_results(job_id)
+      response = data_export_connection.get(action: 'getExportResults', jobId: job_id).body['response'].first
+      if response['state'] == EXPORT_FINISHED
+        @logger.info("Export finished.")
+        @logger.debug("  Response: #{response}")
+        {
+          files: response['files'],
+          number_of_sessions: response['numSessions'],
+          number_of_bytes: response['numBytes'],
+          state: response['state'],
+          s3_copy_status: response['s3CopyStatus']
+        }
+      else
+        { state: response['state'] }
+      end
+    end
+
+    def wait_for_job(job_id, polling_interval = 60)
+      while get_export_results(job_id)[:state] != EXPORT_FINISHED
+        @logger.debug("Polling job #{job_id}: #{get_export_results(job_id)}")
+        sleep(polling_interval)
+      end
+      get_export_results(job_id)
+    end
+
+    def export_user(user_id)
+      data_export_connection.get(action: 'exportUser', userId: user_id).body['response'].first['userAttributes']
+    end
+
+    def get_ab_tests(only_recent = false)
+      content_read_only_connection.get(action: 'getAbTests', recent: only_recent).body['response'].first['abTests']
+    end
+
+    def get_ab_test(ab_test_id)
+      content_read_only_connection.get(action: 'getAbTest', id: ab_test_id).body['response'].first['abTest']
+    end
+
+    def get_variant(variant_id)
+      content_read_only_connection.get(action: 'getVariant', id: variant_id).body['response'].first['variant']
+    end
+
+    def get_messages(only_recent = false)
+      content_read_only_connection.get(action: 'getMessages', recent: only_recent).body['response'].first['messages']
+    end
+
+    def get_message(message_id)
+      content_read_only_connection.get(action: 'getMessage', id: message_id).body['response'].first['message']
+    end
+
+    def get_vars(user_id)
+      @http.get(action: 'getVars', userId: user_id).body['response'].first['vars']
+    end
+
+    # If you pass old events OR users with old date attributes (i.e. create_date for an old users), leanplum will mark them 'anomalous'
+    # and exclude them from your data set.
+    # Calling this method after you pass old events will fix that for all events for the specified user_id
+    # For some reason this API feature requires the developer key
+    def reset_anomalous_users(user_ids)
+      user_ids = arrayify(user_ids)
+      request_data = user_ids.map { |user_id| { 'action' => 'setUserAttributes', 'resetAnomalies' => true, 'userId' => user_id } }
+      response = development_connection.post(request_data)
+      validate_response(request_data, response)
+    end
+
+    private
+
+    # Only instantiated for data export endpoint calls
+    def data_export_connection
+      @data_export ||= LeanplumApi::DataExport.new(logger: @logger)
+    end
+
+    # Only instantiated for ContentReadOnly calls (AB tests)
+    def content_read_only_connection
+      @content_read_only ||= LeanplumApi::ContentReadOnly.new(logger: @logger)
+    end
+
+    def development_connection
+      @development ||= LeanplumApi::Development.new(logger: @logger)
+    end
+
+    def extract_user_id_or_device_id_hash(hash)
+      user_id = hash['user_id'] || hash[:user_id]
+      device_id = hash['device_id'] || hash[:device_id]
+      fail "No device_id or user_id in hash #{hash}" unless user_id || device_id
+
+      user_id ? { 'userId' => user_id } : { 'deviceId' => device_id }
+    end
+
+    # Action can be any command that takes a userAttributes param.  "start" (a session) is the other command that most
+    # obviously takes userAttributes.
+    def build_user_attributes_hash(user_hash, action = 'setUserAttributes')
+      extract_user_id_or_device_id_hash(user_hash).merge(
+        'action' => action,
+        'userAttributes' => turn_date_and_time_values_to_strings(user_hash).reject { |k,v| k.to_s =~ /^(user_id|device_id)$/ }
+      )
+    end
+
+    # Events have a :user_id or :device id, a name (:event) and an optional time (:time)
+    def build_event_attributes_hash(event_hash)
+      fail "No event name provided in #{event_hash}" unless event_hash[:event] || event_hash['event']
+
+      time = event_hash[:time] || event_hash['time']
+      time_hash = time ? { 'time' => time.strftime('%s') } : {}
+
+      event = extract_user_id_or_device_id_hash(event_hash).merge(time_hash).merge(
+        'action' => 'track',
+        'event' => event_hash[:event] || event_hash['event']
+      )
+      event_params = event_hash.reject { |k,v| k.to_s =~ /^(user_id|device_id|event|time)$/ }
+      if event_params.keys.size > 0
+        event.merge('params' => event_params )
+      else
+        event
+      end
+    end
+
+    # Leanplum does not support dates and times as of 2015-08-11
+    def turn_date_and_time_values_to_strings(hash)
+      new_hash = {}
+      hash.each do |k,v|
+        if v.is_a?(Time) || v.is_a?(DateTime)
+          new_hash[k] = v.strftime('%Y-%m-%d %H:%M:%S')
+        elsif v.is_a?(Date)
+          new_hash[k] = v.strftime('%Y-%m-%d')
+        else
+          new_hash[k] = v
+        end
+      end
+      new_hash
+    end
+
+    # In case leanplum decides your events are too old, they will send a warning.
+    # Right now we aren't responding to this directly.
+    # '{"response":[{"success":true,"warning":{"message":"Anomaly detected: time skew. User will be excluded from analytics."}}]}'
+    def validate_response(input, response)
+      success_indicators = response.body['response']
+      if success_indicators.size != input.size
+        fail "Attempted to update #{input.size} records but only received confirmation for #{success_indicators.size}!"
+      end
+
+      failure_indices = []
+      success_indicators.each_with_index do |s,i|
+        if s['success'].to_s != 'true'
+          @logger.error("Unsuccessful attempt to update at position #{i}: #{input[i]}")
+          failure_indices << i
+        else
+          @logger.debug("Successfully updated position #{i}: #{input[i]}")
+        end
+      end
+
+      fail LeanplumValidationException.new('Failed to update') if failure_indices.size > 0
+    end
+
+    def arrayify(x)
+      if x && !x.is_a?(Array)
+        [x]
+      else
+        x || []
+      end
+    end
+  end
+end