ahoy_email 1.0.2 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e39b9c6d5b1c32cc0a7a1bcc5da1e08205d6187e8eb5aec1505295ac1de36c64
-  data.tar.gz: c8f94cc014a6ab2cebe9c718a02989505fa9086d4b6bdbaed1e35a13bf269259
+  metadata.gz: 69eb9c77891a37c75ef7f7683211c90159cbb8aefd64fa14a0b1b35d2e16d0eb
+  data.tar.gz: a937ba8e9362d1c2551f5c193b9a3bbf1b4132f3df9ddb77f3f838f633fb2f07
 SHA512:
-  metadata.gz: fc2721f83dc1eb2098d4d16166c3e78a07184007b61fd320ab4e50b26dc8dcc34583482baf8af1154d1b12e904c9113a69f4f3d24b18c1efc5dc26cf88e19aa2
-  data.tar.gz: 20f100d9f5c34ed8553ef778e4330df5cf35458d50f1bcfb2a28cdf3e6b8750d59b65b1dc153b23c773db4959ae10e051a28828852b0da06064c18a10f8c685c
+  metadata.gz: 4b12c970be432d7db95fdb8eaade5766f69fc7826a94f41474ba5c2a35da1ea85b6317f83250cb1c8f41c7fe876028b1377958709d2c84ff9bd303926ac8ab5a
+  data.tar.gz: 96dcc647ee3777e27b14d7628025d96ea92efce7160d36da0b066b72d9dc5aac8196008699a93673d81d0fdcb909aa69874b349dffdbaf0e32e4d7511a32df5a

data/CHANGELOG.md

@@ -1,13 +1,48 @@
-## 1.0.2
+## 2.0.1 (2021-03-08)
+
+- Added database subscriber
+
+## 2.0.0 (2021-03-06)
+
+- Made `to` field encrypted by default for new installations
+- Added click analytics for Redis
+- Added send events to subscribers
+- Removed support for Rails < 5.2
+
+Breaking changes
+
+- The `track` method has been broken into `has_history` for message history, `utm_params` for UTM tagging, and `track_clicks` for click analytics
+- Message history is no longer enabled by default
+- Open tracking has been removed
+- `:message` is no longer included in click events
+- Users are shown a link expired page when signature verification fails instead of being redirected to the homepage when `AhoyEmail.invalid_redirect_url` is not set
+
+## 1.1.1 (2021-03-06)
+
+- Added support for classes for subscribers
+- Use `datetime` type in migration
+
+## 1.1.0 (2019-07-15)
+
+- Made `opened_at` optional with click tracking
+- Fixed secret token for environment variables
+- Removed support for Rails 4.2
+
+## 1.0.3 (2019-02-18)
+
+- Fixed custom message model
+- Fixed `message` option with proc
+
+## 1.0.2 (2018-10-02)
 
 - Fixed error with Ruby < 2.5
 - Fixed UTM parameters storage on model
 
-## 1.0.1
+## 1.0.1 (2018-09-27)
 
 - Use observer instead of interceptor
 
-## 1.0.0
+## 1.0.0 (2018-09-27)
 
 - Removed support for Rails < 4.2
 
@@ -20,91 +55,91 @@ Breaking changes
 - `AhoyEmail.track` was removed in favor of `AhoyEmail.default_options`
 - The `heuristic_parse` option was removed and is now the default
 
-## 0.5.2
+## 0.5.2 (2018-04-26)
 
 - Fixed secret token for Rails 5.2
 - Added `heuristic_parse` option
 
-## 0.5.1
+## 0.5.1 (2018-04-19)
 
 - Fixed deprecation warning in Rails 5.2
 - Added `unsubscribe_links` option
 - Allow `message_model` to accept a proc
 - Use `references` in migration
 
-## 0.5.0
+## 0.5.0 (2017-05-01)
 
 - Added support for Rails 5.1
 - Added `invalid_redirect_url`
 
-## 0.4.0
+## 0.4.0 (2016-09-01)
 
 - Fixed `belongs_to` error in Rails 5
 - Include `safely_block` gem without polluting global namespace
 
-## 0.3.2
+## 0.3.2 (2016-07-27)
 
 - Fixed deprecation warning for Rails 5
 - Do not track content by default on fresh installations
 
-## 0.3.1
+## 0.3.1 (2016-05-11)
 
 - Fixed deprecation warnings
 - Fixed `stack level too deep` error
 
-## 0.3.0
+## 0.3.0 (2015-12-16)
 
 - Added safely for error reporting
 - Fixed error with `to`
 - Prevent duplicate records when mail called multiple times
 
-## 0.2.4
+## 0.2.4 (2015-07-29)
 
 - Added `extra` option for extra attributes
 
-## 0.2.3
+## 0.2.3 (2015-03-22)
 
 - Save utm parameters
 - Added `url_options`
 - Skip tracking for `mailto` links
 - Only set secret token if not already set
 
-## 0.2.2
+## 0.2.2 (2014-08-31)
 
 - Fixed secret token for Rails 4.1
 - Fixed links with href
 - Fixed message id for Rails 3.1
 
-## 0.2.1
+## 0.2.1 (2014-05-26)
 
 - Added `only` and `except` options
 
-## 0.2.0
+## 0.2.0 (2014-05-10)
 
 - Enable tracking when track is called by default
 
-## 0.1.5
+## 0.1.5 (2014-05-09)
 
 - Rails 3 fix
 
-## 0.1.4
+## 0.1.4 (2014-05-04)
 
 - Try not to rewrite unsubscribe links
 
-## 0.1.3
+## 0.1.3 (2014-05-03)
 
 - Added `to` and `mailer` fields
 - Added subscribers for open and click events
 
-## 0.1.2
+## 0.1.2 (2014-05-01)
 
 - Added `AhoyEmail.track` (fix)
 
-## 0.1.1
+## 0.1.1 (2014-04-30)
 
 - Use secure compare for signature verification
 - Fixed deprecation warnings
 
-## 0.1.0
+## 0.1.0 (2014-04-29)
 
 - First major release

data/LICENSE.txt

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

data/README.md

@@ -1,20 +1,14 @@
 # Ahoy Email
 
-:postbox: Email analytics for Rails
+First-party email analytics for Rails
 
-You get:
+**Ahoy Email 2.0 was recently released** - see [how to upgrade](#upgrading)
 
-- 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)
+:fire: For web and native app analytics, check out [Ahoy](https://github.com/ankane/ahoy)
 
 :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)
-
-[![Build Status](https://travis-ci.org/ankane/ahoy_email.svg?branch=master)](https://travis-ci.org/ankane/ahoy_email)
+[![Build Status](https://github.com/ankane/ahoy_email/workflows/build/badge.svg?branch=master)](https://github.com/ankane/ahoy_email/actions)
 
 ## Installation
 
@@ -24,42 +18,65 @@ Add this line to your application’s Gemfile:
 gem 'ahoy_email'
 ```
 
-And run the generator. This creates a model to store messages.
+## Getting Started
+
+There are three main features, which can be used independently:
+
+- [Message history](#message-history)
+- [UTM tagging](#utm-tagging)
+- [Click analytics](#click-analytics)
+
+## Message History
+
+To encrypt email addresses, install [Lockbox](https://github.com/ankane/lockbox) and [Blind Index](https://github.com/ankane/blind_index) and run:
 
 ```sh
-rails generate ahoy_email:install
+rails generate ahoy:messages
 rails db:migrate
 ```
 
-## How It Works
+If you prefer not to encrypt data, run:
 
-### Message History
+```sh
+rails generate ahoy:messages --unencrypted
+rails db:migrate
+```
 
-Ahoy creates an `Ahoy::Message` record for each email sent by default. You can disable history for a mailer:
+Then, add to mailers:
 
 ```ruby
 class CouponMailer < ApplicationMailer
-  track message: false # use only/except to limit actions
+  has_history
 end
 ```
 
-Or by default:
+Use the `Ahoy::Message` model to query messages:
 
 ```ruby
-AhoyEmail.default_options[:message] = false
+Ahoy::Message.last
 ```
 
-### Users
+Use only and except to limit actions
+
+```ruby
+class CouponMailer < ApplicationMailer
+  has_history only: [:welcome]
+end
+```
 
-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.
+To store history for all mailers, create `config/initializers/ahoy_email.rb` with:
+
+```ruby
+AhoyEmail.default_options[:message] = true
+```
 
-By default, Ahoy tries `@user` then `params[:user]` then `User.find_by(email: message.to.first)` to find the user.
+### Users
 
-You can pass a specific user with:
+By default, Ahoy Email tries `@user` then `params[:user]` then `User.find_by(email: message.to)` to find the user. You can pass a specific user with:
 
 ```ruby
 class CouponMailer < ApplicationMailer
-  track user: -> { params[:some_user] }
+  has_history user: -> { params[:some_user] }
 end
 ```
 
@@ -79,25 +96,23 @@ And run:
 user.messages
 ```
 
-### Extra Attributes
-
-Record extra attributes on the `Ahoy::Message` model.
+### Extra Data
 
-Create a migration to add extra attributes to the `ahoy_messages` table. For example:
+Add extra data to messages. Create a migration like:
 
 ```ruby
-class AddCouponIdToAhoyMessages < ActiveRecord::Migration[5.2]
+class AddCouponIdToAhoyMessages < ActiveRecord::Migration[6.1]
   def change
     add_column :ahoy_messages, :coupon_id, :integer
   end
 end
 ```
 
-Then use:
+And use:
 
 ```ruby
 class CouponMailer < ApplicationMailer
-  track extra: {coupon_id: 1}
+  has_history extra: {coupon_id: 1}
 end
 ```
 
@@ -105,213 +120,244 @@ You can use a proc as well.
 
 ```ruby
 class CouponMailer < ApplicationMailer
-  track extra: -> { {coupon_id: params[:coupon].id} }
+  has_history extra: -> { {coupon_id: params[:coupon].id} }
 end
 ```
 
-### UTM Tagging
+### Options
 
-Automatically add UTM parameters to links.
+Set global options
 
 ```ruby
-class CouponMailer < ApplicationMailer
-  track utm_params: true # use only/except to limit actions
-end
+AhoyEmail.default_options[:user] = -> { params[:admin] }
 ```
 
-The defaults are:
+Use a different model
 
-- `utm_medium` - `email`
-- `utm_source` - the mailer name like `coupon_mailer`
-- `utm_campaign` - the mailer action like `offer`
+```ruby
+AhoyEmail.message_model = -> { UserMessage }
+```
 
-You can customize them with:
+Or fully customize how messages are tracked
 
 ```ruby
-class CouponMailer < ApplicationMailer
-  track utm_params: true, utm_campaign: -> { "coupon#{params[:coupon].id}" }
+AhoyEmail.track_method = lambda do |data|
+  # your code
 end
 ```
 
-Skip specific links with:
+### Data Retention
 
-```erb
-<%= link_to "Go", some_url, data: {skip_utm_params: true} %>
+Delete older data with:
+
+```ruby
+Ahoy::Message.where("created_at < ?", 1.year.ago).in_batches.delete_all
 ```
 
-### Opens & Clicks
+Delete data for a specific user with:
 
-#### Setup
+```ruby
+Ahoy::Message.where(user_id: 1).in_batches.delete_all
+```
 
-Additional setup is required to track opens and clicks.
+## UTM Tagging
 
-Create a migration with:
+Use UTM tagging to attribute visits or conversions to an email campaign. Add UTM parameters to links with:
 
 ```ruby
-class AddTokenToAhoyMessages < ActiveRecord::Migration[5.2]
-  def change
-    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
+class CouponMailer < ApplicationMailer
+  utm_params
 end
 ```
 
-Create an initializer `config/initializers/ahoy_email.rb` with:
+The defaults are:
+
+- `utm_medium` - `email`
+- `utm_source` - the mailer name like `coupon_mailer`
+- `utm_campaign` - the mailer action like `offer`
+
+You can customize them with:
 
 ```ruby
-AhoyEmail.api = true
+class CouponMailer < ApplicationMailer
+  utm_params utm_campaign: -> { "coupon#{params[:coupon].id}" }
+end
 ```
 
-And add to mailers you want to track:
+Use only and except to limit actions
 
 ```ruby
 class CouponMailer < ApplicationMailer
-  track open: true, click: true # use only/except to limit actions
+  utm_params only: [:welcome]
 end
 ```
 
-#### How It Works
+Skip specific links with:
 
-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.
+```erb
+<%= link_to "Go", some_url, data: {skip_utm_params: true} %>
+```
 
-For clicks, a redirect is added to links to track clicks in HTML emails.
+## Click Analytics
 
-```
-https://chartkick.com
-```
+You can track click-through rate to see how well campaigns are performing. Stats can be stored in your database, Redis, or any other data store.
 
-becomes
+#### Database
 
-```
-https://yoursite.com/ahoy/messages/rAnDoMtOkEn/click?url=https%3A%2F%2Fchartkick.com&signature=...
-```
+Run:
 
-A signature is added to prevent [open redirects](https://www.owasp.org/index.php/Open_redirect).
+```sh
+rails generate ahoy:clicks
+rails db:migrate
+```
 
-Skip specific links with:
+And create `config/initializers/ahoy_email.rb` with:
 
-```erb
-<%= link_to "Go", some_url, data: {skip_click: true} %>
+```ruby
+AhoyEmail.subscribers << AhoyEmail::DatabaseSubscriber
+AhoyEmail.api = true
 ```
 
-By default, unsubscribe links are excluded. To change this, use:
+#### Redis
+
+Add this line to your application’s Gemfile:
 
 ```ruby
-AhoyEmail.default_options[:unsubscribe_links] = true
+gem 'redis'
 ```
 
-You can specify the domain to use with:
+And create `config/initializers/ahoy_email.rb` with:
 
 ```ruby
-AhoyEmail.default_options[:url_options] = {host: "mydomain.com"}
+# pass your Redis client if you already have one
+AhoyEmail.subscribers << AhoyEmail::RedisSubscriber.new(redis: Redis.new)
+AhoyEmail.api = true
 ```
 
-#### Events
+#### Other
 
-Subscribe to open and click events by adding to the initializer:
+Create `config/initializers/ahoy_email.rb` with:
 
 ```ruby
 class EmailSubscriber
-  def open(event)
+  def track_send(data)
     # your code
   end
 
-  def click(event)
+  def track_click(data)
     # your code
   end
+
+  def stats(campaign)
+    # optional, for AhoyEmail.stats
+  end
 end
 
-AhoyEmail.subscribers << EmailSubscriber.new
-```
+AhoyEmail.subscribers << EmailSubscriber
+AhoyEmail.api = true
+````
 
-Here’s an example if you use [Ahoy](https://github.com/ankane/ahoy) to track visits and events:
+### Usage
 
-```ruby
-class EmailSubscriber
-  def open(event)
-    event[:controller].ahoy.track "Email opened", message_id: event[:message].id
-  end
+Add to mailers you want to track
 
-  def click(event)
-    event[:controller].ahoy.track "Email clicked", message_id: event[:message].id, url: event[:url]
-  end
+```ruby
+class CouponMailer < ApplicationMailer
+  track_clicks campaign: "my-campaign"
 end
-
-AhoyEmail.subscribers << EmailSubscriber.new
 ```
 
-## Reference
+If storing stats in the database, the mailer should also use `has_history`
 
-Set global options
+Use only and except to limit actions
 
 ```ruby
-AhoyEmail.default_options[:user] = -> { params[:admin] }
+class CouponMailer < ApplicationMailer
+  track_clicks campaign: "my-campaign", only: [:welcome]
+end
 ```
 
-Use a different model
+Or make it conditional
 
 ```ruby
-AhoyEmail.message_model = -> { UserMessage }
+class CouponMailer < ApplicationMailer
+  track_clicks campaign: "my-campaign", if: -> { params[:user].opted_in? }
+end
 ```
 
-Or fully customize how messages are tracked
+Skip specific links with:
 
-```ruby
-AhoyEmail.track_method = lambda do |data|
-  # your code
-end
+```erb
+<%= link_to "Go", some_url, data: {skip_click: true} %>
 ```
 
-## Mongoid
+By default, unsubscribe links are excluded. To change this, use:
 
-If you prefer to use Mongoid instead of ActiveRecord, create `app/models/ahoy/message.rb` with:
+```ruby
+AhoyEmail.default_options[:unsubscribe_links] = true
+```
+
+You can specify the domain to use with:
 
 ```ruby
-class Ahoy::Message
-  include Mongoid::Document
+AhoyEmail.default_options[:url_options] = {host: "mydomain.com"}
+```
 
-  belongs_to :user, polymorphic: true, optional: true, index: true
+### Stats
 
-  field :to, type: String
-  field :mailer, type: String
-  field :subject, type: String
-  field :sent_at, type: Time
-end
+Get stats for a campaign
+
+```ruby
+AhoyEmail.stats("my-campaign")
 ```
 
 ## Upgrading
 
-### 1.0
+### 2.0
+
+Ahoy Email 2.0 brings a number of changes. Here are a few to be aware of:
 
-Breaking changes
+- The `to` field is encrypted by default for new installations. If you’d like to encrypt an existing installation, install [Lockbox](https://github.com/ankane/lockbox) and [Blind Index](https://github.com/ankane/blind_index) and follow the Lockbox instructions for [migrating existing data](https://github.com/ankane/lockbox#migrating-existing-data).
 
-- UTM tagging, open tracking, and click tracking are no longer enabled by default. To enable, create an initializer with:
+  For the model, create `app/models/ahoy/message.rb` with:
 
   ```ruby
-  AhoyEmail.api = true
+  class Ahoy::Message < ActiveRecord::Base
+    self.table_name = "ahoy_messages"
 
-  AhoyEmail.default_options[:open] = true
-  AhoyEmail.default_options[:click] = true
-  AhoyEmail.default_options[:utm_params] = true
+    belongs_to :user, polymorphic: true, optional: true
+
+    encrypts :to, migrating: true
+    blind_index :to, migrating: true
+  end
   ```
 
-- Only sent emails are recorded
-- Proc options are now executed in the context of the mailer and take no arguments
+- The `track` method has been broken into:
+
+  - `has_history` for message history
+  - `utm_params` for UTM tagging
+  - `track_clicks` for click analytics
+
+- Message history is no longer enabled by default. Add `has_history` to individual mailers, or create an initializer with:
 
   ```ruby
-  # old
-  user: ->(mailer, message) { User.find_by(email: message.to.first) }
+  AhoyEmail.default_options[:message] = true
+  ```
+
+- For privacy, open tracking has been removed.
 
-  # new
-  user: -> { User.find_by(email: message.to.first) }
+- For clicks, we encourage you to try [aggregate analytics](#click-analytics) to measure the performance of campaigns. You can use a library like [Rollup](https://github.com/ankane/rollup) to aggregate existing data, then drop the `token` and `clicked_at` columns.
+
+  To keep individual analytics, use `has_history` and `track_clicks campaign: false` and create an initializer with:
+
+  ```ruby
+  AhoyEmail.save_token = true
+  AhoyEmail.subscribers << AhoyEmail::MessageSubscriber
   ```
 
-- 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
+  If you use a custom subscriber, `:message` is no longer included in click events. You can use `:token` to query the message if needed.
+
+- Users are shown a link expired page when signature verification fails instead of being redirected to the homepage when `AhoyEmail.invalid_redirect_url` is not set
 
 ## History
 
@@ -325,3 +371,12 @@ Everyone is encouraged to help improve this project. Here are a few ways you can
 - 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:
+
+```sh
+git clone https://github.com/ankane/ahoy_email.git
+cd ahoy_email
+bundle install
+bundle exec rake test
+```