clearbit 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e0b00b7a895da02d3d5ca094f8960a954b5ecde28891979a515015608c2fd6d
-  data.tar.gz: e4e411ccc729b972cf7139594e59da959ff22222f82fb53e312c1b529512e7ee
+  metadata.gz: 1ef2fb93ad9465fc8f69a87a2b94ead8843082586e763bbe3d32d2ca8a20cc57
+  data.tar.gz: 1ae24030ff38ee37a7079c5b47cfe859233c1e613c515e5f84fcca3b0b1aed4f
 SHA512:
-  metadata.gz: 368ac6459e7e2613e2636731fef9db010d3ae30c9772b7d57017c24d96b4760c9a1af6cddfcfbe6b793051e07552194c519d4a201883f04ec861185b8d5e475a
-  data.tar.gz: '08f475f7c73ccd1c77dd5b660f9c061bc1531402e1d982cf8f2142d5094fe7354087da8a27f50ed30e9562feb29c67b607495e7399d366e1d480b1915f150efa'
+  metadata.gz: 668f7320b3f7774a2712ace35d08e264dfe6095039db4dfe169bdad19e5613f739add95ffe4a1b95af2583abd9c403a27e9a822abdda867ce85842f40667ac05
+  data.tar.gz: a6955e0c932d7990c9f1ba0a02735f4fdfb7fa75c1e6d50cd3b2ac15bd113bbbd8af21303a3b2ec306af76c91ff28b1ea9ecaf204bf01a4d026e2fd37995f640

data/README.md

@@ -80,16 +80,46 @@ See the [documentation](https://clearbit.com/docs#company-api) for more informat
 
 ## Analytics
 
+*NOTE:* We **strongly** recommend using `clearbit.js` for Analytics and integrating with Clearbit X. It handles a lot of complexity, like generating `anonymous_id`s and associating them with `user_id`s when a user is identified. It also automatically tracks `page` views with the full data set.
+
+### Identifying Users
+
 Identify users by sending their `user_id`, and adding details like their `email` and `company_domain` to create People and Companies inside of Clearbit X.
 
 ```ruby
 Clearbit::Analytics.identify(
-  user_id: '1234', # Required
+  user_id: '1234', # Required if no anonymous_id is sent. The user's ID in your database.
+  anonymous_id: session[:anonymous_id], # Required if no user_id is sent. A UUID to track anonymous users.
   traits: {
     email: 'david@clearbitexample.com', # Optional, but strongly recommended
     company_domain: 'clearbit.com',     # Optional, but strongly recommended
     first_name: 'David', # Optional
     last_name: 'Lumley', # Optional
+    # … other analytical traits can also be sent, like the plan a user is on etc
+  },
+  context: {
+    ip: '89.102.33.1' # Optional, but strongly recommended when identifying users
+  }                   # as they sign up, or log in
+)
+```
+
+### Page Views
+
+Use the `page` method, and send the users `anonymous_id` along with the `url` they're viewing, and the `ip` the request comes from in order to create Companies inside of Clearbit X and track their page views.
+
+```ruby
+Clearbit::Analytics.page(
+  user_id: '1234', # Required if no anonymous_id is sent. The user's ID in your database.
+  anonymous_id: session[:anonymous_id], # Required if no user_id is sent. A UUID to track anonymous users.
+  name: 'Clearbit Ruby Library', # Optional, but strongly recommended
+  properties: {
+    url: 'https://github.com/clearbit/clearbit-ruby?utm_source=google', # Required. Likely to be request.referer
+    path: '/clearbit/clearbit-ruby', # Optional, but strongly recommended
+    search: '?utm_source=google', # Optional, but strongly recommended
+    referrer: nil, # Optional. Unlikely to be request.referrer.
+  },
+  context: {
+    ip: '89.102.33.1', # Optional, but strongly recommended.
   },
 )
 ```

data/lib/clearbit/analytics.rb

@@ -17,6 +17,14 @@ module Clearbit
       analytics.flush
     end
 
+    # Proxy page through to a client instance, in order to keep the client
+    # consistent with how the other Clearbit APIs are accessed
+    def self.page(args)
+      analytics = new(write_key: Clearbit.key)
+      analytics.page(args)
+      analytics.flush
+    end
+
     # Initializes a new instance of {Clearbit::Analytics::Client}, to which all
     # method calls are proxied.
     #

data/lib/clearbit/analytics/README.md

@@ -0,0 +1,114 @@
+# Getting Started with Clearbit::Analytics
+
+## Initialization
+
+Make sure you set your `Clearbit.key` as part of your apps initialization, or before you make use of `Clearbit::Analytics`. You can find your secret key at [https://dashboard.clearbit.com/api](https://dashboard.clearbit.com/api)
+
+`Clearbit.key = 'sk_…'`.
+
+We also recommend ensuring that every person has a randomly generated `anonymous_id` to aid tracking page events and assist in matching up anonymous traffic to signed in users.
+
+```ruby
+class ApplicationController
+  before_action :set_anonymous_id
+  …
+
+  def set_anonymous_id
+    session[:anonymous_id] ||= SecureRandom.uuid
+  end
+
+  …
+end
+```
+
+## Importing Users into X
+
+You'll want to loop through your users, and call `.identify` for each one, passing the users `id`, and their `email` along with any other traits you value.
+
+```ruby
+User.find_in_batches do |users|
+  users.each do |user|
+    Clearbit::Analytics.identify(
+      user_id: user.id, # Required.
+      traits: {
+        email: user.email, # Required.
+        company_domain: user.domain || user.email.split('@').last,  # Optional, strongly recommended.
+        first_name: user.first_name,  # Optional.
+        last_name: user.last_name, # Optional.
+        # … other analytical traits can also be sent, like the plan a user is on etc.
+      },
+    )
+  end
+end
+```
+
+## Identifying Users on sign up / log in
+
+Identifying users on sign up, or on log in will help Clearbit X associate the user with anonymous page views.
+
+```ruby
+class SessionsController
+  …
+
+  def create
+    …
+
+    identify(current_user)
+
+    …
+  end
+
+  private
+
+  def identify(user)
+    Clearbit::Analytics.identify(
+      user_id: user.id, # Required
+      anonymous_id: session[:anonymous_id], # Optional, strongly recommended. Helps Clearbit X associate with anonymous visits.
+      traits: {
+        email: user.email, # Required.
+        company_domain: user.domain || user.email.split('@').last,  # Optional, strongly recommended.
+        first_name: user.first_name,  # Optional.
+        last_name: user.last_name, # Optional.
+        # … other analytical traits can also be sent, like the plan a user is on etc.
+      },
+      context: {
+        ip: request.ip, # Optional, but strongly recommended. Helps Clearbit X associate with anonymous visits.
+      },
+    )
+  end
+
+  …
+end
+```
+
+## Sending Page views
+
+Tracking page views is best done using a `anonymous_id` you generate for each user. You'll need to sent the `url` as part of the `properties` hash, and the `ip` as part of the `context` hash. Any other data you can provide will greatly help with segmentation inside of Clearbit X.
+
+
+```ruby
+uri = URI(request.referer) # You'll likely want to do some error handling here.
+
+Clearbit::Analytics.page(
+  user_id: current_user&.id, # Optional
+  anonymous_id: session[:anonymous_id], # Required
+  properties: {
+    url: request.referrer, # Required. Because this is a backend integration, the referrer is the URL that was visited.
+    path: format_path(uri.path), # Optional, but strongly recommended.
+    search: format_search(uri.params), # Optional, but strongly recommended.
+    referrer: nil, # Optional. Not the `request.referer`, but the referrer of the original page view.
+  },
+  context: {
+    ip: request.ip, # Required. Helps Clearbit X associate anonymous visits with Companies.
+  },
+)
+
+def format_path(path)
+  path.presence || '/'
+end
+
+def format_search(search)
+  return unless search
+  '?' + search
+end
+```

data/lib/clearbit/analytics/field_parser.rb

@@ -170,7 +170,7 @@ module Clearbit
         end
 
         def add_context!(context)
-          context[:library] = { :name => 'analytics-ruby', :version => Clearbit::VERSION.to_s }
+          context[:library] = { :name => 'clearbit-ruby', :version => Clearbit::VERSION.to_s }
         end
 
         # private: Ensures that a string is non-empty

data/lib/clearbit/analytics/logging.rb

@@ -38,7 +38,7 @@ module Clearbit
                           logger.progname = 'Clearbit::Analytics'
                           logger
                         end
-          @logger = PrefixedLogger.new(base_logger, '[analytics-ruby]')
+          @logger = PrefixedLogger.new(base_logger, '[clearbit-ruby]')
         end
 
         attr_writer :logger

data/lib/clearbit/version.rb

@@ -1,3 +1,3 @@
 module Clearbit
-  VERSION = '0.3.0'
+  VERSION = '0.3.1'
 end

data/spec/lib/clearbit/analytics_spec.rb

@@ -6,20 +6,41 @@ describe Clearbit::Analytics do
     Clearbit.key = 'clearbit_key'
   end
 
-  it 'sends an identify request to Clearbit X' do
-    basic_auth = Base64.encode64('clearbit_key:').strip
-    x_stub = stub_request(:post, 'https://x.clearbit.com/v1/import').
-      with(
-        headers: { 'Authorization' => "Basic #{basic_auth}" }
-      ).to_return(status: 200, body: {success: true}.to_json)
+  describe '#identify' do
+    it 'sends an identify request to Clearbit X' do
+      basic_auth = Base64.encode64('clearbit_key:').strip
+      x_stub = stub_request(:post, 'https://x.clearbit.com/v1/import').
+        with(
+          headers: { 'Authorization' => "Basic #{basic_auth}" }
+        ).to_return(status: 200, body: {success: true}.to_json)
 
-    Clearbit::Analytics.identify(
-      user_id: '123',
-      traits: {
-        email: 'david@clearbit.com',
-      },
-    )
+      Clearbit::Analytics.identify(
+        user_id: '123',
+        traits: {
+          email: 'david@clearbit.com',
+        },
+      )
 
-    expect(x_stub).to have_been_requested
+      expect(x_stub).to have_been_requested
+    end
+  end
+
+  describe '#page' do
+    it 'sends an identify request to Clearbit X' do
+      basic_auth = Base64.encode64('clearbit_key:').strip
+      x_stub = stub_request(:post, 'https://x.clearbit.com/v1/import').
+        with(
+          headers: { 'Authorization' => "Basic #{basic_auth}" }
+        ).to_return(status: 200, body: {success: true}.to_json)
+
+      Clearbit::Analytics.page(
+        user_id: '123',
+        traits: {
+          email: 'david@clearbit.com',
+        },
+      )
+
+      expect(x_stub).to have_been_requested
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clearbit
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Alex MacCaw
@@ -151,6 +151,7 @@ files:
 - lib/clearbit.rb
 - lib/clearbit/analytics.rb
 - lib/clearbit/analytics/LICENSE
+- lib/clearbit/analytics/README.md
 - lib/clearbit/analytics/backoff_policy.rb
 - lib/clearbit/analytics/client.rb
 - lib/clearbit/analytics/defaults.rb