ahoy_email 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5c6f895cc438acdeb4982e684a4ba32efc86c05b
-  data.tar.gz: 19750f27ae10e0828b4f3e7813c3a236413fa1b1
+  metadata.gz: 7d245ad6df5fbb64f6b38292b8b139a1382dda4e
+  data.tar.gz: cd822e8f05cf9eb01a1c37979b67428c2c7fd999
 SHA512:
-  metadata.gz: 88ba353c711f596a745a8c406a222859c517c1392571791d91c833713d46a56a15f313428eae6af39e042b7c8ffc8aa1b75db969d1f950def5b824bb6b95fe19
-  data.tar.gz: 082bba0e14fab78aba984e1d3e1b94ce08841c092ff24e834804bf15478c8cc02c2050df8ab1c15701530158d30954222261f86c7ac09abcbc24bca6ee4a62be
+  metadata.gz: 7c598c2697d2ca2167e2ccb6e5fdedb20a27f831f71b0f7ed0a4907d9b4646e24f6cd02cdbb7be54328dfec81cf9b353d57a3c80bd08cbf21a510b58e3da4463
+  data.tar.gz: a0649a7c6a0c575dc87a8aac7d36e1a53aab6d475c198a04131597001797442d1f3cdcedd442ec3f5f2ba4f64b3a2e4d9ab8d26af1d43d9984d7b060ea181d10

data/CHANGELOG.md

@@ -1,3 +1,3 @@
-## 0.1.0 [unreleased]
+## 0.1.0
 
 - First major release

data/README.md

@@ -1,14 +1,14 @@
 # Ahoy Email
 
-:construction: Coming soon - May 1, 2014
+:postbox: Simple, powerful email tracking for Rails
 
-:envelope: Simple, powerful email tracking for Rails
+You get:
 
-Keep track of emails:
+- A history of emails sent to each user
+- Open and click tracking
+- Easy UTM tagging
 
-- sent
-- opened
-- clicked
+Works with any email service.
 
 ## Installation
 
@@ -27,17 +27,53 @@ rake db:migrate
 
 ## How It Works
 
-Ahoy creates an `Ahoy::Message` record when an email is sent.
+Ahoy creates an `Ahoy::Message` every time an email is sent by default.
 
-### Open
+### Users
 
-An invisible pixel is added right before the closing `</body>` tag to HTML emails.
+Ahoy tracks 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.
 
-If a recipient has images enabled in his / her email client, the pixel is loaded and an open is recorded.
+By default, Ahoy tries `User.where(email: message.to.first).first` to find the user.
 
-### Click
+You can pass a specific user with:
 
-Links in HTML emails are rewritten to pass through your server.
+```ruby
+class UserMailer < ActionMailer::Base
+  def welcome_email(user)
+    # ...
+    track user: user
+    mail to: user.email
+  end
+end
+```
+
+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"
+end
+```
+
+And run:
+
+```ruby
+user.messages
+```
+
+### 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.
+
+Use `track open: false` to skip this.
+
+### Clicks
+
+A redirect is added to links to track clicks in HTML emails.
 
 ````
 http://chartkick.com
@@ -46,78 +82,94 @@ http://chartkick.com
 becomes
 
 ```
-http://yoursite.com/ahoy/messages/rAnDoMtOken/click?url=http%3A%2F%2Fchartkick.com&signature=...
+http://you.io/ahoy/messages/rAnDoMtOkEn/click?url=http%3A%2F%2Fchartkick.com&signature=...
 ```
 
 A signature is added to prevent [open redirects](https://www.owasp.org/index.php/Open_redirect).
 
-Keep specific links from being tracked with `<a data-disable-tracking="true" href="..."></a>`.
+Use `track click: false` to skip tracking, or skip specific links with:
+
+```html
+<a data-skip-click="true" href="...">Can't touch this</a>
+```
 
 ### UTM Parameters
 
-UTM parameters are added to each link if they don’t already exist.
+UTM parameters are added to links if they don’t already exist.
 
-By default, `utm_medium` is set to `email`.
+The defaults are:
 
-### User
+- utm_medium - `email`
+- utm_source - the mailer name like `user_mailer`
+- utm_campaign - the mailer action like `welcome_email`
 
-To specify the user, use:
+Use `track utm_params: false` to skip tagging, or skip specific links with:
 
-```ruby
+
+```html
+<a data-skip-utm-params="true" href="...">Break it down</a>
+```
+
+## Customize
+
+There are 3 places to set options. Here’s the order of precedence.
+
+### Action
+
+``` ruby
 class UserMailer < ActionMailer::Base
   def welcome_email(user)
     # ...
-    ahoy user: user
+    track user: user
     mail to: user.email
   end
 end
 ```
 
-User is [polymorphic](http://railscasts.com/episodes/154-polymorphic-association), so use it with any model.
-
-## Customize
+### Mailer
 
-There are 3 places to set options.
+```ruby
+class UserMailer < ActionMailer::Base
+  track utm_campaign: "boom"
+end
+```
 
 ### Global
 
-The defaults are listed below.
+```ruby
+AhoyEmail.track open: false
+```
+
+## Reference
+
+You can use a `Proc` for any option.
 
 ```ruby
-AhoyEmail.options = {
-  create_message: true,
-  track_open: true,
-  track_click: true,
-  utm_source: nil,
-  utm_medium: "email",
-  utm_term: nil,
-  utm_content: nil,
-  utm_campaign: nil
-}
+track utm_campaign: proc{|message, mailer| mailer.action_name + Time.now.year }
 ```
 
-### Mailers
+Disable tracking for an email
 
 ```ruby
-class UserMailer < ActionMailer::Base
-  ahoy utm_campaign: "boom"
-end
+track message: false
 ```
 
-### Action
+Or by default
 
-``` ruby
-class UserMailer < ActionMailer::Base
-  def welcome_email(user)
-    # ...
-    ahoy user: user
-    mail to: user.email
-  end
-end
+```ruby
+AhoyEmail.track message: false
+```
+
+Use a different model
+
+```ruby
+AhoyEmail.message_model = UserMessage
 ```
 
 ## TODO
 
+- Add tests
+- Open and click hooks for deeper analytics
 - Subscription management (lists, opt-outs) [separate gem]
 
 ## History

data/app/controllers/ahoy/messages_controller.rb

@@ -27,7 +27,7 @@ module Ahoy
     protected
 
     def set_message
-      @message = Ahoy::Message.where(token: params[:id]).first
+      @message = AhoyEmail.message_model.where(token: params[:id]).first
     end
 
   end

data/lib/ahoy_email.rb

@@ -5,49 +5,34 @@ require "addressable/uri"
 require "openssl"
 require "ahoy_email/processor"
 require "ahoy_email/interceptor"
+require "ahoy_email/mailer"
 require "ahoy_email/engine"
 
-ActionMailer::Base.register_interceptor AhoyEmail::Interceptor
-
 module AhoyEmail
   mattr_accessor :secret_token, :options
 
   self.options = {
-    create_message: true,
-    track_open: true,
-    track_click: true,
-    utm_source: nil,
+    message: true,
+    open: true,
+    click: true,
+    utm_params: true,
+    utm_source: proc {|message, mailer| mailer.mailer_name },
     utm_medium: "email",
     utm_term: nil,
     utm_content: nil,
-    utm_campaign: nil
+    utm_campaign: proc {|message, mailer| mailer.action_name },
+    user: proc{|message, mailer| User.where(email: message.to.first).first rescue nil }
   }
-end
-
-module ActionMailer
-  class Base
-    class_attribute :ahoy_options
-    self.ahoy_options = {}
-
-    class << self
-      def ahoy(options)
-        self.ahoy_options = ahoy_options.merge(options)
-      end
-    end
-
-    def ahoy(options)
-      @ahoy_options = (@ahoy_options || {}).merge(options)
-    end
 
-    def mail_with_ahoy(headers = {}, &block)
-      message = mail_without_ahoy(headers, &block)
-
-      options = AhoyEmail.options.merge(self.class.ahoy_options).merge(@ahoy_options || {})
-      AhoyEmail::Processor.new(message, options).process!
-
-      message
-    end
-    alias_method_chain :mail, :ahoy
+  def self.message_model=(message_model)
+    @message_model = message_model
+  end
 
+  def self.message_model
+    @message_model || Ahoy::Message
   end
+
 end
+
+ActionMailer::Base.send :include, AhoyEmail::Mailer
+ActionMailer::Base.register_interceptor AhoyEmail::Interceptor

data/lib/ahoy_email/interceptor.rb

@@ -3,7 +3,7 @@ module AhoyEmail
     class << self
 
       def delivering_email(message)
-        AhoyEmail::Processor.new(message).mark_sent!
+        AhoyEmail::Processor.new(message).track_send
       end
 
     end

data/lib/ahoy_email/mailer.rb

@@ -0,0 +1,38 @@
+module AhoyEmail
+  module Mailer
+
+    def self.included(base)
+      base.extend ClassMethods
+      base.class_eval do
+        class_attribute :ahoy_options
+        self.ahoy_options = {}
+        alias_method_chain :mail, :ahoy
+      end
+    end
+
+    module ClassMethods
+      def track(options)
+        self.ahoy_options = ahoy_options.merge(options)
+      end
+    end
+
+    def track(options)
+      @ahoy_options = (@ahoy_options || {}).merge(options)
+    end
+
+    def mail_with_ahoy(headers = {}, &block)
+      message = mail_without_ahoy(headers, &block)
+
+      options = AhoyEmail.options.merge(self.class.ahoy_options).merge(@ahoy_options || {})
+      options.each do |k, v|
+        if v.respond_to?(:call)
+          options[k] = v.call(message, self)
+        end
+      end
+      AhoyEmail::Processor.new(message, options).process
+
+      message
+    end
+
+  end
+end

data/lib/ahoy_email/processor.rb

@@ -7,31 +7,30 @@ module AhoyEmail
     def initialize(message, options = {})
       @message = message
       @options = options
-      @ahoy_message = Ahoy::Message.new
     end
 
-    def process!
-      if options[:create_message]
+    def process
+      if options[:message]
+        @ahoy_message = AhoyEmail.message_model.new
         ahoy_message.token = generate_token
         ahoy_message.user = options[:user]
 
-        track_utm_parameters!
-        track_open! if options[:track_open]
-        track_click! if options[:track_click]
+        track_open if options[:open]
+        track_links if options[:utm_params] or options[:click]
 
         # save
         ahoy_message.subject = message.subject if ahoy_message.respond_to?(:subject=)
         ahoy_message.content = message.to_s if ahoy_message.respond_to?(:content=)
-        ahoy_message.sent_at = Time.now
         ahoy_message.save
+        message["Ahoy-Message-Id"] = ahoy_message.id
       end
     rescue => e
       report_error(e)
     end
 
-    def mark_sent!
+    def track_send
       if (message_id = message["Ahoy-Message-Id"])
-        ahoy_message = Ahoy::Message.where(id: message_id).first
+        ahoy_message = AhoyEmail.message_model.where(id: message_id.to_s).first
         if ahoy_message
           ahoy_message.sent_at = Time.now
           ahoy_message.save
@@ -48,27 +47,7 @@ module AhoyEmail
       SecureRandom.urlsafe_base64(32).gsub(/[\-_]/, "").first(32)
     end
 
-    def track_utm_parameters!
-      if html_part?
-        body = (message.html_part || message).body
-
-        doc = Nokogiri::HTML(body.raw_source)
-        doc.css("a").each do |link|
-          uri = Addressable::URI.parse(link["href"])
-          params = uri.query_values || {}
-          %w[utm_source utm_medium utm_term utm_content utm_campaign].each do |key|
-            params[key] ||= options[key.to_sym] if options[key.to_sym]
-          end
-          uri.query_values = params
-          link["href"] = uri.to_s
-        end
-
-        # hacky
-        body.raw_source.sub!(body.raw_source, doc.to_s)
-      end
-    end
-
-    def track_open!
+    def track_open
       if html_part?
         raw_source = (message.html_part || message).body.raw_source
         regex = /<\/body>/i
@@ -92,17 +71,24 @@ module AhoyEmail
       end
     end
 
-    def track_click!
+    def track_links
       if html_part?
         body = (message.html_part || message).body
 
         doc = Nokogiri::HTML(body.raw_source)
         doc.css("a").each do |link|
-          key = "data-disable-tracking"
-          if link[key]
-            # remove attribute
-            link.remove_attribute(key)
-          else
+          # utm params first
+          if options[:utm_params] and !skip_attribute?(link, "utm-params")
+            uri = Addressable::URI.parse(link["href"])
+            params = uri.query_values || {}
+            %w[utm_source utm_medium utm_term utm_content utm_campaign].each do |key|
+              params[key] ||= options[key.to_sym] if options[key.to_sym]
+            end
+            uri.query_values = params
+            link["href"] = uri.to_s
+          end
+
+          if options[:click] and !skip_attribute?(link, "click")
             signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::Digest.new("sha1"), AhoyEmail.secret_token, link["href"])
             url =
               AhoyEmail::Engine.routes.url_helpers.url_for(
@@ -128,6 +114,17 @@ module AhoyEmail
       (message.html_part || message).content_type =~ /html/
     end
 
+    def skip_attribute?(link, suffix)
+      attribute = "data-skip-#{suffix}"
+      if link[attribute]
+        # remove it
+        link.remove_attribute(attribute)
+        true
+      else
+        false
+      end
+    end
+
     # not a fan of quiet errors
     # but tracking should *not* break
     # email delivery in production

data/lib/ahoy_email/version.rb

@@ -1,3 +1,3 @@
 module AhoyEmail
-  VERSION = "0.0.2"
+  VERSION = "0.1.0"
 end

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

@@ -8,6 +8,7 @@ class <%= migration_class_name %> < ActiveRecord::Migration
       t.string :user_type
 
       # optional
+      # feel free to remove
       t.text :subject
       t.text :content
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ahoy_email
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Andrew Kane
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-29 00:00:00.000000000 Z
+date: 2014-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionmailer
@@ -100,6 +100,7 @@ files:
 - lib/ahoy_email.rb
 - lib/ahoy_email/engine.rb
 - lib/ahoy_email/interceptor.rb
+- lib/ahoy_email/mailer.rb
 - lib/ahoy_email/processor.rb
 - lib/ahoy_email/version.rb
 - lib/generators/ahoy_email/install_generator.rb