amplitude-api 0.1.0 → 0.3.3

data/lib/amplitude_api/event.rb

@@ -1,3 +1,9 @@
+# frozen_string_literal: true
+
+# This class is 115 lines long. It's on the limit, it should be refactored before
+# including more code.
+#
+# rubocop:disable Metrics/ClassLength
 class AmplitudeAPI
   # AmplitudeAPI::Event
   class Event
@@ -7,15 +13,46 @@ class AmplitudeAPI
 
     # Create a new Event
     #
-    # See (Amplitude HTTP API Documentation)[https://amplitude.zendesk.com/hc/en-us/articles/204771828-HTTP-API]
+    # See (Amplitude HTTP API Documentation)[https://developers.amplitude.com/docs/http-api-v2]
     # for a list of valid parameters and their types.
     def initialize(attributes = {})
+      @extra_properties = []
       attributes.each do |k, v|
-        send("#{k}=", v) if respond_to?("#{k}=")
+        send("#{k}=", v)
       end
       validate_arguments
     end
 
+    def method_missing(method_name, *args)
+      super if block_given?
+      super unless method_name.to_s.end_with? "="
+
+      property_name = method_name.to_s.delete_suffix("=")
+
+      @extra_properties << property_name
+
+      create_setter property_name
+      create_getter property_name
+
+      send("#{property_name}=".to_sym, *args)
+    end
+
+    def create_setter(attribute_name)
+      self.class.send(:define_method, "#{attribute_name}=".to_sym) do |value|
+        instance_variable_set("@" + attribute_name.to_s, value)
+      end
+    end
+
+    def create_getter(attribute_name)
+      self.class.send(:define_method, attribute_name.to_sym) do
+        instance_variable_get("@" + attribute_name.to_s)
+      end
+    end
+
+    def respond_to_missing?(method_name, *args)
+      @extra_properties.include?(method_name) || @extra_properties.include?("#{method_name}=") || super
+    end
+
     def user_id=(value)
       @user_id =
         if value.respond_to?(:id)
@@ -36,28 +73,42 @@ class AmplitudeAPI
       }
       event[:user_id] = user_id if user_id
       event[:device_id] = device_id if device_id
-      event.merge(optional_properties).merge(revenue_hash)
+      event.merge(optional_properties).merge(revenue_hash).merge(extra_properties)
     end
     alias to_h to_hash
 
     # @return [ Hash ] Optional properties
+    #
+    # Returns optional properties (belong to the API but are optional)
     def optional_properties
-      %i[device_id time ip platform country insert_id].map do |prop|
+      AmplitudeAPI::Config.optional_properties.map do |prop|
         val = prop == :time ? formatted_time : send(prop)
         val ? [prop, val] : nil
       end.compact.to_h
     end
 
+    # @return [ Hash ] Extra properties
+    #
+    # Returns optional properties (not belong to the API, are assigned by the user)
+    # This way, if the API is updated with new properties, the gem will be able
+    # to work with the new specification until the code is modified
+    def extra_properties
+      @extra_properties.map do |prop|
+        val = send(prop)
+        val ? [prop.to_sym, val] : nil
+      end.compact.to_h
+    end
+
     # @return [ true, false ]
     #
     # Returns true if the event type matches one reserved by Amplitude API.
     def reserved_event?(type)
-      ['[Amplitude] Start Session',
-       '[Amplitude] End Session',
-       '[Amplitude] Revenue',
-       '[Amplitude] Revenue (Verified)',
-       '[Amplitude] Revenue (Unverified)',
-       '[Amplitude] Merged User'].include?(type)
+      ["[Amplitude] Start Session",
+       "[Amplitude] End Session",
+       "[Amplitude] Revenue",
+       "[Amplitude] Revenue (Verified)",
+       "[Amplitude] Revenue (Unverified)",
+       "[Amplitude] Merged User"].include?(type)
     end
 
     # @return [ true, false ]
@@ -89,15 +140,23 @@ class AmplitudeAPI
     end
 
     def validate_required_arguments
-      raise ArgumentError, 'You must provide user_id or device_id (or both)' unless user_id || device_id
-      raise ArgumentError, 'You must provide event_type' unless event_type
-      raise ArgumentError, 'Invalid event_type - cannot match a reserved event name' if reserved_event?(event_type)
+      raise ArgumentError, "You must provide user_id or device_id (or both)" unless user_id || device_id
+      raise ArgumentError, "You must provide event_type" unless event_type
+      raise ArgumentError, "Invalid event_type - cannot match a reserved event name" if reserved_event?(event_type)
     end
 
     def validate_revenue_arguments
-      return self.quantity ||= 1 if price
-      raise ArgumentError, 'You must provide a price in order to use the product_id' if product_id
-      raise ArgumentError, 'You must provide a price in order to use the revenue_type' if revenue_type
+      return true if !revenue_type && !product_id
+      return true if revenue || price
+
+      raise ArgumentError, revenue_error_message
+    end
+
+    def revenue_error_message
+      error_field = "product_id" if product_id
+      error_field = "revenue_type" if revenue_type
+
+      "You must provide a price or a revenue in order to use the field #{error_field}"
     end
 
     def revenue_hash
@@ -106,6 +165,7 @@ class AmplitudeAPI
       revenue_hash[:revenueType] = revenue_type if revenue_type
       revenue_hash[:quantity] = quantity if quantity
       revenue_hash[:price] = price if price
+      revenue_hash[:revenue] = revenue if revenue
       revenue_hash
     end
 
@@ -114,3 +174,4 @@ class AmplitudeAPI
     end
   end
 end
+# rubocop:enable Metrics/ClassLength

data/lib/amplitude_api/identification.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class AmplitudeAPI
   # AmplitudeAPI::Identification
   class Identification
@@ -16,7 +18,7 @@ class AmplitudeAPI
     # @param [ String ] user_id a user_id to associate with the identification
     # @param [ String ] device_id a device_id to associate with the identification
     # @param [ Hash ] user_properties various properties to attach to the user identification
-    def initialize(user_id: '', device_id: nil, user_properties: {})
+    def initialize(user_id: "", device_id: nil, user_properties: {})
       self.user_id = user_id
       self.device_id = device_id if device_id
       self.user_properties = user_properties

data/lib/amplitude_api/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class AmplitudeAPI
-  VERSION = '0.1.0'.freeze
+  VERSION = "0.3.3"
 end

data/readme.md

@@ -19,7 +19,7 @@ AmplitudeAPI.config.api_key = "abcdef123456"
 
 
 event = AmplitudeAPI::Event.new({
-  user_id: "123",
+  user_id: "12345",
   event_type: "clicked on home",
   time: Time.now,
   insert_id: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
@@ -31,7 +31,38 @@ event = AmplitudeAPI::Event.new({
 AmplitudeAPI.track(event)
 ```
 
-## GDPR Compliance
+You can track multiple events with a single call, with the only limit of the payload
+size imposed by Amplitude:
+
+```ruby
+event_1 = AmplitudeAPI::Event.new(...)
+event_2 = AmplitudeAPI::Event.new(...)
+
+AmplitudeAPI.track(event_1, event_2)
+```
+
+```ruby
+events = [event_1, event_2]
+AmplitudeAPI.track(*events)
+```
+
+In case you use an integer as the time, it is expected to be in seconds. Values in
+the time field will be converted to milliseconds using `->(time) { time ? time.to_i * 1_000 : nil }`
+You can change this behaviour and use your custom formatter. For example, in case
+you wanted to use milliseconds instead of seconds you could do this:
+```ruby
+AmplitudeAPI.config.time_formatter = ->(time) { time ? time.to_i : nil },
+```
+
+You can speficy track options in the config. The options will be applied to all subsequent requests:
+
+```ruby
+AmplitudeAPI.config.options = { min_id_length: 10 }
+AmplitudeAPI.track(event)
+```
+
+
+## User Privacy APIs
 
 The following code snippet will delete a user from amplitude
 
@@ -42,12 +73,13 @@ AmplitudeAPI.config.api_key = "abcdef123456"
 # Configure your Amplitude Secret Key
 AmplitudeAPI.config.secret_key = "secretMcSecret"
 
-AmplitudeAPI.delete(user_ids: [233],
-  requester: "privacy@mycompany.com"
+AmplitudeAPI.delete(user_ids: ["12345"],
+  requester: "privacy@example.com"
 )
 ```
 
-Currently, we are using this in Rails and using ActiveJob to dispatch events asynchronously. I plan on moving background/asynchronous support into this gem.
+Currently, we are using this in Rails and using ActiveJob to dispatch events asynchronously. I plan on moving
+background/asynchronous support into this gem.
 
 ## What's Next
 
@@ -55,7 +87,7 @@ Currently, we are using this in Rails and using ActiveJob to dispatch events asy
 * Configurable default account to use when no `user_id` present
 
 ## Other useful resources
-* [Amplitude HTTP Api Documentation](https://amplitude.zendesk.com/hc/en-us/articles/204771828)
+* [Amplitude HTTP API V2 Api Documentation](https://developers.amplitude.com/docs/http-api-v2)
 * [Segment.io Amplitude integration](https://segment.com/docs/integrations/amplitude/)
 
 ## Contributing

data/spec/lib/amplitude_api/event_spec.rb

@@ -1,277 +1,318 @@
-require 'spec_helper'
+# frozen_string_literal: true
+
+require "spec_helper"
 
 describe AmplitudeAPI::Event do
   user = Struct.new(:id)
 
-  context 'with a user object' do
-    describe '#body' do
+  context "with a user object" do
+    describe "#body" do
       it "populates with the user's id" do
         event = described_class.new(
           user_id: user.new(123),
-          event_type: 'clicked on home'
+          event_type: "clicked on home"
         )
         expect(event.to_hash[:user_id]).to eq(123)
       end
     end
   end
 
-  context 'with a user id' do
-    describe '#body' do
+  context "with a user id" do
+    describe "#body" do
       it "populates with the user's id" do
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home'
+          event_type: "clicked on home"
         )
         expect(event.to_hash[:user_id]).to eq(123)
       end
     end
   end
 
-  context 'without a user' do
-    describe '#body' do
-      it 'populates with the unknown user' do
+  context "without a user" do
+    describe "#body" do
+      it "populates with the unknown user" do
         event = described_class.new(
           user_id: nil,
-          event_type: 'clicked on home'
+          event_type: "clicked on home"
         )
         expect(event.to_hash[:user_id]).to eq(AmplitudeAPI::USER_WITH_NO_ACCOUNT)
       end
     end
   end
 
-  describe 'init' do
-    context 'attributes' do
-      it 'accepts string attributes' do
+  describe "init" do
+    context "attributes" do
+      it "accepts string attributes" do
         time = Time.at(1_451_606_400_000 / 1_000)
         event = described_class.new(
-          'user_id' => 123,
-          'device_id' => 'abcd',
-          'event_type' => 'sausage',
-          'event_properties' => { 'a' => 'b' },
-          'user_properties' => { 'c' => 'd' },
-          'time' => time,
-          'ip' => '127.0.0.1',
-          'platform' => 'Web',
-          'country' => 'United States',
-          'insert_id' => 'bestId'
+          "user_id" => 123,
+          "device_id" => "abcd",
+          "event_type" => "sausage",
+          "event_properties" => { "a" => "b" },
+          "user_properties" => { "c" => "d" },
+          "time" => time,
+          "ip" => "127.0.0.1",
+          "platform" => "Web",
+          "country" => "United States",
+          "insert_id" => "bestId"
         )
 
-        expect(event.to_hash).to eq(event_type: 'sausage',
+        expect(event.to_hash).to eq(event_type: "sausage",
                                     user_id: 123,
-                                    device_id: 'abcd',
-                                    event_properties: { 'a' => 'b' },
-                                    user_properties: { 'c' => 'd' },
+                                    device_id: "abcd",
+                                    event_properties: { "a" => "b" },
+                                    user_properties: { "c" => "d" },
                                     time: 1_451_606_400_000,
-                                    ip: '127.0.0.1',
-                                    platform: 'Web',
-                                    country: 'United States',
-                                    insert_id: 'bestId')
+                                    ip: "127.0.0.1",
+                                    platform: "Web",
+                                    country: "United States",
+                                    insert_id: "bestId")
       end
 
-      it 'accepts symbol attributes' do
+      it "accepts symbol attributes" do
         time = Time.at(1_451_606_400_000 / 1_000)
         event = described_class.new(
           user_id: 123,
-          device_id: 'abcd',
-          event_type: 'sausage',
-          event_properties: { 'a' => 'b' },
-          user_properties: { 'c' => 'd' },
+          device_id: "abcd",
+          event_type: "sausage",
+          event_properties: { "a" => "b" },
+          user_properties: { "c" => "d" },
           time: time,
-          ip: '127.0.0.1',
-          platform: 'Web',
-          country: 'United States',
-          insert_id: 'bestId'
+          ip: "127.0.0.1",
+          platform: "Web",
+          country: "United States",
+          insert_id: "bestId"
         )
 
-        expect(event.to_hash).to eq(event_type: 'sausage',
+        expect(event.to_hash).to eq(event_type: "sausage",
                                     user_id: 123,
-                                    device_id: 'abcd',
-                                    event_properties: { 'a' => 'b' },
-                                    user_properties: { 'c' => 'd' },
+                                    device_id: "abcd",
+                                    event_properties: { "a" => "b" },
+                                    user_properties: { "c" => "d" },
                                     time: 1_451_606_400_000,
-                                    ip: '127.0.0.1',
-                                    platform: 'Web',
-                                    country: 'United States',
-                                    insert_id: 'bestId')
+                                    ip: "127.0.0.1",
+                                    platform: "Web",
+                                    country: "United States",
+                                    insert_id: "bestId")
       end
     end
 
-    context 'the user does not send in a price' do
-      it 'raises an error if the user sends in a product_id' do
+    context "the user sends a revenue_type or a product_id" do
+      it "raises an error if there is not a price neither a revenue" do
+        expect do
+          described_class.new(
+            user_id: 123,
+            event_type: "bad event",
+            product_id: "hopscotch.4lyfe"
+          )
+        end.to raise_error ArgumentError, /You must provide a price or a revenue/
+
+        expect do
+          described_class.new(
+            user_id: 123,
+            event_type: "bad event",
+            revenue_type: "whatever"
+          )
+        end.to raise_error ArgumentError, /You must provide a price or a revenue/
+      end
+
+      it "does not raise an error if there is a price" do
+        expect do
+          described_class.new(
+            user_id: 123,
+            event_type: "bad event",
+            product_id: "hopscotch.4lyfe",
+            price: 10.2
+          )
+        end.not_to raise_error
+
         expect do
           described_class.new(
             user_id: 123,
-            event_type: 'bad event',
-            product_id: 'hopscotch.4lyfe'
+            event_type: "bad event",
+            revenue_type: "whatever",
+            price: 10.2
           )
-        end.to raise_error(ArgumentError)
+        end.not_to raise_error
       end
 
-      it 'raises an error if the user sends in a revenue_type' do
+      it "does not raise an error if there is a revenue" do
+        expect do
+          described_class.new(
+            user_id: 123,
+            event_type: "bad event",
+            product_id: "hopscotch.4lyfe",
+            revenue: 100.1
+          )
+        end.not_to raise_error
+
         expect do
           described_class.new(
             user_id: 123,
-            event_type: 'bad event',
-            revenue_type: 'tax return'
+            event_type: "bad event",
+            revenue_type: "whatever",
+            revenue: 100.1
           )
-        end.to raise_error(ArgumentError)
+        end.not_to raise_error
       end
     end
   end
 
-  describe '#to_hash' do
-    it 'includes the event type' do
+  describe "#to_hash" do
+    it "includes the event type" do
       event = described_class.new(
         user_id: 123,
-        event_type: 'clicked on home'
+        event_type: "clicked on home"
       )
-      expect(event.to_hash[:event_type]).to eq('clicked on home')
+      expect(event.to_hash[:event_type]).to eq("clicked on home")
     end
 
-    it 'includes arbitrary properties' do
+    it "includes arbitrary properties" do
       event = described_class.new(
         user_id: 123,
-        event_type: 'clicked on home',
+        event_type: "clicked on home",
         event_properties: { abc: :def }
       )
       expect(event.to_hash[:event_properties]).to eq(abc: :def)
     end
 
-    describe 'time' do
-      it 'includes a time for the event' do
+    describe "time" do
+      it "includes a time for the event" do
         time = Time.at(1_451_606_400_000 / 1_000)
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home',
+          event_type: "clicked on home",
           time: time
         )
         expect(event.to_hash[:time]).to eq(1_451_606_400_000)
       end
 
-      it 'does not include time if it is not set' do
+      it "does not include time if it is not set" do
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home'
+          event_type: "clicked on home"
         )
         expect(event.to_hash).not_to have_key(:time)
       end
     end
 
-    describe 'insert_id' do
-      it 'includes an insert_id for the event' do
+    describe "insert_id" do
+      it "includes an insert_id for the event" do
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home',
-          insert_id: 'foo-bar'
+          event_type: "clicked on home",
+          insert_id: "foo-bar"
         )
-        expect(event.to_hash[:insert_id]).to eq('foo-bar')
+        expect(event.to_hash[:insert_id]).to eq("foo-bar")
       end
 
-      it 'does not include insert_id if it is not set' do
+      it "does not include insert_id if it is not set" do
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home'
+          event_type: "clicked on home"
         )
         expect(event.to_hash).not_to have_key(:insert_id)
       end
     end
 
-    describe 'platform' do
-      it 'includes the platform for the event' do
+    describe "platform" do
+      it "includes the platform for the event" do
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home',
-          platform: 'Web'
+          event_type: "clicked on home",
+          platform: "Web"
         )
-        expect(event.to_hash[:platform]).to eq('Web')
+        expect(event.to_hash[:platform]).to eq("Web")
       end
 
-      it 'does not include the platform if it is not set' do
+      it "does not include the platform if it is not set" do
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home'
+          event_type: "clicked on home"
         )
         expect(event.to_hash).not_to have_key(:platform)
       end
     end
 
-    describe 'country' do
-      it 'includes the country for the event' do
+    describe "country" do
+      it "includes the country for the event" do
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home',
-          country: 'United States'
+          event_type: "clicked on home",
+          country: "United States"
         )
-        expect(event.to_hash[:country]).to eq('United States')
+        expect(event.to_hash[:country]).to eq("United States")
       end
 
-      it 'does not include the country if it is not set' do
+      it "does not include the country if it is not set" do
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home'
+          event_type: "clicked on home"
         )
         expect(event.to_hash).not_to have_key(:country)
       end
     end
 
-    describe 'revenue params' do
-      it 'includes the price if it is set' do
+    describe "revenue params" do
+      it "includes the price if it is set" do
         price = 100_000.99
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home',
+          event_type: "clicked on home",
           price: price
         )
         expect(event.to_hash[:price]).to eq(price)
       end
 
-      it 'sets the quantity to 1 if the price is set and the quantity is not' do
-        price = 100_000.99
+      it "includes the quantity if it is set" do
+        quantity = 100
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home',
-          price: price
+          event_type: "clicked on home",
+          quantity: quantity,
+          price: 10.99
         )
-        expect(event.to_hash[:quantity]).to eq(1)
+        expect(event.to_hash[:quantity]).to eq(quantity)
       end
 
-      it 'includes the quantity if it is set' do
-        quantity = 100
+      it "includes the revenue if it is set" do
+        revenue = 100
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home',
-          quantity: quantity,
-          price: 10.99
+          event_type: "clicked on home",
+          quantity: 456,
+          revenue: revenue
         )
-        expect(event.to_hash[:quantity]).to eq(quantity)
+        expect(event.to_hash[:revenue]).to eq(revenue)
       end
 
-      it 'includes the productID if set' do
-        product_id = 'hopscotch.subscriptions.rule'
+      it "includes the productID if set" do
+        product_id = "hopscotch.subscriptions.rule"
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home',
+          event_type: "clicked on home",
           price: 199.99,
           product_id: product_id
         )
         expect(event.to_hash[:productId]).to eq(product_id)
       end
 
-      it 'includes the revenueType if set' do
-        revenue_type = 'income'
+      it "includes the revenueType if set" do
+        revenue_type = "income"
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home',
+          event_type: "clicked on home",
           price: 199.99,
           revenue_type: revenue_type
         )
         expect(event.to_hash[:revenueType]).to eq(revenue_type)
       end
 
-      it 'does not include revenue params if they are not set' do
+      it "does not include revenue params if they are not set" do
         event = described_class.new(
           user_id: 123,
-          event_type: 'clicked on home'
+          event_type: "clicked on home"
         )
         expect(event.to_hash).not_to have_key(:quantity)
         expect(event.to_hash).not_to have_key(:revenueType)
@@ -280,4 +321,63 @@ describe AmplitudeAPI::Event do
       end
     end
   end
+
+  describe "arbitrary properties" do
+    # We need to create a class for each test because the methods we are calling
+    # in this test group are modifying the class
+    let(:klass) { Class.new described_class }
+
+    let(:event) {
+      klass.new(
+        user_id: 123,
+        event_type: "bad event"
+      )
+    }
+
+    it "creates properties on initialization" do
+      property_value = "an arbitrary value"
+      creation_data = {
+        user_id: "whatever",
+        event_type: "something happened",
+        arbitrary_property: property_value
+      }
+
+      initialized_event = klass.new(creation_data)
+
+      expect(initialized_event.arbitrary_property).to eq property_value
+    end
+
+    it "creates arbitrary properties when assigning values" do
+      event.arbitrary_property = "arbitrary value"
+
+      expect(event.arbitrary_property).to eq "arbitrary value"
+    end
+
+    it "responds_to? arbitrary properties" do
+      event.arbitrary_property = "arbitrary value"
+
+      expect(event.respond_to?(:arbitrary_property)).to be true
+      expect(event.respond_to?(:arbitrary_property=)).to be true
+    end
+
+    it "does not define property until assigned" do
+      expect {
+        event.undefined_property
+      }.to raise_error NoMethodError, /undefined_property/
+    end
+
+    it "do not accepts blocks when assigning values to create properties" do
+      expect do
+        event.arbitrary_property { puts "whatever" }
+      end.to raise_error NoMethodError
+    end
+
+    it "includes arbitrary properties in the generated hash" do
+      event.arbitrary_property = "arbitrary value"
+
+      hash = event.to_hash
+
+      expect(hash).to include(arbitrary_property: "arbitrary value")
+    end
+  end
 end