ahoy_email 1.1.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2998bcf65131bcbb1ae5d6b5c2d0e1bf21496571a8c8c3e96230f21c9b3b2a74
-  data.tar.gz: 4e0291a50f134fcc95cdf8626aaf368bf2cb7c4ce763bbc008691d88421abba3
+  metadata.gz: d178d2bd4a2631bad0bce962cd35daecc019034270530f350596d14172e46ca0
+  data.tar.gz: af5eb88ec75a4100c5215a71e39fb825d7c7e4823fd601c3cd6473b7409db3dd
 SHA512:
-  metadata.gz: 9fd0fd7d531e72f1c4d930cf35d398747ec7052b3f940597f80010e07f45d37c70ddb52f9d60d2c3b9bdb49a6760ed28a353e381f87e8849c57f7a5a6b6f8871
-  data.tar.gz: 04616042077a12cea5b86dd682339f91104c201bc0ce35a95716a45bf71cad4e80c964b0b57d813090d464d7cf66e7f4edc4f2c214c00723214342e00c9eccfd
+  metadata.gz: bcc3ac25d9a8323a4da3a4331a338ca377a375033886c9e447945654897ea3b89e178ffe7a4e02336838ba27e1b8f8dda0aef0f5261f1adb8c66167dbe758f98
+  data.tar.gz: b433434716662eb90d9309c6dfdefe61752496777206e43d1d1d9ddadfee9aa664cf1daa1272d4df62a393d6e979e62932194829dd68b84720fd47661fada6e0

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+## 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

data/README.md

@@ -2,6 +2,8 @@
 
 First-party email analytics for Rails
 
+**Ahoy Email 2.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)
@@ -16,48 +18,65 @@ Add this line to your application’s Gemfile:
 gem 'ahoy_email'
 ```
 
-And run the generator. This creates a model to store messages.
-
-```sh
-rails generate ahoy_email:install
-rails db:migrate
-```
-
 ## Getting Started
 
-There are three main features:
+There are three main features, which can be used independently:
 
 - [Message history](#message-history)
 - [UTM tagging](#utm-tagging)
-- [Open & click analytics](#open--click-analytics)
+- [Click analytics](#click-analytics)
 
 ## Message History
 
-Ahoy Email creates an `Ahoy::Message` record for each email sent by default. You can disable history for a mailer:
+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:messages
+rails db:migrate
+```
+
+If you prefer not to encrypt data, run:
+
+```sh
+rails generate ahoy:messages --unencrypted
+rails db:migrate
+```
+
+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
+```
+
+To store history for all mailers, create `config/initializers/ahoy_email.rb` with:
 
-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.
+```ruby
+AhoyEmail.default_options[:message] = true
+```
 
-By default, Ahoy tries `@user` then `params[:user]` then `User.find_by(email: message.to)` 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
 ```
 
@@ -77,11 +96,9 @@ And run:
 user.messages
 ```
 
-### Extra Attributes
+### Extra Data
 
-Record extra attributes on the `Ahoy::Message` model.
-
-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[6.1]
@@ -91,11 +108,11 @@ class AddCouponIdToAhoyMessages < ActiveRecord::Migration[6.1]
 end
 ```
 
-Then use:
+And use:
 
 ```ruby
 class CouponMailer < ApplicationMailer
-  track extra: {coupon_id: 1}
+  has_history extra: {coupon_id: 1}
 end
 ```
 
@@ -103,23 +120,53 @@ 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
 
-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:
+Set global options
 
-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))
+```ruby
+AhoyEmail.default_options[:user] = -> { params[:admin] }
+```
 
-Add UTM parameters to links with:
+Use a different model
+
+```ruby
+AhoyEmail.message_model = -> { UserMessage }
+```
+
+Or fully customize how messages are tracked
+
+```ruby
+AhoyEmail.track_method = lambda do |data|
+  # your code
+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
+```
+
+## UTM Tagging
+
+Use UTM tagging to attribute visits or conversions to an email campaign. Add UTM parameters to links with:
 
 ```ruby
 class CouponMailer < ApplicationMailer
-  track utm_params: true # use only/except to limit actions
+  utm_params
 end
 ```
 
@@ -133,7 +180,15 @@ You can customize them with:
 
 ```ruby
 class CouponMailer < ApplicationMailer
-  track utm_params: true, utm_campaign: -> { "coupon#{params[:coupon].id}" }
+  utm_params utm_campaign: -> { "coupon#{params[:coupon].id}" }
+end
+```
+
+Use only and except to limit actions
+
+```ruby
+class CouponMailer < ApplicationMailer
+  utm_params only: [:welcome]
 end
 ```
 
@@ -143,40 +198,56 @@ Skip specific links with:
 <%= link_to "Go", some_url, data: {skip_utm_params: true} %>
 ```
 
-## Open & Click Analytics
+## Click Analytics
 
-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.
+You can track click-through rate to see how well campaigns are performing. Stats can be stored in any data store, and there’s a built-in integration with Redis.
 
-### Setup
+#### Redis
 
-Create a migration with:
+Add this line to your application’s Gemfile:
 
 ```ruby
-class AddTokenToAhoyMessages < ActiveRecord::Migration[6.1]
-  def change
-    add_column :ahoy_messages, :token, :string
-    add_index :ahoy_messages, :token
+gem 'redis'
+```
 
-    # for opens
-    add_column :ahoy_messages, :opened_at, :timestamp
+And create `config/initializers/ahoy_email.rb` with:
 
-    # for clicks
-    add_column :ahoy_messages, :clicked_at, :timestamp
-  end
-end
+```ruby
+# pass your Redis client if you already have one
+AhoyEmail.subscribers << AhoyEmail::RedisSubscriber.new(redis: Redis.new)
+AhoyEmail.api = true
 ```
 
-Create an initializer `config/initializers/ahoy_email.rb` with:
+#### Other
+
+Create `config/initializers/ahoy_email.rb` with:
 
 ```ruby
+class EmailSubscriber
+  def track_send(data)
+    # your code
+  end
+
+  def track_click(data)
+    # your code
+  end
+
+  def stats(campaign = nil)
+    # optional, for AhoyEmail.stats
+  end
+end
+
+AhoyEmail.subscribers << EmailSubscriber
 AhoyEmail.api = true
-```
+````
 
-And add to mailers you want to track:
+### Setup
+
+Add to mailers you want to track
 
 ```ruby
 class CouponMailer < ApplicationMailer
-  track open: true, click: true
+  track_clicks campaign: "my-campaign"
 end
 ```
 
@@ -184,7 +255,7 @@ Use only and except to limit actions
 
 ```ruby
 class CouponMailer < ApplicationMailer
-  track click: true, only: [:welcome]
+  track_clicks campaign: "my-campaign", only: [:welcome]
 end
 ```
 
@@ -192,28 +263,10 @@ Or make it conditional
 
 ```ruby
 class CouponMailer < ApplicationMailer
-  track click: -> { params[:user].opted_in? }
+  track_clicks campaign: "my-campaign", if: -> { 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.
-
-```
-https://chartkick.com
-```
-
-becomes
-
-```
-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).
-
 Skip specific links with:
 
 ```erb
@@ -232,108 +285,67 @@ You can specify the domain to use with:
 AhoyEmail.default_options[:url_options] = {host: "mydomain.com"}
 ```
 
-### Events
+### Stats
 
-Subscribe to open and click events by adding to the initializer:
+Get stats for all campaigns
 
 ```ruby
-class EmailSubscriber
-  def open(event)
-    # your code
-  end
-
-  def click(event)
-    # your code
-  end
-end
-
-AhoyEmail.subscribers << EmailSubscriber.new
+AhoyEmail.stats
 ```
 
-Here’s an example if you use [Ahoy](https://github.com/ankane/ahoy) to track visits and events:
+Get stats for a specific campaign
 
 ```ruby
-class EmailSubscriber
-  def open(event)
-    event[:controller].ahoy.track "Email opened", message_id: event[:message].id
-  end
-
-  def click(event)
-    event[:controller].ahoy.track "Email clicked", message_id: event[:message].id, url: event[:url]
-  end
-end
-
-AhoyEmail.subscribers << EmailSubscriber.new
+AhoyEmail.stats("my-campaign")
 ```
 
-## Data Protection
-
-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.
+## Upgrading
 
-Create `app/models/ahoy/message.rb` with:
+### 2.0
 
-```ruby
-class Ahoy::Message < ApplicationRecord
-  self.table_name = "ahoy_messages"
-  belongs_to :user, polymorphic: true, optional: true
+Ahoy Email 2.0 brings a number of changes. Here are a few to be aware of:
 
-  encrypts :to
-  blind_index :to
-end
-```
+- 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).
 
-## Data Retention
-
-Delete older data with:
+  For the model, create `app/models/ahoy/message.rb` 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
-```
+  ```ruby
+  class Ahoy::Message < ActiveRecord::Base
+    self.table_name = "ahoy_messages"
 
-## Reference
+    belongs_to :user, polymorphic: true, optional: true
 
-Set global options
+    encrypts :to, migrating: true
+    blind_index :to, migrating: true
+  end
+  ```
 
-```ruby
-AhoyEmail.default_options[:user] = -> { params[:admin] }
-```
+- The `track` method has been broken into:
 
-Use a different model
+  - `has_history` for message history
+  - `utm_params` for UTM tagging
+  - `track_clicks` for click analytics
 
-```ruby
-AhoyEmail.message_model = -> { UserMessage }
-```
+- Message history is no longer enabled by default. Add `has_history` to individual mailers, or create an initializer with:
 
-Or fully customize how messages are tracked
+  ```ruby
+  AhoyEmail.default_options[:message] = true
+  ```
 
-```ruby
-AhoyEmail.track_method = lambda do |data|
-  # your code
-end
-```
+- For privacy, open tracking has been removed.
 
-## Mongoid
+- 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.
 
-If you prefer to use Mongoid instead of Active Record, create `app/models/ahoy/message.rb` with:
+  To keep individual analytics, use `has_history` and `track_clicks campaign: false` and create an initializer with:
 
-```ruby
-class Ahoy::Message
-  include Mongoid::Document
+  ```ruby
+  AhoyEmail.save_token = true
+  AhoyEmail.subscribers << AhoyEmail::MessageSubscriber
+  ```
 
-  belongs_to :user, polymorphic: true, optional: true, index: true
+  If you use a custom subscriber, `:message` is no longer included in click events. You can use `:token` to query the message if needed.
 
-  field :to, type: String
-  field :mailer, type: String
-  field :subject, type: String
-  field :sent_at, type: Time
-end
-```
+- 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