ahoy_email 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c056fb39ad0a8774c23582f8a37fbea9f460d903f4f05565e31b5670b0ce615d
-  data.tar.gz: 5b489942efd5cb224f068d06d06fdd9e9e68f65d256ded15be359ccdfc4190ec
+  metadata.gz: 2998bcf65131bcbb1ae5d6b5c2d0e1bf21496571a8c8c3e96230f21c9b3b2a74
+  data.tar.gz: 4e0291a50f134fcc95cdf8626aaf368bf2cb7c4ce763bbc008691d88421abba3
 SHA512:
-  metadata.gz: 55a1a58246738297be5e07198ef58014a13596fa372cf8127a4b4670ddfb7465c09371250ff269306cfc03ef7704ec28bc716669857eb6bc40fbe3132c94564a
-  data.tar.gz: b58a064519fb0ef57a255db8a57c4b0101f0fbf029e3110f1ece205e927bb13a8e4c3d5f95888e36be41f25eed6f0dc73ee995ff546d27771604c6b4058fd392
+  metadata.gz: 9fd0fd7d531e72f1c4d930cf35d398747ec7052b3f940597f80010e07f45d37c70ddb52f9d60d2c3b9bdb49a6760ed28a353e381f87e8849c57f7a5a6b6f8871
+  data.tar.gz: 04616042077a12cea5b86dd682339f91104c201bc0ce35a95716a45bf71cad4e80c964b0b57d813090d464d7cf66e7f4edc4f2c214c00723214342e00c9eccfd

data/CHANGELOG.md

@@ -1,24 +1,29 @@
-## 1.1.0
+## 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
+## 1.0.3 (2019-02-18)
 
 - Fixed custom message model
 - Fixed `message` option with proc
 
-## 1.0.2
+## 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
 
@@ -31,91 +36,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-2019 Andrew Kane
+Copyright (c) 2014-2021 Andrew Kane
 
 MIT License
 

data/README.md

@@ -1,20 +1,12 @@
 # Ahoy Email
 
-:postbox: Email analytics for Rails
+First-party email analytics for Rails
 
-You get:
-
-- 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
 
@@ -31,11 +23,17 @@ 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
@@ -51,7 +49,7 @@ 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.
 
@@ -86,7 +84,7 @@ 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
@@ -109,9 +107,15 @@ class CouponMailer < ApplicationMailer
 end
 ```
 
-### UTM Tagging
+## UTM Tagging
+
+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:
 
-Automatically add UTM parameters to links.
+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
@@ -139,22 +143,25 @@ Skip specific links with:
 <%= 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
 ```
@@ -169,11 +176,27 @@ 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.
 
@@ -209,7 +232,7 @@ You can specify the domain to use with:
 AhoyEmail.default_options[:url_options] = {host: "mydomain.com"}
 ```
 
-#### Events
+### Events
 
 Subscribe to open and click events by adding to the initializer:
 
@@ -245,7 +268,7 @@ 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:
 
@@ -254,11 +277,25 @@ 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
@@ -283,7 +320,7 @@ 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
@@ -298,37 +335,6 @@ class Ahoy::Message
 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)
@@ -342,11 +348,11 @@ Everyone is encouraged to help improve this project. Here are a few ways you can
 - 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
 ```

data/app/controllers/ahoy/messages_controller.rb

@@ -8,6 +8,7 @@ module Ahoy
     before_action :set_message
 
     def open
+      # TODO move to MessageSubscriber in 2.0
       if @message && !@message.opened_at
         @message.opened_at = Time.now
         @message.save!
@@ -19,6 +20,7 @@ module Ahoy
     end
 
     def click
+      # TODO move to MessageSubscriber in 2.0
       if @message && !@message.clicked_at
         @message.clicked_at = Time.now
         @message.opened_at ||= @message.clicked_at if @message.respond_to?(:opened_at=)
@@ -37,6 +39,7 @@ module Ahoy
 
         redirect_to url
       else
+        # TODO show link expired page with link to invalid redirect url in 2.0
         redirect_to AhoyEmail.invalid_redirect_url || main_app.root_url
       end
     end
@@ -44,14 +47,22 @@ module Ahoy
     protected
 
     def set_message
-      @message = AhoyEmail.message_model.where(token: params[:id]).first
+      @token =  params[:id]
+
+      model = AhoyEmail.message_model
+
+      return if model.respond_to?(:column_names) && !model.column_names.include?("token")
+
+      @message = model.where(token: @token).first
     end
 
     def publish(name, event = {})
       AhoyEmail.subscribers.each do |subscriber|
+        subscriber = subscriber.new if subscriber.is_a?(Class) && !subscriber.respond_to?(name)
         if subscriber.respond_to?(name)
           event[:message] = @message
           event[:controller] = self
+          event[:token] = @token
           subscriber.send name, event
         end
       end

data/lib/ahoy_email.rb

@@ -29,7 +29,7 @@ module AhoyEmail
     utm_term: nil,
     utm_content: nil,
     utm_campaign: -> { action_name },
-    user: -> { @user || (respond_to?(:params) && params && params[:user]) || (message.to.try(:size) == 1 ? (User.find_by(email: message.to.first) rescue nil) : nil) },
+    user: -> { (defined?(@user) && @user) || (respond_to?(:params) && params && params[:user]) || (message.to.try(:size) == 1 ? (User.find_by(email: message.to.first) rescue nil) : nil) },
     mailer: -> { "#{self.class.name}##{action_name}" },
     url_options: {},
     extra: {},

data/lib/ahoy_email/processor.rb

@@ -84,6 +84,7 @@ module AhoyEmail
       if html_part?
         part = message.html_part || message
 
+        # TODO use Nokogiri::HTML::DocumentFragment.parse in 2.0
         doc = Nokogiri::HTML(part.body.raw_source)
         doc.css("a[href]").each do |link|
           uri = parse_uri(link["href"])
@@ -115,6 +116,12 @@ module AhoyEmail
           end
         end
 
+        # ampersands converted to &
+        # https://github.com/sparklemotion/nokogiri/issues/1127
+        # not ideal, but should be equivalent in html5
+        # https://stackoverflow.com/questions/15776556/whats-the-difference-between-and-amp-in-html5
+        # escaping technically required before html5
+        # https://stackoverflow.com/questions/3705591/do-i-encode-ampersands-in-a-href
         part.body = doc.to_s
       end
     end

data/lib/ahoy_email/version.rb

@@ -1,3 +1,3 @@
 module AhoyEmail
-  VERSION = "1.1.0"
+  VERSION = "1.1.1"
 end

data/lib/generators/ahoy_email/templates/install.rb.tt

@@ -5,7 +5,7 @@ class <%= migration_class_name %> < ActiveRecord::Migration<%= migration_version
       t.text :to
       t.string :mailer
       t.text :subject
-      t.timestamp :sent_at
+      t.datetime :sent_at
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ahoy_email
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Andrew Kane
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2019-07-16 00:00:00.000000000 Z
+date: 2021-03-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionmailer
@@ -150,8 +150,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: 
-email: andrew@chartkick.com
+description:
+email: andrew@ankane.org
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -176,7 +176,7 @@ homepage: https://github.com/ankane/ahoy_email
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -191,8 +191,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.4
-signing_key: 
+rubygems_version: 3.2.3
+signing_key:
 specification_version: 4
-summary: Email analytics for Rails
+summary: First-party email analytics for Rails
 test_files: []