README.md in ahoy_email-0.5.0 vs README.md in ahoy_email-0.5.1
- old
+ new
@@ -3,12 +3,12 @@
:postbox: Simple, powerful email tracking for Rails
You get:
- A history of emails sent to each user
-- Open and click tracking
- Easy UTM tagging
+- Open and click tracking
Works with any email service.
:bullettrain_side: To manage unsubscribes, check out [Mailkick](https://github.com/ankane/mailkick)
@@ -26,11 +26,11 @@
And run the generator. This creates a model to store messages.
```sh
rails generate ahoy_email:install
-rake db:migrate
+rails db:migrate
```
## How It Works
Ahoy creates an `Ahoy::Message` every time an email is sent by default.
@@ -42,11 +42,11 @@
By default, Ahoy tries `User.where(email: message.to.first).first` to find the user.
You can pass a specific user with:
```ruby
-class UserMailer < ActionMailer::Base
+class UserMailer < ApplicationMailer
def welcome_email(user)
# ...
track user: user
mail to: user.email
end
@@ -56,21 +56,38 @@
The user association is [polymorphic](http://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 < ActiveRecord::Base
- has_many :messages, class_name: "Ahoy::Message"
+class User < ApplicationRecord
+ has_many :messages, class_name: "Ahoy::Message", as: :user
end
```
And run:
```ruby
user.messages
```
+### UTM Parameters
+
+UTM parameters are added to links if they don’t already exist.
+
+The defaults are:
+
+- utm_medium - `email`
+- utm_source - the mailer name like `user_mailer`
+- utm_campaign - the mailer action like `welcome_email`
+
+Use `track utm_params: false` to skip tagging, or skip specific links with:
+
+
+```html
+<a data-skip-utm-params="true" href="...">Break it down</a>
+```
+
### Opens
An invisible pixel is added right before the `</body>` tag in HTML emails.
If the recipient has images enabled in his or her email client, the pixel is loaded and the open time recorded.
@@ -97,27 +114,10 @@
```html
<a data-skip-click="true" href="...">Can't touch this</a>
```
-### UTM Parameters
-
-UTM parameters are added to links if they don’t already exist.
-
-The defaults are:
-
-- utm_medium - `email`
-- utm_source - the mailer name like `user_mailer`
-- utm_campaign - the mailer action like `welcome_email`
-
-Use `track utm_params: false` to skip tagging, or skip specific links with:
-
-
-```html
-<a data-skip-utm-params="true" href="...">Break it down</a>
-```
-
### Extra Attributes
Create a migration to add extra attributes to the `ahoy_messages` table, for example:
```ruby
@@ -150,11 +150,11 @@
There are 3 places to set options. Here’s the order of precedence.
#### Action
``` ruby
-class UserMailer < ActionMailer::Base
+class UserMailer < ApplicationMailer
def welcome_email(user)
# ...
track user: user
mail to: user.email
end
@@ -162,11 +162,11 @@
```
#### Mailer
```ruby
-class UserMailer < ActionMailer::Base
+class UserMailer < ApplicationMailer
track utm_campaign: "boom"
end
```
#### Global
@@ -212,11 +212,11 @@
## Reference
You can use a `Proc` for any option.
```ruby
-track utm_campaign: proc { |message, mailer| mailer.action_name + Time.now.year }
+track utm_campaign: ->(message, mailer) { mailer.action_name + Time.now.year }
```
Disable tracking for an email
```ruby
@@ -238,9 +238,15 @@
Customize domain
```ruby
track url_options: {host: "mydomain.com"}
+```
+
+By default, unsubscribe links are excluded from tracking. To change this, use:
+
+```ruby
+track unsubscribe_links: true
```
Use a different model
```ruby