game_analytics 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 94d50722665774ca90d5e42edb9e727a931fbdff
-  data.tar.gz: 0a62b5479e0ad7db5d251d727f9e53a78668e3ca
+  metadata.gz: 301b00ccddb8190e6d5adb999ab9ee5d6039ffc1
+  data.tar.gz: b98f7e0d885ecd8bf0ab3c873d656a4dc5c56b75
 SHA512:
-  metadata.gz: 32d4129191048cba941f9c61a707df6c2847607b5eecedd4c3ec3759d1b81bf72a981e1f08399cbb70998faede16249c3ddd3efbac17eaf14fc27dc22a7f1a1d
-  data.tar.gz: 27c13be5e2e3484d5b285d1c080c9078a1f44d8c0180cab2913b3bacf8671923cc72248ed9a39e21b262d3f50a6df00ee4e8a8b927f92bdc48ed1c349eb7145f
+  metadata.gz: 5f5c54607d02134e62fceabc85482ee8475dadaea0cded1423b17f057543a464fc39daeca4ccb898b001205a8d298a8727e713f9f464c8c40f495a8acc3a44cf
+  data.tar.gz: fb669ef41103d51409d9a2426bed545e7a446e1d2d4f5ce90bd04172f5b9ccd6ccbe162947e09b7b21637a29225ee0696b697e6b10345ee97e1a9427e1f4811a

data/README.md

@@ -15,7 +15,9 @@ available.
 
 Add this line to your application's Gemfile:
 
-    gem 'game_analytics'
+```ruby
+gem 'game_analytics'
+```
 
 And then execute:
 
@@ -30,29 +32,130 @@ Or install it yourself as:
 Configure the gem with your GameAnalytics keys by placing code like the following in
 your initializer:
 
-    GameAnalytics.config(
-      :game_key => '123451234512345123451234512345',
-      :secret_key => '123451234512345123451234512345'
-    )
+```ruby
+GameAnalytics.config(
+  :game_key => '123451234512345123451234512345',
+  :secret_key => '123451234512345123451234512345'
+)
+```
 
 In your application, create Metric objects of the appropriate GameAnalytics types
 (Design, Business, Quality, or User), and send them to the service:
 
-    m = GameAnalytics::Metric::Business.new(:user_id => '-100', :session_id => '-100',
-      :build => 'development', :message => 'test')
-    GameAnalytics.client.enqueue m
+```ruby
+m = GameAnalytics::Metric::Business.new(:user_id => '-100', :session_id => '-100',
+  :build => 'development', :message => 'test')
+GameAnalytics.client.enqueue m
+```
 
 GameAnalytics uses the submitting ip to determine the country the user resides in. If you are submitting events
 in the name of the user (e.g. client) from another machine (e.g. server), you can pass the original ip using `new_with_ip`:
 
-    m = GameAnalytics::Metric::Business.new_with_ip('123.123.123.123', :user_id => '-100', :session_id => '-100',
-          :build => 'development', :message => 'test')
-        GameAnalytics.client.enqueue m
+```ruby
+m = GameAnalytics::Metric::Business.new_with_ip('123.123.123.123', :user_id => '-100', :session_id => '-100', :build => 'development', :message => 'test')
+GameAnalytics.client.enqueue m
+```
 
 You can also send arrays of objects in a single service request:
 
-    GameAnalytics.client.enqueue [m1, m2]
+```ruby
+GameAnalytics.client.enqueue [m1, m2]
+```
 
+## Events
+
+There are 4 types of events you can send to GameAnalytics. For a general description of events see [General event structure](http://support.gameanalytics.com/hc/en-us/articles/200841486-General-event-structure).
+
+All events **require** the following fields:
+
+| Field      | Type   | Required | Description                                                                                                                                                           |
+|:-----------|:-------|:--------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| user_id    | string | **Yes**  | A unique ID representing the user playing your game. This ID should remain the same across different play sessions.                                                   |
+| session_id | string | **Yes**  | A unique ID representing the current play session. A new unique ID should be generated at the start of each session, and used for all events throughout that session. |
+| build      | string | **Yes**  | Describes the current version of the game being played.                                                                                                               |
+
+
+### Design Event
+
+Documentation: [Design event structure](http://support.gameanalytics.com/hc/en-us/articles/200841506-Design-event-structure)
+
+#### Additional fields
+
+| Field    | Type   | Required | Description                                                                                                                                                                    |
+|:---------|:-------|:--------:|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| event_id | string | **Yes**  | Identifies the event. This field can be sub-categorized by using ":", eg. "PickedUpAmmo:Shotgun".                                                                              |
+| area     | string |    No    | Indicates the area or game level where the event occurred.                                                                                                                     |
+| value    | float  |    No    | Numeric value which may be used to enhance the event_id. For example, if the event_id is "PickedUpAmmo:Shotgun", the value could indicate the number of shotgun shells gained. |
+| x        | float  |    No    | The x coordinate at which this event occurred.                                                                                                                                 |
+| y        | float  |    No    | The y coordinate at which this event occurred.                                                                                                                                 |
+| z        | float  |    No    | The z coordinate at which this event occurred.                                                                                                                                 |
+
+
+### User Event
+
+Documentation: [User event structure](http://support.gameanalytics.com/hc/en-us/articles/200841526-User-event-structure)
+
+#### Additional fields
+
+| Field             | Type    | Required | Description                                                                                             |
+|:------------------|:--------|:--------:|:--------------------------------------------------------------------------------------------------------|
+| gender            | char    |    No    | The gender of the user (M/F).                                                                           |
+| birth_year        | integer |    No    | The year the user was born.                                                                             |
+| friend_count      | integer |    No    | The number of friends in the users network.                                                             |
+| facebook_id       | string  |    No    | The Facebook ID of the user, in clear.                                                                  |
+| googleplus_id     | string  |    No    | The Google Plus ID of the user, in clear.                                                               |
+| ios_id            | string  |    No    | The IDFA of the user, in clear.                                                                         |
+| android_id        | string  |    No    | The Android ID of the user, in clear.                                                                   |
+| adtruth_id        | string  |    No    | The AdTruth ID of the user, in clear.                                                                   |
+| platform          | string  |    No    | The platform that this user plays the game on.                                                          |
+| device            | string  |    No    | The device that this user plays the game on.                                                            |
+| os_major          | string  |    No    | The major version of the OS that this user plays on.                                                    |
+| os_minor          | string  |    No    | The minor version of the OS that this user plays on.                                                    |
+| install_publisher | string  |    No    | The name of the ad publisher.                                                                           |
+| install_site      | string  |    No    | The website or app where the ad for your game was shown.                                                |
+| install_campaign  | string  |    No    | The name of your ad campaign this user comes from.                                                      |
+| install_adgroup   | string  |    No    | The name of the ad group this user comes from.                                                          |
+| install_ad        | string  |    No    | The name of the ad this user comes from.                                                                |
+| install_keyword   | string  |    No    | A keyword to associate with this user and the campaign ad.                                              |
+| sdk_version       | string  |    No    | Used by the GA team to provide support on specific versions of the different GA SDKs. DO NOT implement. |
+
+
+### Business Event
+
+Documentation: [Business event structure](http://support.gameanalytics.com/hc/en-us/articles/200841516-Business-event-structure)
+
+#### Additional fields
+
+| Field    | Type    | Required | Description                                                                                                                                                                                                                                                                                                                                                                               |
+|:---------|:--------|:--------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| event_id | string  | **Yes**  | Identifies the event. This field can be sub-categorized by using ":", eg. "Purchase:RocketLauncher:Ammo".                                                                                                                                                                                                                                                                                 |
+| area     | string  |    No    | Indicates the area or game level where the event occurred.                                                                                                                                                                                                                                                                                                                                |
+| value    | float   |    no    | Numeric value which may be used to enhance the event_id. For example, if the event_id is "Purchase:RocketLauncher:Ammo", the value could indicate the number of rocket launcher ammo bought.                                                                                                                                                                                              |
+| currency | string  | **Yes**  | A custom string for identifying the currency. The monetization dashboard will only be populated if you use one of the supported currencies, for example "USD", "RON" or "DKK". For all other virtual currency strings, you will need to create your custom dashboards and widgets.                                                                                                        |
+| amount   | integer | **Yes**  | Numeric value which corresponds to the cost of the purchase in the monetary unit multiplied by 100. For example, if the currency is "USD", the amount should be specified in cents. Exception: Google Play IAB uses a comma separator for representing EUR currency. Before you multiply by 100 we recommend you replace the comma with a point separator. (Example: 12,68€  -> 12.68€) |
+| x        | float   |    No    | The x coordinate at which this event occurred.                                                                                                                                                                                                                                                                                                                                            |
+| y        | float   |    No    | The y coordinate at which this event occurred.                                                                                                                                                                                                                                                                                                                                            |
+| z        | float   |    No    | The z coordinate at which this event occurred.                                                                                                                                                                                                                                                                                                                                            |
+
+
+### Error Event
+
+Documentation: [Error and Quality event structure](http://support.gameanalytics.com/hc/en-us/articles/200841476-Error-and-Quality-event-structure)
+
+#### Additional fields
+
+| Field    | Type   | Required | Description                                                                                                                          |
+|:---------|:-------|:--------:|:-------------------------------------------------------------------------------------------------------------------------------------|
+| message  | string | **Yes**  | Used to describe the event in further detail. For example, in the case of an exception the event could contain the stack trace.      |
+| severity | string | **Yes**  | Used to describe the severity of the event. Must be one of the following values: `["critical", "error", "warning", "info", "debug"]` |
+| area     | string |    No    | Indicates the area or game level where the event occurred.                                                                           |
+| x        | float  |    No    | The x coordinate at which this event occurred.                                                                                       |
+| y        | float  |    No    | The y coordinate at which this event occurred.                                                                                       |
+| z        | float  |    No    | The z coordinate at which this event occurred.                                                                                       |
+
+
+### Quality Event (Deprecated)
+Documentation: [Error and Quality event structure](http://support.gameanalytics.com/hc/en-us/articles/200841476-Error-and-Quality-event-structure)
 
 ## Contributing
 

data/Rakefile

@@ -1 +1,8 @@
 require "bundler/gem_tasks"
+
+task :console do
+  require 'irb'
+  require './lib/game_analytics.rb'
+  ARGV.clear
+  IRB.start
+end

data/lib/game_analytics.rb

@@ -1,3 +1,4 @@
+require 'logger'
 require 'game_analytics/common'
 require 'game_analytics/client'
 require 'game_analytics/metric'
@@ -11,13 +12,14 @@ module GameAnalytics
     attr_accessor :options, :logger, :disabled
   end
 
+  self.logger = const_defined?('Rails') ? Rails.logger : Logger.new(STDOUT)
 
   def self.config(opts)
     @options = opts
-    @logger = opts[:logger] || Rails.logger
+    @logger = opts[:logger] if opts[:logger]
     @disabled = opts[:disabled]
   end
-  
+
   def self.client
     @client ||= Client.new
   end

data/lib/game_analytics/client.rb

@@ -1,45 +1,45 @@
 module GameAnalytics
-class Client
-  
-  include Common
+  class Client
 
+    include Common
 
-  def initialize
-    @queue = Queue.new
-    @worker_mutex = Mutex.new
-  end
 
-  def enqueue(metric)
-    return if disabled
-    ensure_worker_running
-    @queue << metric
-    nil
-  end
+    def initialize
+      @queue = Queue.new
+      @worker_mutex = Mutex.new
+    end
+
+    def enqueue(metric)
+      return if disabled
+      ensure_worker_running
+      @queue << metric
+      nil
+    end
 
 
-private
+  private
 
-  def ensure_worker_running
-    return if worker_running?
-    @worker_mutex.synchronize do
+    def ensure_worker_running
       return if worker_running?
-      start_worker
+      @worker_mutex.synchronize do
+        return if worker_running?
+        start_worker
+      end
     end
-  end
 
-  def worker_running?
-    @worker_thread && @worker_thread.alive?
-  end
+    def worker_running?
+      @worker_thread && @worker_thread.alive?
+    end
 
-  def start_worker
-    @worker_thread = Thread.new do
-      begin
-        Worker.new(@queue).run
-      rescue => ex
-        logger.info "GameAnalytics worker thread exception: #{ex}"
+    def start_worker
+      @worker_thread = Thread.new do
+        begin
+          Worker.new(@queue).run
+        rescue => ex
+          logger.info "GameAnalytics worker thread exception: #{ex}"
+        end
       end
     end
-  end
 
-end
+  end
 end

data/lib/game_analytics/common.rb

@@ -1,21 +1,21 @@
 module GameAnalytics
-module Common
-  
-  def logger
-    GameAnalytics.logger
-  end
-  
-  def options
-    GameAnalytics.options
-  end
-  
-  def client
-    GameAnalytics.client
-  end
-  
-  def disabled
-    GameAnalytics.disabled
-  end
+  module Common
 
-end
+    def logger
+      GameAnalytics.logger
+    end
+
+    def options
+      GameAnalytics.options
+    end
+
+    def client
+      GameAnalytics.client
+    end
+
+    def disabled
+      GameAnalytics.disabled
+    end
+
+  end
 end

data/lib/game_analytics/metric.rb

@@ -1,47 +1,65 @@
 module GameAnalytics
-class Metric
-  
-  include Common
+  class Metric
 
-  attr_accessor :origin_ip
+    include Common
 
-  def self.new_with_ip(ip, data={})
-    metric = self.new(data)
-    metric.origin_ip = ip
-    metric
-  end
+    attr_accessor :origin_ip
 
-  def initialize(data={})
-    @data = data
-    needs = required_keys - data.keys
-    raise "missing required fields #{needs}" unless needs.empty?
-  end
-  
-  def as_json(options={})
-    @data
-  end
-  
-  def required_keys
-    [:user_id, :session_id, :build, :event_id]
-  end
+    def self.new_with_ip(ip, data={})
+      metric = self.new(data)
+      metric.origin_ip = ip
+      metric
+    end
 
+    def initialize(data={})
+      @data = data
+      needs = required_keys - data.keys
+      raise "missing required fields #{needs}" unless needs.empty?
+    end
+
+    def as_json(options={})
+      @data
+    end
 
-  class Design < Metric
-  end
-  
-  class User < Metric
-  end
-  
-  class Business < Metric
-    
     def required_keys
-      super + [:currency, :amount]
+      self.class.const_get("REQUIRED_KEYS")
     end
-    
-  end
-  
-  class Quality < Metric
-  end
 
-end
+
+    class Design < Metric
+
+      REQUIRED_KEYS = [:user_id, :session_id, :build, :event_id]
+
+    end
+
+    class User < Metric
+
+      REQUIRED_KEYS = [:user_id, :session_id, :build, :event_id]
+
+    end
+
+    class Business < Metric
+
+      REQUIRED_KEYS = [:user_id, :session_id, :build, :event_id, :currency, :amount]
+
+    end
+
+    class Quality < Metric
+
+      REQUIRED_KEYS = [:user_id, :session_id, :build, :event_id]
+
+      def initialize(data={})
+        super
+        logger.warn('Deprecation Warning: the Quality metric is deprecated, please use the Error metric instead')
+      end
+
+    end
+
+    class Error < Metric
+
+      REQUIRED_KEYS = [:user_id, :session_id, :build]
+
+    end
+
+  end
 end

data/lib/game_analytics/version.rb

@@ -1,5 +1,5 @@
 module GameAnalytics
   
-  VERSION = '0.0.2'
+  VERSION = '0.0.3'
 
 end

data/lib/game_analytics/worker.rb

@@ -2,37 +2,37 @@ require 'digest/md5'
 require 'httpclient'
 
 module GameAnalytics
-class Worker
-  
-  include Common
+  class Worker
 
+    include Common
 
-  def initialize(q)
-    @queue = q
-    @http = HTTPClient.new
-    @url_base = "http://api.gameanalytics.com/1/#{options[:game_key]}"
-  end
-  
-  def process(unit)
-    metric = unit.is_a?(Array) ? unit.first : unit
-    klass = metric.class
-
-    json_data = unit.to_json
-    header = {'Authorization' => Digest::MD5.hexdigest(json_data + options[:secret_key])}
-    header['X-Forwarded-For'] = metric.origin_ip if metric.origin_ip
-    category = klass.name.demodulize.downcase
-    url = "#{@url_base}/#{category}"
-    logger.info "GameAnalytics <: #{url} #{json_data} #{header.inspect}"
-    resp = @http.post(url, :body => json_data, :header => header)
-    logger.info "GameAnalytics >: #{resp.content} (#{resp.status})"
-  end
-  
-  def run
-    logger.info "GameAnalytics worker running"
-    loop do
-      process @queue.pop
+
+    def initialize(q)
+      @queue = q
+      @http = HTTPClient.new
+      @url_base = "http://api.gameanalytics.com/1/#{options[:game_key]}"
     end
-  end
 
-end
+    def process(unit)
+      metric = unit.is_a?(Array) ? unit.first : unit
+      klass = metric.class
+
+      json_data = unit.to_json
+      header = {'Authorization' => Digest::MD5.hexdigest(json_data + options[:secret_key])}
+      header['X-Forwarded-For'] = metric.origin_ip if metric.origin_ip
+      category = klass.name.demodulize.downcase
+      url = "#{@url_base}/#{category}"
+      logger.info "GameAnalytics <: #{url} #{json_data} #{header.inspect}"
+      resp = @http.post(url, :body => json_data, :header => header)
+      logger.info "GameAnalytics >: #{resp.content} (#{resp.status})"
+    end
+
+    def run
+      logger.info "GameAnalytics worker running"
+      loop do
+        process @queue.pop
+      end
+    end
+
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: game_analytics
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - wlipa
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-02 00:00:00.000000000 Z
+date: 2015-11-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httpclient
@@ -107,7 +107,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5
+rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
 summary: Interface to the REST API of the metrics collection service gameanalytics.com