Merge pull request #7 from jponc/feature/add-identify

Add Identify API

Author: toothrot

lib/amplitude-api.rb

@@ -2,9 +2,11 @@
 require 'bundler/setup'
 require 'typhoeus'
 require 'amplitude-api/event'
+require 'amplitude-api/identification'
 
 class AmplitudeAPI
-  URI_STRING = "https://api.amplitude.com/httpapi"
+  TRACK_URI_STRING = "https://api.amplitude.com/httpapi"
+  IDENTIFY_URI_STRING = "https://api.amplitude.com/identify"
 
   USER_WITH_NO_ACCOUNT = "user who doesn't have an account"
 
@@ -13,6 +15,8 @@ class << self
     #   @return [ String ] an Amplitude API Key
     attr_accessor :api_key
 
+    # ==== Event Tracking related methods
+
     # Send a single event immediately to the AmplitudeAPI
     #
     # @param [ String ] event_name a string that describes the event, e.g. "clicked on Home"
@@ -25,37 +29,81 @@ def send_event(event_name, user, properties = {})
       track(event)
     end
 
-    # @overload body(event)
+
+    # @overload track_body(event)
     #   @param [ AmplitudeAPI::Event ]
     #
-    # @overload body([events])
+    # @overload track_body([events])
     #   @param [ Array<AmplitudeAPI::Event> ]
     #
     # @return [ Hash ]
     #
     # Converts a series of AmplitudeAPI::Event objects into a body
     # suitable for the Amplitude API
-    def body(*events)
+    def track_body(*events)
       event_body = events.flatten.map do |event|
         event.to_hash
       end
-      post_body = {
+
+      {
         api_key: self.api_key,
         event: JSON.generate(event_body)
       }
     end
 
+
     # @overload track(event)
     #   @param [ AmplitudeAPI::Event ] Send a single event to the Amplitude API
     #
     # @overload track([events])
     #   @param [ Array<AmplitudeAPI::Event> ] Send an array of events in a single request to Amplitude
     #
-    # @return [ Typhoeus::Response ] 
+    # @return [ Typhoeus::Response ]
     #
     # Send one or more Events to the Amplitude API
     def track(*events)
-      Typhoeus.post(URI_STRING, body: body(events))
+      Typhoeus.post(TRACK_URI_STRING, body: track_body(events))
+    end
+
+    # ==== Identification related methods
+
+    def send_identify(user_id, user_properties = {})
+      identification = AmplitudeAPI::Identification.new(user_id: user_id, user_properties: user_properties)
+      identify(identification)
+    end
+
+    # @overload identify_body(identification)
+    #   @param [ AmplitudeAPI::Identification ]
+    #
+    # @overload identify_body([identifications])
+    #   @param [ Array<AmplitudeAPI::Identification> ]
+    #
+    # @return [ Hash ]
+    #
+    # Converts a series of AmplitudeAPI::Identification objects into a body
+    # suitable for the Amplitude Identify API
+    def identify_body(*identifications)
+      identification_body = identifications.flatten.map do |identification|
+        identification.to_hash
+      end
+
+      {
+        api_key: self.api_key,
+        identification: JSON.generate(identification_body)
+      }
+    end
+
+    # @overload identify(identification)
+    #   @param [ AmplitudeAPI::Identify ] Send a single identify to the Amplitude API
+    #
+    # @overload identify([identifications])
+    #   @param [ Array<AmplitudeAPI::Identify> ] Send an array of identifications in a single request to Amplitude
+    #
+    # @return [ Typhoeus::Response ]
+    #
+    # Send one or more Identifications to the Amplitude Identify API
+    def identify(*identifications)
+      Typhoeus.post(IDENTIFY_URI_STRING, body: identify_body(identifications))
     end
   end
 end

lib/amplitude-api/identification.rb

@@ -0,0 +1,49 @@
+class AmplitudeAPI
+  class Identification
+    # @!attribute [ rw ] user_id
+    #   @return [ String ] the user_id to be sent to Amplitude
+    attr_accessor :user_id
+    # @!attribute [ rw ] user_properties
+    #   @return [ String ] the user_properties to be attached to the Amplitude Identify
+    attr_accessor :user_properties
+
+    # Create a new Identification
+    #
+    # @param [ String ] user_id a user_id to associate with the identification
+    # @param [ Hash ] user_properties various properties to attach to the user identification
+    def initialize(user_id: "", user_properties: {})
+      self.user_id = user_id
+      self.user_properties = user_properties
+    end
+
+    def user_id=(value)
+      @user_id =
+        if value.respond_to?(:id)
+          value.id
+        else
+          value || AmplitudeAPI::USER_WITH_NO_ACCOUNT
+        end
+    end
+
+    # @return [ Hash ] A serialized Event
+    #
+    # Used for serialization and comparison
+    def to_hash
+      {
+        user_id: self.user_id,
+        user_properties: self.user_properties
+      }
+    end
+
+    # @return [ true, false ]
+    #
+    # Compares +to_hash+ for equality
+    def ==(other)
+      if other.respond_to?(:to_hash)
+        self.to_hash == other.to_hash
+      else
+        false
+      end
+    end
+  end
+end

spec/lib/amplitude-api/identification_spec.rb

@@ -0,0 +1,44 @@
+require 'spec_helper'
+
+describe AmplitudeAPI::Identification do
+  User = Struct.new(:id)
+
+  context "with a user object" do
+    describe "#body" do
+      it "populates with the user's id" do
+        identification = AmplitudeAPI::Identification.new(user_id: User.new(123))
+        expect(identification.to_hash[:user_id]).to eq(123)
+      end
+    end
+  end
+
+  context "with a user id" do
+    describe "#body" do
+      it "populates with the user's id" do
+        identification = AmplitudeAPI::Identification.new(user_id: 123)
+        expect(identification.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
+        identification = AmplitudeAPI::Identification.new(user_id: nil)
+        expect(identification.to_hash[:user_id]).to eq(AmplitudeAPI::USER_WITH_NO_ACCOUNT)
+      end
+    end
+  end
+
+  describe '#body' do
+    it "includes the user id" do
+      identification = AmplitudeAPI::Identification.new(user_id: 123)
+      expect(identification.to_hash[:user_id]).to eq(123)
+    end
+
+    it "includes arbitrary user properties" do
+      identification = AmplitudeAPI::Identification.new(user_id: 123, user_properties: {first_name: 'John', last_name: 'Doe'})
+      expect(identification.to_hash[:user_properties]).to eq(first_name: 'John', last_name: 'Doe')
+    end
+  end
+end

spec/lib/amplitude_api_spec.rb

@@ -11,7 +11,7 @@
         event = AmplitudeAPI::Event.new(user_id: 123, event_type: 'clicked on sign up')
         body = {api_key: AmplitudeAPI.api_key, event: JSON.generate([event.to_hash])}
 
-        expect(Typhoeus).to receive(:post).with(AmplitudeAPI::URI_STRING, body: body)
+        expect(Typhoeus).to receive(:post).with(AmplitudeAPI::TRACK_URI_STRING, body: body)
 
         AmplitudeAPI.track(event)
       end
@@ -23,13 +23,38 @@
         event2 = AmplitudeAPI::Event.new(user_id: 456, event_type: 'liked a widget')
         body = {api_key: AmplitudeAPI.api_key, event: JSON.generate([event.to_hash, event2.to_hash])}
 
-        expect(Typhoeus).to receive(:post).with(AmplitudeAPI::URI_STRING, body: body)
+        expect(Typhoeus).to receive(:post).with(AmplitudeAPI::TRACK_URI_STRING, body: body)
 
         AmplitudeAPI.track([event, event2])
       end
     end
   end
 
+  describe ".identify" do
+    context "with a single identification" do
+      it "sends the identification to Amplitude" do
+        identification = AmplitudeAPI::Identification.new(user_id: 123, user_properties: {first_name: 'John', last_name: 'Doe'})
+        body = {api_key: AmplitudeAPI.api_key, identification: JSON.generate([identification.to_hash])}
+
+        expect(Typhoeus).to receive(:post).with(AmplitudeAPI::IDENTIFY_URI_STRING, body: body)
+
+        AmplitudeAPI.identify(identification)
+      end
+    end
+
+    context "with multiple identifications" do
+      it "sends all identifications in a single request" do
+        identification = AmplitudeAPI::Identification.new(user_id: 123, user_properties: {first_name: 'Julian', last_name: 'Ponce'})
+        identification2 = AmplitudeAPI::Identification.new(user_id: 456, user_properties: {first_name: 'John', last_name: 'Doe'})
+        body = {api_key: AmplitudeAPI.api_key, identification: JSON.generate([identification.to_hash, identification2.to_hash])}
+
+        expect(Typhoeus).to receive(:post).with(AmplitudeAPI::IDENTIFY_URI_STRING, body: body)
+
+        AmplitudeAPI.identify([identification, identification2])
+      end
+    end
+  end
+
   describe ".initializer " do
     it "initializes event without parameter" do
       event = AmplitudeAPI::Event.new()
@@ -77,16 +102,43 @@
     end
   end
 
+  describe ".send_identify" do
+    it "sends an identify to AmplitudeAPI" do
+      identification = AmplitudeAPI::Identification.new(user_id: @user, user_properties: {first_name: 'John', last_name: 'Doe'})
+      expect(AmplitudeAPI).to receive(:identify).with(identification)
+
+      AmplitudeAPI.send_identify(@user, {first_name: 'John', last_name: 'Doe'})
+    end
+
+    context "the user is nil" do
+      it "sends an identify with the no account user" do
+        identification = AmplitudeAPI::Identification.new(user_id: nil, user_properties: {first_name: 'John', last_name: 'Doe'})
+        expect(AmplitudeAPI).to receive(:identify).with(identification)
+
+        AmplitudeAPI.send_identify(nil, {first_name: 'John', last_name: 'Doe'})
+      end
+    end
+
+    context "the user is a user_id" do
+      it "sends an identify to AmplitudeAPI" do
+        identification = AmplitudeAPI::Identification.new(user_id: 123, user_properties: {first_name: 'John', last_name: 'Doe'})
+        expect(AmplitudeAPI).to receive(:identify).with(identification)
+
+        AmplitudeAPI.send_identify(@user.id, {first_name: 'John', last_name: 'Doe'})
+      end
+    end
+  end
+
   describe "#body" do
     it "should add an api key" do
       event = AmplitudeAPI::Event.new(user_id: @user, event_type: "test_event", event_properties: {test_property: 1})
-      body = AmplitudeAPI.body(event)
+      body = AmplitudeAPI.track_body(event)
       expect(body[:api_key]).to eq('stub api key')
     end
 
     it "should create an event" do
       event = AmplitudeAPI::Event.new(user_id: 23, event_type: "test_event", event_properties: {foo: "bar"})
-      body = AmplitudeAPI.body(event)
+      body = AmplitudeAPI.track_body(event)
 
       expected = JSON.generate([{event_type: "test_event", user_id: 23, event_properties: {foo: "bar"}}])
       expect(body[:event]).to eq(expected)