README.md in ahoy_email-1.1.0 vs README.md in ahoy_email-1.1.1
- old
+ new
@@ -1,23 +1,15 @@
# Ahoy Email
-:postbox: Email analytics for Rails
+First-party email analytics for Rails
-You get:
+:fire: For web and native app analytics, check out [Ahoy](https://github.com/ankane/ahoy)
-- A history of emails sent to each user
-- Easy UTM tagging
-- Optional open and click tracking
-
-**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)
+[](https://github.com/ankane/ahoy_email/actions)
-[](https://travis-ci.org/ankane/ahoy_email)
-
## Installation
Add this line to your application’s Gemfile:
```ruby
@@ -29,16 +21,22 @@
```sh
rails generate ahoy_email:install
rails db:migrate
```
-## How It Works
+## Getting Started
-### Message History
+There are three main features:
-Ahoy creates an `Ahoy::Message` record for each email sent by default. You can disable history for a mailer:
+- [Message history](#message-history)
+- [UTM tagging](#utm-tagging)
+- [Open & click analytics](#open--click-analytics)
+## Message History
+
+Ahoy Email creates an `Ahoy::Message` record for each email sent by default. You can disable history for a mailer:
+
```ruby
class CouponMailer < ApplicationMailer
track message: false # use only/except to limit actions
end
```
@@ -49,11 +47,11 @@
AhoyEmail.default_options[:message] = false
```
### Users
-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.
+Ahoy Email records the user a message is sent to - not just the email address. This gives you a history of messages for each user, even if they change addresses.
By default, Ahoy tries `@user` then `params[:user]` then `User.find_by(email: message.to)` to find the user.
You can pass a specific user with:
@@ -84,11 +82,11 @@
Record extra attributes on the `Ahoy::Message` model.
Create a migration to add extra attributes to the `ahoy_messages` table. For example:
```ruby
-class AddCouponIdToAhoyMessages < ActiveRecord::Migration[5.2]
+class AddCouponIdToAhoyMessages < ActiveRecord::Migration[6.1]
def change
add_column :ahoy_messages, :coupon_id, :integer
end
end
```
@@ -107,14 +105,20 @@
class CouponMailer < ApplicationMailer
track extra: -> { {coupon_id: params[:coupon].id} }
end
```
-### UTM Tagging
+## UTM Tagging
-Automatically add UTM parameters to links.
+Use UTM tagging to attribute a conversion (like an order) to an email campaign. If you use [Ahoy](https://github.com/ankane/ahoy) for web analytics:
+1. Send an email with UTM parameters
+2. When a user visits the site, Ahoy will create a visit with the UTM parameters
+3. When a user orders, the visit will be associated with the order (if [configured](https://github.com/ankane/ahoy#associated-models))
+
+Add UTM parameters to links with:
+
```ruby
class CouponMailer < ApplicationMailer
track utm_params: true # use only/except to limit actions
end
```
@@ -137,26 +141,29 @@
```erb
<%= link_to "Go", some_url, data: {skip_utm_params: true} %>
```
-### Opens & Clicks
+## Open & Click Analytics
-#### Setup
+While it’s nice to get feedback on the performance of your emails, we discourage the use of open tracking. If you do decide to use open or click tracking, be sure to get consent from your users and consider a short retention period. Check out [this article](https://www.eff.org/deeplinks/2019/01/stop-tracking-my-emails) for more best practices.
-Additional setup is required to track opens and clicks.
+### Setup
Create a migration with:
```ruby
-class AddTokenToAhoyMessages < ActiveRecord::Migration[5.2]
+class AddTokenToAhoyMessages < ActiveRecord::Migration[6.1]
def change
add_column :ahoy_messages, :token, :string
+ add_index :ahoy_messages, :token
+
+ # for opens
add_column :ahoy_messages, :opened_at, :timestamp
- add_column :ahoy_messages, :clicked_at, :timestamp
- add_index :ahoy_messages, :token
+ # for clicks
+ add_column :ahoy_messages, :clicked_at, :timestamp
end
end
```
Create an initializer `config/initializers/ahoy_email.rb` with:
@@ -167,16 +174,32 @@
And add to mailers you want to track:
```ruby
class CouponMailer < ApplicationMailer
- track open: true, click: true # use only/except to limit actions
+ track open: true, click: true
end
```
-#### How It Works
+Use only and except to limit actions
+```ruby
+class CouponMailer < ApplicationMailer
+ track click: true, only: [:welcome]
+end
+```
+
+Or make it conditional
+
+```ruby
+class CouponMailer < ApplicationMailer
+ track click: -> { params[:user].opted_in? }
+end
+```
+
+### How It Works
+
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.
For clicks, a redirect is added to links to track clicks in HTML emails.
```
@@ -207,11 +230,11 @@
```ruby
AhoyEmail.default_options[:url_options] = {host: "mydomain.com"}
```
-#### Events
+### Events
Subscribe to open and click events by adding to the initializer:
```ruby
class EmailSubscriber
@@ -243,24 +266,38 @@
AhoyEmail.subscribers << EmailSubscriber.new
```
## Data Protection
-Protect the privacy of your users by encrypting the `to` field. [attr_encrypted](https://github.com/attr-encrypted/attr_encrypted) is great for this. Use [blind_index](https://github.com/ankane/blind_index) if you need to query by the `to` field.
+We recommend encrypting the `to` field (as well as the `subject` if it’s sensitive). [Lockbox](https://github.com/ankane/lockbox) is great for this. Use [Blind Index](https://github.com/ankane/blind_index) if you need to query by the `to` field.
Create `app/models/ahoy/message.rb` with:
```ruby
class Ahoy::Message < ApplicationRecord
self.table_name = "ahoy_messages"
belongs_to :user, polymorphic: true, optional: true
- attr_encrypted :to, key: ...
- blind_index :to, key: ...
+ encrypts :to
+ blind_index :to
end
```
+## Data Retention
+
+Delete older data with:
+
+```ruby
+Ahoy::Message.where("created_at < ?", 1.year.ago).in_batches.delete_all
+```
+
+Delete data for a specific user with:
+
+```ruby
+Ahoy::Message.where(user_id: 1).in_batches.delete_all
+```
+
## Reference
Set global options
```ruby
@@ -281,11 +318,11 @@
end
```
## Mongoid
-If you prefer to use Mongoid instead of ActiveRecord, create `app/models/ahoy/message.rb` with:
+If you prefer to use Mongoid instead of Active Record, create `app/models/ahoy/message.rb` with:
```ruby
class Ahoy::Message
include Mongoid::Document
@@ -296,41 +333,10 @@
field :subject, type: String
field :sent_at, type: Time
end
```
-## Upgrading
-
-### 1.0
-
-Breaking changes
-
-- UTM tagging, open tracking, and click tracking are no longer enabled by default. To enable, create an initializer with:
-
- ```ruby
- AhoyEmail.api = true
-
- AhoyEmail.default_options[:open] = true
- AhoyEmail.default_options[:click] = true
- AhoyEmail.default_options[:utm_params] = true
- ```
-
-- Only sent emails are recorded
-- Proc options are now executed in the context of the mailer and take no arguments
-
- ```ruby
- # old
- user: ->(mailer, message) { User.find_by(email: message.to) }
-
- # new
- user: -> { User.find_by(email: message.to) }
- ```
-
-- 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)
## Contributing
@@ -340,13 +346,13 @@
- [Report bugs](https://github.com/ankane/ahoy_email/issues)
- Fix bugs and [submit pull requests](https://github.com/ankane/ahoy_email/pulls)
- Write, clarify, or fix documentation
- Suggest or add new features
-To get started with development and testing:
+To get started with development:
```sh
git clone https://github.com/ankane/ahoy_email.git
cd ahoy_email
bundle install
-rake test
+bundle exec rake test
```