ahoy_matey 1.6.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cb076e85628b3c486e6d80013bf0729f8d3ab142
-  data.tar.gz: 3413580422d7567e36a2acb5bf678637fdadf189
+  metadata.gz: 47cc04adfac18b2f14547b376a3465f601d59307
+  data.tar.gz: 6e1638296155ceab46f9d105e52d7422259ebc63
 SHA512:
-  metadata.gz: ff07d818af43a63fa773cd891f08c2be04359c9c095e25bdd12e5c94e23b6164637573f82b4c7ebd265de918a7134d495f949f09be956492eb094fabcf648154
-  data.tar.gz: 87347e995d4145626112aa2ea8277ef3c45432c7f6f89435af8ed068dd85c5849df58740d3ffa5f6da5c583917a1894ac9bccd8c97cb142e641a7d0f81744a2a
+  metadata.gz: 1f0a217bd790fff2b55e1e6395ea940079b2a457efc1328c61a054d6a3835f0d6fcb9c154eae7f3496f8a79559282cc3d9b1eefb2db4ce651d74d6c14dce536a
+  data.tar.gz: 6789de07f914f49b05f72b4b5517935571368be2e43987421e170dd8da838d78a1fa48e1d878424a9800f53ea779b5dcd8b3523432977f7aec4a29e296941a41

data/.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,7 @@
+Hi,
+
+Before creating an issue, please check out the Contributing Guide:
+
+https://github.com/ankane/ahoy/blob/master/CONTRIBUTING.md
+
+Thanks!

data/CHANGELOG.md

@@ -1,3 +1,25 @@
+## 2.0.0
+
+- Removed dependency on jQuery
+- Use `navigator.sendBeacon` by default in supported browsers
+- Added `geocode` event
+- Added `where_event` method for querying events
+- Added support for `visitable` and `where_props` to Mongoid
+- Added `preserve_callbacks` option
+- Use `json` for MySQL by default
+- Fixed log silencing
+
+Breaking changes
+
+- Simpler interface for data stores
+- Renamed `track_visits_immediately` to `server_side_visits` and enabled by default
+- Renamed `mount` option to `api` and disabled by default
+- Enabled `protect_from_forgery` by default
+- Removed deprecated options
+- Removed throttling
+- Removed most built-in stores
+- Removed support for Rails < 4.2
+
 ## 1.6.1
 
 - Added `gin` index on properties for events

data/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing
+
+First, thanks for wanting to contribute. You’re awesome! :heart:
+
+## Questions
+
+Use [Stack Overflow](https://stackoverflow.com/) with the tag `ahoy`.
+
+## Feature Requests
+
+Create an issue. Start the title with `[Idea]`.
+
+## Issues
+
+Think you’ve discovered an issue?
+
+1. Search existing issues to see if it’s been reported.
+2. Try the `master` branch to make sure it hasn’t been fixed.
+
+```rb
+gem "ahoy_matey", github: "ankane/ahoy"
+```
+
+If the above steps don’t help, create an issue. Include:
+
+- Detailed steps to reproduce
+- Complete backtraces for exceptions
+
+## Pull Requests
+
+Fork the project and create a pull request. A few tips:
+
+- Keep changes to a minimum. If you have multiple features or fixes, submit multiple pull requests.
+- Follow the existing style. The code should read like it’s written by a single person.
+
+Feel free to open an issue to get feedback on your idea before spending too much time on it.
+
+---
+
+This contributing guide is released under [CCO](https://creativecommons.org/publicdomain/zero/1.0/) (public domain). Use it for your own project without attribution.

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2014 Andrew Kane
+Copyright (c) 2014-2018 Andrew Kane
 
 MIT License
 

data/README.md

@@ -1,12 +1,14 @@
 # Ahoy
 
-Ahoy provides a solid foundation to track visits and events in Ruby, JavaScript, and native apps. Works with any data store so you can easily scale.
+:fire: Simple, powerful analytics for Rails
 
-:tangerine: Battle-tested at [Instacart](https://www.instacart.com/opensource)
+Track visits and events in Ruby, JavaScript, and native apps. Data is stored in your database by default so you can easily combine it with other data.
+
+**Ahoy 2.0 was recently released!** See [how to upgrade](docs/Ahoy-2-Upgrade.md)
 
-:postbox: To track emails, check out [Ahoy Email](https://github.com/ankane/ahoy_email).
+:postbox: To track emails, check out [Ahoy Email](https://github.com/ankane/ahoy_email), and for A/B testing, check out [Field Test](https://github.com/ankane/field_test)
 
-:maple_leaf: For A/B testing, check out [Field Test](https://github.com/ankane/field_test).
+:tangerine: Battle-tested at [Instacart](https://www.instacart.com/opensource)
 
 ## Installation
 
@@ -16,177 +18,73 @@ Add this line to your application’s Gemfile:
 gem 'ahoy_matey'
 ```
 
-And add the javascript file in `app/assets/javascripts/application.js` after jQuery.
-
-```javascript
-//= require jquery
-//= require ahoy
-```
-
-## Choose a Data Store
-
-Ahoy supports a number of data stores out of the box.  You can start with one of them and customize as needed, or create your own store from scratch.
-
-- [PostgreSQL, MySQL, or SQLite](#postgresql-mysql-or-sqlite)
-- [MongoDB](#mongodb)
-- [Kafka](#kafka), [Fluentd](#fluentd), [RabbitMQ](#rabbitmq), [NATS](#nats), [NSQ](#nsq), or [Amazon Kinesis Firehose](#amazon-kinesis-firehose)
-- [Logs](#logs)
-- [Custom](#custom)
-
-### PostgreSQL, MySQL, or SQLite
-
-Run:
-
-```sh
-rails generate ahoy:stores:active_record
-rake db:migrate
-```
-
-### MongoDB
-
-Run:
-
-```sh
-rails generate ahoy:stores:mongoid
-```
-
-### Kafka
-
-Add [ruby-kafka](https://github.com/zendesk/ruby-kafka) to your Gemfile.
-
-```ruby
-gem 'ruby-kafka'
-```
-
 And run:
 
 ```sh
-rails generate ahoy:stores:kafka
+bundle install
+rails generate ahoy:install
+rails db:migrate
 ```
 
-Use `ENV["KAFKA_URL"]` to configure.
+Restart your web server, open a page in your browser, and a visit will be created :tada:
 
-### Fluentd
-
-Add [fluent-logger](https://github.com/fluent/fluent-logger-ruby) to your Gemfile.
+Track your first event from a controller with:
 
 ```ruby
-gem 'fluent-logger'
-```
-
-And run:
-
-```sh
-rails generate ahoy:stores:fluentd
+ahoy.track "My first event", {language: "Ruby"}
 ```
 
-Use `ENV["FLUENTD_HOST"]` and `ENV["FLUENTD_PORT"]` to configure.
-
-### RabbitMQ
+### JavaScript & Native Apps
 
-Add [bunny](https://github.com/ruby-amqp/bunny) to your Gemfile.
+First, enable the API in `config/initializers/ahoy.rb`:
 
 ```ruby
-gem 'bunny'
-```
-
-And run:
-
-```sh
-rails generate ahoy:stores:bunny
+Ahoy.api = true
 ```
 
-Use `ENV["RABBITMQ_URL"]` to configure.
-
-### NATS
+And restart your web server.
 
-Add [nats-pure](https://github.com/nats-io/pure-ruby-nats) to your Gemfile.
+For JavaScript, add to `app/assets/javascripts/application.js`:
 
-```ruby
-gem 'nats-pure'
+```javascript
+//= require ahoy
 ```
 
-And run:
+And track an event with:
 
-```sh
-rails generate ahoy:stores:nats
+```javascript
+ahoy.track("My second event", {language: "JavaScript"});
 ```
 
-Use `ENV["NATS_URL"]` to configure.
-
-### NSQ
-
-Add [nsq-ruby](https://github.com/wistia/nsq-ruby) to your Gemfile.
+For native apps, see the [API spec](#api-spec).
 
-```ruby
-gem 'nsq-ruby'
-```
+## How It Works
 
-And run:
+### Visits
 
-```sh
-rails generate ahoy:stores:nsq
-```
+When someone visits your website, Ahoy creates a visit with lots of useful information.
 
-Use `ENV["NSQ_URL"]` to configure.
+- **traffic source** - referrer, referring domain, landing page, search keyword
+- **location** - country, region, and city
+- **technology** - browser, OS, and device type
+- **utm parameters** - source, medium, term, content, campaign
 
-### Amazon Kinesis Firehose
+Use the `current_visit` method to access it.
 
-Add [aws-sdk](https://github.com/aws/aws-sdk-ruby) to your Gemfile.
+Prevent certain Rails actions from creating visits with:
 
 ```ruby
-gem 'aws-sdk', '>= 2.0.0'
-```
-
-And run:
-
-```sh
-rails generate ahoy:stores:kinesis_firehose
-```
-
-Configure delivery streams and credentials in the initializer.
-
-### Logs
-
-```sh
-rails generate ahoy:stores:log
+skip_before_action :track_ahoy_visit
 ```
 
-This logs visits to `log/visits.log` and events to `log/events.log`.
-
-### Custom
+This is typically useful for APIs.
 
-```sh
-rails generate ahoy:stores:custom
-```
-
-This creates a class for you to fill out.
+You can also defer visit tracking to JavaScript (Ahoy 1.0 behavior) with:
 
 ```ruby
-class Ahoy::Store < Ahoy::Stores::BaseStore
-  def track_visit(options)
-  end
-
-  def track_event(name, properties, options)
-  end
-end
+Ahoy.server_side_visits = false
 ```
 
-See the [ActiveRecordTokenStore](https://github.com/ankane/ahoy/blob/master/lib/ahoy/stores/active_record_token_store.rb) for an example.
-
-## How It Works
-
-### Visits
-
-When someone visits your website, Ahoy creates a visit with lots of useful information.
-
-- **traffic source** - referrer, referring domain, landing page, search keyword
-- **location** - country, region, and city
-- **technology** - browser, OS, and device type
-- **utm parameters** - source, medium, term, content, campaign
-
-Use the `current_visit` method to access it.
-
 ### Events
 
 Each event has a `name` and `properties`.
@@ -213,239 +111,193 @@ See [Ahoy.js](https://github.com/ankane/ahoy.js) for a complete list of features
 ahoy.track "Viewed book", title: "Hot, Flat, and Crowded"
 ```
 
-#### Native Apps
-
-See the [HTTP spec](#native-apps-1) until libraries are built.
-
-### Users
-
-Ahoy automatically attaches the `current_user` to the visit.
-
-With [Devise](https://github.com/plataformatec/devise), it will attach the user even if he or she signs in after the visit starts.
-
-With other authentication frameworks, add this to the end of your sign in method:
+or track actions automatically with:
 
 ```ruby
-ahoy.authenticate(user)
-```
-
-## Customize the Store
+class ApplicationController < ActionController::Base
+  after_action :track_action
 
-Stores are built to be highly customizable.
+  protected
 
-```ruby
-class Ahoy::Store < Ahoy::Stores::ActiveRecordTokenStore
-  # add methods here
+  def track_action
+    ahoy.track "Viewed action", request.path_parameters
+  end
 end
 ```
 
-### Exclude Bots and More
+#### Native Apps
 
-Exclude visits and events from being tracked with:
+See the [API spec](#api-spec).
 
-```ruby
-class Ahoy::Store < Ahoy::Stores::ActiveRecordTokenStore
-  def exclude?
-    bot? || request.ip == "192.168.1.1"
-  end
-end
-```
+### Associated Models
 
-Bots are excluded by default.
+Say we want to associate orders with visits. Ahoy can do this automatically.
 
-### Track Additional Values
+First, generate a migration and add a `visit_id` column (not needed for Mongoid).
 
 ```ruby
-class Ahoy::Store < Ahoy::Stores::ActiveRecordTokenStore
-  def track_visit(options)
-    super do |visit|
-      visit.gclid = visit_properties.landing_params["gclid"]
-    end
-  end
-
-  def track_event(name, properties, options)
-    super do |event|
-      event.ip = request.ip
-    end
+class AddVisitIdToOrders < ActiveRecord::Migration[5.1]
+  def change
+    add_column :orders, :visit_id, :bigint
   end
 end
 ```
 
-Some methods you can use are `request`, `controller`, `visit_properties`, and `ahoy`.
-
-### Customize User
-
-If you use a method other than `current_user`, set it here:
+Then, add `visitable` to the model.
 
 ```ruby
-class Ahoy::Store < Ahoy::Stores::ActiveRecordTokenStore
-  def user
-    controller.true_user
-  end
+class Order < ApplicationRecord
+  visitable
 end
 ```
 
-### Report Exceptions
-
-Exceptions are rescued so analytics do not break your app. Ahoy uses [Safely](https://github.com/ankane/safely) to try to report them to a service by default.
+When a visitor places an order, the `visit_id` column is automatically set :tada:
 
-To customize this, use:
+See where orders are coming from with simple joins:
 
 ```ruby
-Safely.report_exception_method = -> (e) { Rollbar.error(e) }
+Order.joins(:visit).group("referring_domain").count
+Order.joins(:visit).group("city").count
+Order.joins(:visit).group("device_type").count
 ```
 
-### Use Different Models
-
-For ActiveRecord and Mongoid stores
+Customize the column and class name with:
 
 ```ruby
-class Ahoy::Store < Ahoy::Stores::ActiveRecordTokenStore
-  def visit_model
-    CustomVisit
-  end
-
-  def event_model
-    CustomEvent
-  end
-end
+visitable :sign_up_visit, class_name: "Visit"
 ```
 
-## More Features
+### Users
 
-### Automatic Tracking
+Ahoy automatically attaches the `current_user` to the visit. With [Devise](https://github.com/plataformatec/devise), it attaches the user even if he or she signs in after the visit starts.
 
-Page views
+With other authentication frameworks, add this to the end of your sign in method:
 
-```javascript
-ahoy.trackView();
+```ruby
+ahoy.authenticate(user)
 ```
 
-Clicks
+To see the visits for a given user, create an association:
 
-```javascript
-ahoy.trackClicks();
+```ruby
+class User < ApplicationRecord
+  has_many :visits, class_name: "Ahoy::Visit"
+end
 ```
 
-Rails actions
+And use:
 
 ```ruby
-class ApplicationController < ActionController::Base
-  after_action :track_action
-
-  protected
-
-  def track_action
-    ahoy.track "Viewed #{controller_path}##{action_name}", params: request.path_parameters
-  end
-end
+User.find(123).visits
 ```
 
-### Multiple Subdomains
+#### Custom User Method
 
-To track visits across multiple subdomains, use:
+Use a method besides `current_user`
 
 ```ruby
-Ahoy.cookie_domain = :all
+Ahoy.user_method = :true_user
 ```
 
-### Visit Duration
-
-By default, a new visit is created after 4 hours of inactivity.
-
-Change this with:
+or use a proc
 
 ```ruby
-Ahoy.visit_duration = 30.minutes
+Ahoy.user_method = ->(controller) { controller.true_user }
 ```
 
-### ActiveRecord
-
-Let’s associate orders with visits.
+### Doorkeeper
 
-First, generate a migration and add a `visit_id` column.
+To attach the user with [Doorkeeper](https://github.com/doorkeeper-gem/doorkeeper), be sure you have a `current_resource_owner` method in `ApplicationController`.
 
 ```ruby
-class AddVisitIdToOrders < ActiveRecord::Migration
-  def change
-    add_column :orders, :visit_id, :integer
+class ApplicationController < ActionController::Base
+  private
+
+  def current_resource_owner
+    User.find(doorkeeper_token.resource_owner_id) if doorkeeper_token
   end
 end
 ```
 
-**Note**: Use the `uuid` column type if the `id` column on `visits` is a `uuid`.
+### Exclusions
 
-Then, add `visitable` to the model.
+Bots are excluded from tracking by default. To enable, use:
 
 ```ruby
-class Order < ActiveRecord::Base
-  visitable
+Ahoy.track_bots = true
+```
+
+Add your own rules with:
+
+```ruby
+Ahoy.exclude_method = lambda do |controller, request|
+  request.ip == "192.168.1.1"
 end
 ```
 
-When a visitor places an order, the `visit_id` column is automatically set. :tada:
+### Visit Duration
 
-Customize the column and class name with:
+By default, a new visit is created after 4 hours of inactivity. Change this with:
 
 ```ruby
-visitable :sign_up_visit, class_name: "Visit"
+Ahoy.visit_duration = 30.minutes
 ```
 
-### Doorkeeper
+### Multiple Subdomains
 
-To attach the user with [Doorkeeper](https://github.com/doorkeeper-gem/doorkeeper), be sure you have a `current_resource_owner` method in `ApplicationController`.
+To track visits across multiple subdomains, use:
 
 ```ruby
-class ApplicationController < ActionController::Base
-  private
-
-  def current_resource_owner
-    User.find(doorkeeper_token.resource_owner_id) if doorkeeper_token
-  end
-end
+Ahoy.cookie_domain = :all
 ```
 
 ### Geocoding
 
-By default, geocoding is performed inline. For performance, move it to the background with:
+Disable geocoding with:
 
 ```ruby
-Ahoy.geocode = :async
+Ahoy.geocode = false
 ```
 
-For Rails 4.0 and 4.1, you’ll need to add [activejob_backport](https://github.com/ankane/activejob_backport).
-
-To change the queue name (`ahoy` by default), use:
+Change the job queue with:
 
 ```ruby
 Ahoy.job_queue = :low_priority
 ```
 
-Or disable geocoding with:
+### Token Generation
+
+Ahoy uses random UUIDs for visit and visitor tokens by default, but you can use your own generator like [Druuid](https://github.com/recurly/druuid).
 
 ```ruby
-Ahoy.geocode = false
+Ahoy.token_generator = -> { Druuid.gen }
 ```
 
-### Track Visits Immediately
+### Throttling
 
-Visitor and visit ids are generated on the first request (so you can use them immediately), but the `track_visit` method isn’t called until the JavaScript library posts to the server.  This prevents browsers with cookies disabled from creating multiple visits and ensures visits are not created for API endpoints.  Change this with:
+You can use [Rack::Attack](https://github.com/kickstarter/rack-attack) to throttle requests to the API.
 
 ```ruby
-Ahoy.track_visits_immediately = true
+class Rack::Attack
+  throttle("ahoy/ip", limit: 20, period: 1.minute) do |req|
+    if req.path.start_with?("/ahoy/")
+      req.ip
+    end
+  end
+end
 ```
 
-**Note:** It’s highly recommended to perform geocoding in the background with this option.
+### Exceptions
 
-You can exclude API endpoints and other actions with:
+Exceptions are rescued so analytics do not break your app. Ahoy uses [Safely](https://github.com/ankane/safely) to try to report them to a service by default. To customize this, use:
 
 ```ruby
-skip_before_action :track_ahoy_visit
+Safely.report_exception_method = ->(e) { Rollbar.error(e) }
 ```
 
 ## Development
 
-Ahoy is built with developers in mind.  You can run the following code in your browser’s console.
+Ahoy is built with developers in mind. You can run the following code in your browser’s console.
 
 Force a new visit
 
@@ -465,293 +317,162 @@ Turn off logging
 ahoy.debug(false);
 ```
 
-Debug endpoint requests in Ruby
+Debug API requests in Ruby
 
 ```ruby
 Ahoy.quiet = false
 ```
 
-## Explore the Data
-
-How you explore the data depends on the data store used.
-
-For SQL databases, you can use [Blazer](https://github.com/ankane/blazer) to easily generate charts and dashboards.
+## Data Stores
 
-With ActiveRecord, you can do:
+Data tracked by Ahoy is sent to your data store. Ahoy ships with a data store that uses your Rails database by default. You can find it in `config/initializers/ahoy.rb`:
 
 ```ruby
-Visit.group(:search_keyword).count
-Visit.group(:country).count
-Visit.group(:referring_domain).count
-```
-
-[Chartkick](http://chartkick.com/) and [Groupdate](https://github.com/ankane/groupdate) make it easy to visualize the data.
-
-```erb
-<%= line_chart Visit.group_by_day(:started_at).count %>
-```
-
-See where orders are coming from with simple joins:
-
-```ruby
-Order.joins(:visit).group("referring_domain").count
-Order.joins(:visit).group("city").count
-Order.joins(:visit).group("device_type").count
-```
-
-To see the visits for a given user, create an association:
-
-```ruby
-class User < ActiveRecord::Base
-  has_many :visits
+class Ahoy::Store < Ahoy::DatabaseStore
 end
 ```
 
-And use:
-
-```ruby
-user = User.first
-user.visits
-```
-
-### Create Funnels
+There are four events data stores can subscribe to:
 
 ```ruby
-viewed_store_ids = Ahoy::Event.where(name: "Viewed store").uniq.pluck(:user_id)
-added_item_ids = Ahoy::Event.where(user_id: viewed_store_ids, name: "Added item to cart").uniq.pluck(:user_id)
-viewed_checkout_ids = Ahoy::Event.where(user_id: added_item_ids, name: "Viewed checkout").uniq.pluck(:user_id)
-```
-
-The same approach also works with visitor tokens.
-
-### Querying Properties
-
-With ActiveRecord, use:
+class Ahoy::Store < Ahoy::BaseStore
+  def track_visit(data)
+    # new visit
+  end
 
-```ruby
-Ahoy::Event.where(name: "Viewed product").where_properties(product_id: 123).count
-```
+  def track_event(data)
+    # new event
+  end
 
-**Note:** If you get a `NoMethodError`, upgrade Ahoy and add `include Ahoy::Properties` to the Ahoy::Event class:
+  def geocode(data)
+    # visit geocoded
+  end
 
-```ruby
-module Ahoy
-  class Event < ActiveRecord::Base
-    include Ahoy::Properties
-    ...
+  def authenticate(data)
+    # user authenticates
   end
 end
 ```
 
-### Throttling
+Data stores are designed to be highly customizable so you can scale as you grow. Check out [examples](docs/Data-Store-Examples.md) for Kafka, RabbitMQ, Fluentd, NATS, NSQ, and Amazon Kinesis Firehose.
 
-By default, Ahoy uses [rack-attack](https://github.com/kickstarter/rack-attack) to throttle requests to Ahoy endpoints. Turn this off with:
+### Track Additional Data
 
 ```ruby
-Ahoy.throttle = false
-```
-
-The default limit is 20 requests per minute. This can be overridden with:
-
-```ruby
-# limit number of requests to 100 requests every 5 minutes
-Ahoy.throttle_limit = 100
-Ahoy.throttle_period = 5.minutes
-```
-
-## Tutorials
-
-- [Tracking Metrics with Ahoy and Blazer](https://gorails.com/episodes/internal-metrics-with-ahoy-and-blazer)
-
-## Native Apps
-
-### Visits
-
-When a user launches the app, create a visit.
-
-Generate a `visit_token` and `visitor_token` as [UUIDs](http://en.wikipedia.org/wiki/Universally_unique_identifier).
-
-Send these values in the `Ahoy-Visit` and `Ahoy-Visitor` headers with all requests.
-
-Send a `POST` request to `/ahoy/visits` with:
-
-- platform - `iOS`, `Android`, etc.
-- app_version - `1.0.0`
-- os_version - `7.0.6`
-
-After 4 hours of inactivity, create another visit and use the updated visit id.
-
-### Events
-
-Send a `POST` request as `Content-Type: application/json` to `/ahoy/events` with:
-
-- id - `5aea7b70-182d-4070-b062-b0a09699ad5e` - UUID
-- name - `Viewed item`
-- properties - `{"item_id": 123}`
-- time - `2014-06-17T00:00:00-07:00` - [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
-- `Ahoy-Visit` and `Ahoy-Visitor` headers
-- user token (depends on your authentication framework)
-
-Use an array to pass multiple events at once.
-
-## Reference
-
-By default, Ahoy create endpoints at `/ahoy/visits` and `/ahoy/events`. To disable, use:
-
-```ruby
-Ahoy.mount = false
-```
-
-## Upgrading
-
-### 1.4.0
-
-There’s nothing mandatory to do, but it’s worth noting the default store was changed from `ActiveRecordStore` to `ActiveRecordTokenStore` for new installations. `ActiveRecordStore` will continue to be supported.
-
-**Optional** Consider migrating `ahoy_events` table to have the following multi-column index as this *may* benefit
-query performance depending on your usage:
-
-```ruby
-add_index :ahoy_events, [:name, :time]
+class Ahoy::Store < Ahoy::DatabaseStore
+  def track_visit(data)
+    data[:accept_language] = request.headers["Accept-Language"]
+    super(data)
+  end
+end
 ```
 
-### json -> jsonb
+Two useful methods you can use are `request` and `controller`.
 
-Create a migration to add a new `jsonb` column.
+### Use Different Models
 
 ```ruby
-rename_column :ahoy_events, :properties, :properties_json
-add_column :ahoy_events, :properties, :jsonb
-```
-
-Restart your web server immediately afterwards, as Ahoy will rescue and report errors until then.
-
-Sync the new column.
+class Ahoy::Store < Ahoy::DatabaseStore
+  def visit_model
+    MyVisit
+  end
 
-```ruby
-Ahoy::Event.where(properties: nil).select(:id).find_in_batches do |events|
-  Ahoy::Event.where(id: events.map(&:id)).update_all("properties = properties_json::jsonb")
+  def event_model
+    MyEvent
+  end
 end
 ```
 
-Then create a migration to drop the old column.
-
-```ruby
-remove_column :ahoy_events, :properties_json
-```
+## Explore the Data
 
-### 1.0.0
+[Blazer](https://github.com/ankane/blazer) is a great tool for exploring your data.
 
-Add the following code to the end of `config/initializers/ahoy.rb`.
+With ActiveRecord, you can do:
 
 ```ruby
-class Ahoy::Store < Ahoy::Stores::ActiveRecordTokenStore
-  uses_deprecated_subscribers
-end
+Ahoy::Visit.group(:search_keyword).count
+Ahoy::Visit.group(:country).count
+Ahoy::Visit.group(:referring_domain).count
 ```
 
-If you use `Ahoy::Event` to track events, copy it into your project.
-
-```ruby
-module Ahoy
-  class Event < ActiveRecord::Base
-    self.table_name = "ahoy_events"
-
-    belongs_to :visit
-    belongs_to :user, polymorphic: true
+[Chartkick](http://chartkick.com/) and [Groupdate](https://github.com/ankane/groupdate) make it easy to visualize the data.
 
-    serialize :properties, JSON
-  end
-end
+```erb
+<%= line_chart Ahoy::Visit.group_by_day(:started_at).count %>
 ```
 
-That’s it!  To fix deprecations, keep reading.
+### Querying Events
 
-#### Visits
+Ahoy provides two methods on the event model to make querying easier.
 
-Remove `ahoy_visit` from your visit model and replace it with:
+To query on both name and properties, you can use:
 
 ```ruby
-class Visit < ActiveRecord::Base
-  belongs_to :user, polymorphic: true
-end
+Ahoy::Event.where_event("Viewed product", product_id: 123).count
 ```
 
-#### Subscribers
-
-Remove `uses_deprecated_subscribers` from `Ahoy::Store`.
-
-If you have a custom subscriber, copy the `track` method to `track_event` in `Ahoy::Store`.
+Or just query properties with:
 
 ```ruby
-class Ahoy::Store < Ahoy::Stores::ActiveRecordTokenStore
-  def track_event(name, properties, options)
-    # code copied from the track method in your subscriber
-  end
-end
+Ahoy::Event.where_props(product_id: 123).count
 ```
 
-#### Authentication
+### Funnels
 
-Ahoy no longer tracks the `$authenticate` event automatically.
-
-To restore this behavior, use:
+It’s easy to create funnels.
 
 ```ruby
-class Ahoy::Store < Ahoy::Stores::ActiveRecordTokenStore
-  def authenticate(user)
-    super
-    ahoy.track "$authenticate"
-  end
-end
+viewed_store_ids = Ahoy::Event.where(name: "Viewed store").distinct.pluck(:user_id)
+added_item_ids = Ahoy::Event.where(user_id: viewed_store_ids, name: "Added item to cart").distinct.pluck(:user_id)
+viewed_checkout_ids = Ahoy::Event.where(user_id: added_item_ids, name: "Viewed checkout").distinct.pluck(:user_id)
 ```
 
-#### Global Options
-
-Replace the `Ahoy.user_method` with `user` method, and replace `Ahoy.track_bots` and `Ahoy.exclude_method` with `exclude?` method.
-
-Skip this step if you do not use these options.
-
-```ruby
-class Ahoy::Store < Ahoy::Stores::ActiveRecordTokenStore
-  def user
-    # logic from Ahoy.user_method goes here
-    controller.true_user
-  end
+The same approach also works with visitor tokens.
 
-  def exclude?
-    # logic from Ahoy.track_bots and Ahoy.exclude_method goes here
-    bot? || request.ip == "192.168.1.1"
-  end
-end
-```
+## Tutorials
 
-You made it!  Now, take advantage of Ahoy’s awesome new features, like easy customization and exception reporting.
+- [Tracking Metrics with Ahoy and Blazer](https://gorails.com/episodes/internal-metrics-with-ahoy-and-blazer)
 
-### 0.3.0
+## API Spec
 
-Starting with `0.3.0`, visit and visitor tokens are now UUIDs.
+### Visits
 
-### 0.1.6
+Generate visit and visitor tokens as [UUIDs](http://en.wikipedia.org/wiki/Universally_unique_identifier), and include these values in the `Ahoy-Visit` and `Ahoy-Visitor` headers with all requests.
 
-In `0.1.6`, a big improvement was made to `browser` and `os`. Update existing visits with:
+Send a `POST` request to `/ahoy/visits` with `Content-Type: application/json` and a body like:
 
-```ruby
-Visit.find_each do |visit|
-  visit.set_technology
-  visit.save! if visit.changed?
-end
+```json
+{
+  "visit_token": "<visit-token>",
+  "visitor_token": "<visitor-token>",
+  "platform": "iOS",
+  "app_version": "1.0.0",
+  "os_version": "11.2.6"
+}
 ```
 
-## TODO
-
-- real-time dashboard of visits and events
-- more events for append only stores
-- turn off modules
+After 4 hours of inactivity, create another visit (use the same visitor token).
 
-## No Ruby?
+### Events
 
-Check out [Ahoy.js](https://github.com/ankane/ahoy.js).
+Send a `POST` request to `/ahoy/events` with `Content-Type: application/json` and a body like:
+
+```json
+{
+  "visit_token": "<visit-token>",
+  "visitor_token": "<visitor-token>",
+  "events": [
+    {
+      "id": "<optional-random-id>",
+      "name": "Viewed item",
+      "properties": {
+        "item_id": 123
+      },
+      "time": "2018-01-01T00:00:00-07:00"
+    }
+  ]
+}
+```
 
 ## History