README.md in ahoy_email-0.5.2 vs README.md in ahoy_email-1.0.0

@@ -1,16 +1,16 @@
 # Ahoy Email
 
-:postbox: Simple, powerful email tracking for Rails
+:postbox: Email analytics for Rails
 
 You get:
 
 - A history of emails sent to each user
 - Easy UTM tagging
-- Open and click tracking
+- Optional open and click tracking
 
-Works with any email service.
+**Ahoy Email 1.0 was recently released!** See [how to upgrade](#upgrading)
 
 :bullettrain_side: To manage unsubscribes, check out [Mailkick](https://github.com/ankane/mailkick)
 
 :fire: To track visits and events, check out [Ahoy](https://github.com/ankane/ahoy)
 
@@ -31,31 +31,41 @@
 rails db:migrate
 ```
 
 ## How It Works
 
-Ahoy creates an `Ahoy::Message` every time an email is sent by default.
+### Message History
 
+Ahoy creates an `Ahoy::Message` record for each email sent by default. You can disable history for a mailer:
+
+```ruby
+class UserMailer < ApplicationMailer
+  track message: false # use only/except to limit actions
+end
+```
+
+Or by default:
+
+```ruby
+AhoyEmail.default_options[:message] = false
+```
+
 ### Users
 
-Ahoy tracks the user a message is sent to - not just the email address.  This gives you a full history of messages for each user, even if he or she changes addresses.
+Ahoy records the user a message is sent to - not just the email address. This gives you a full history of messages for each user, even if he or she changes addresses.
 
-By default, Ahoy tries `User.where(email: message.to.first).first` to find the user.
+By default, Ahoy tries `@user` then `params[:user]` then `User.find_by(email: message.to.first)` to find the user.
 
 You can pass a specific user with:
 
 ```ruby
 class UserMailer < ApplicationMailer
-  def welcome_email(user)
-    # ...
-    track user: user
-    mail to: user.email
-  end
+  track user: -> { params[:some_user] }
 end
 ```
 
-The user association is [polymorphic](http://railscasts.com/episodes/154-polymorphic-association), so use it with any model.
+The user association is [polymorphic](https://railscasts.com/episodes/154-polymorphic-association), so use it with any model.
 
 To get all messages sent to a user, add an association:
 
 ```ruby
 class User < ApplicationRecord
@@ -67,128 +77,152 @@
 
 ```ruby
 user.messages
 ```
 
-### UTM Parameters
+### Extra Attributes
 
-UTM parameters are added to links if they don’t already exist.
+Record extra attributes on the `Ahoy::Message` model.
 
-The defaults are:
+Create a migration to add extra attributes to the `ahoy_messages` table. For example:
 
-- utm_medium - `email`
-- utm_source - the mailer name like `user_mailer`
-- utm_campaign - the mailer action like `welcome_email`
+```ruby
+class AddCouponIdToAhoyMessages < ActiveRecord::Migration[5.2]
+  def change
+    add_column :ahoy_messages, :coupon_id, :integer
+  end
+end
+```
 
-Use `track utm_params: false` to skip tagging, or skip specific links with:
+Then use:
 
+```ruby
+class CouponMailer < ApplicationMailer
+  track extra: {coupon_id: 1}
+end
+```
 
-```html
-<a data-skip-utm-params="true" href="...">Break it down</a>
+You can use a proc as well.
+
+```ruby
+class CouponMailer < ApplicationMailer
+  track extra: -> { {coupon_id: params[:coupon].id} }
+end
 ```
 
-### Opens
+### UTM Tagging
 
-An invisible pixel is added right before the `</body>` tag in HTML emails.
+Automatically add UTM parameters to links.
 
-If the recipient has images enabled in his or her email client, the pixel is loaded and the open time recorded.
+```ruby
+class CouponMailer < ApplicationMailer
+  track utm_params: true # use only/except to limit actions
+end
+```
 
-Use `track open: false` to skip this.
+The defaults are:
 
-### Clicks
+- `utm_medium` - `email`
+- `utm_source` - the mailer name like `coupon_mailer`
+- `utm_campaign` - the mailer action like `offer`
 
-A redirect is added to links to track clicks in HTML emails.
+You can customize them with:
 
+```ruby
+class CouponMailer < ApplicationMailer
+  track utm_params: true, utm_campaign: -> { "coupon#{params[:coupon].id}" }
+end
 ```
-https://chartkick.com
-```
 
-becomes
+Skip specific links with:
 
+```erb
+<%= link_to "Go", some_url, data: {skip_utm_params: true} %>
 ```
-https://yoursite.com/ahoy/messages/rAnDoMtOkEn/click?url=https%3A%2F%2Fchartkick.com&signature=...
-```
 
-A signature is added to prevent [open redirects](https://www.owasp.org/index.php/Open_redirect).
+### Opens & Clicks
 
-Use `track click: false` to skip tracking, or skip specific links with:
+#### Setup
 
-```html
-<a data-skip-click="true" href="...">Can't touch this</a>
-```
+Additional setup is required to track opens and clicks.
 
-### Extra Attributes
+Create a migration with:
 
-Create a migration to add extra attributes to the `ahoy_messages` table, for example:
-
 ```ruby
-class AddCampaignIdToAhoyMessages < ActiveRecord::Migration
+class AddTokenToAhoyMessages < ActiveRecord::Migration[5.2]
   def change
-    add_column :ahoy_messages, :campaign_id, :integer
+    add_column :ahoy_messages, :token, :string
+    add_column :ahoy_messages, :opened_at, :timestamp
+    add_column :ahoy_messages, :clicked_at, :timestamp
+
+    add_index :ahoy_messages, :token
   end
 end
 ```
 
-Then use:
+Create an initializer `config/initializers/ahoy_email.rb` with:
 
 ```ruby
-track extra: {campaign_id: 1}
+AhoyEmail.api = true
 ```
 
-## Customize
+And add to mailers you want to track:
 
-### Tracking
+```ruby
+class UserMailer < ApplicationMailer
+  track open: true, click: true # use only/except to limit actions
+end
+```
 
-Skip tracking of attributes by removing them from your model.  You can safely remove:
+#### How It Works
 
-- to
-- mailer
-- subject
-- content
+For opens, an invisible pixel is added right before the `</body>` tag in HTML emails. If the recipient has images enabled in their email client, the pixel is loaded and the open time recorded.
 
-### Configuration
+For clicks, a redirect is added to links to track clicks in HTML emails.
 
-There are 3 places to set options. Here’s the order of precedence.
+```
+https://chartkick.com
+```
 
-#### Action
+becomes
 
-``` ruby
-class UserMailer < ApplicationMailer
-  def welcome_email(user)
-    # ...
-    track user: user
-    mail to: user.email
-  end
-end
 ```
+https://yoursite.com/ahoy/messages/rAnDoMtOkEn/click?url=https%3A%2F%2Fchartkick.com&signature=...
+```
 
-#### Mailer
+A signature is added to prevent [open redirects](https://www.owasp.org/index.php/Open_redirect).
 
+Skip specific links with:
+
+```erb
+<%= link_to "Go", some_url, data: {skip_click: true} %>
+```
+
+By default, unsubscribe links are excluded. To change this, use:
+
 ```ruby
-class UserMailer < ApplicationMailer
-  track utm_campaign: "boom"
-end
+AhoyEmail.default_options[:unsubscribe_links] = true
 ```
 
-#### Global
+You can specify the domain to use with:
 
 ```ruby
-AhoyEmail.track open: false
+AhoyEmail.default_options[:url_options] = {host: "mydomain.com"}
 ```
 
-## Events
+#### Events
 
-Subscribe to open and click events. Create an initializer `config/initializers/ahoy_email.rb` with:
+Subscribe to open and click events by adding to the initializer:
 
 ```ruby
 class EmailSubscriber
   def open(event)
-    # any code you want
+    # your code
   end
 
   def click(event)
-    # any code you want
+    # your code
   end
 end
 
 AhoyEmail.subscribers << EmailSubscriber.new
 ```
@@ -209,57 +243,59 @@
 AhoyEmail.subscribers << EmailSubscriber.new
 ```
 
 ## Reference
 
-You can use a `Proc` for any option.
+Set global options
 
 ```ruby
-track utm_campaign: ->(message, mailer) { mailer.action_name + Time.now.year }
+AhoyEmail.default_options[:user] = -> { params[:admin] }
 ```
 
-Disable tracking for an email
+Use a different model
 
 ```ruby
-track message: false
+AhoyEmail.message_model = -> { UserMessage }
 ```
 
-Or specific actions
+Or fully customize how messages are tracked
 
 ```ruby
-track only: [:welcome_email]
-track except: [:welcome_email]
+AhoyEmail.track_method = lambda do |data|
+  # your code
+end
 ```
 
-Or by default
+## Upgrading
 
-```ruby
-AhoyEmail.track message: false
-```
+### 1.0
 
-Customize domain
+Breaking changes
 
-```ruby
-track url_options: {host: "mydomain.com"}
-```
+- UTM tagging, open tracking, and click tracking are no longer enabled by default. To enable, create an initializer with:
 
-By default, unsubscribe links are excluded from tracking. To change this, use:
+  ```ruby
+  AhoyEmail.api = true
 
-```ruby
-track unsubscribe_links: true
-```
+  AhoyEmail.default_options[:open] = true
+  AhoyEmail.default_options[:click] = true
+  AhoyEmail.default_options[:utm_params] = true
+  ```
 
-Use a different model
+- Only sent emails are recorded
+- Proc options are now executed in the context of the mailer and take no arguments
 
-```ruby
-AhoyEmail.message_model = -> { UserMessage }
-```
+  ```ruby
+  # old
+  user: ->(mailer, message) { User.find_by(email: message.to.first) }
 
-## Upgrading
+  # new
+  user: -> { User.find_by(email: message.to.first) }
+  ```
 
-### 0.2.3
-
-Optionally, you can store UTM parameters by adding `utm_source`, `utm_medium`, and `utm_campaign` columns to your message model.
+- Invalid options now throw an `ArgumentError`
+- `AhoyEmail.track` was removed in favor of `AhoyEmail.default_options`
+- The `heuristic_parse` option was removed and is now the default
 
 ## History
 
 View the [changelog](https://github.com/ankane/ahoy_email/blob/master/CHANGELOG.md)