ahoy_email 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 099588e69bfa92fd90438816b1a5ef6857fb2f23
-  data.tar.gz: b9c49ef5f702558434df01c199c8eacd93d80bb3
+  metadata.gz: 5c6f895cc438acdeb4982e684a4ba32efc86c05b
+  data.tar.gz: 19750f27ae10e0828b4f3e7813c3a236413fa1b1
 SHA512:
-  metadata.gz: 27f621400f1b6c2f85408f4e68c43a7cdd420b8b1496ba27b6715190a60c792a105762b1e6e1daa1ea04e31c12ca301618a9d93c4b483ce3eff820f4d7f0e350
-  data.tar.gz: df563aa16ce94a7197248a449de900f3501349d9b77450a294ed2e2b038e74702e040c7ee49f22e920ba8e9cb95e14b4865a08c7a0ceee6a07a163b0fd26c050
+  metadata.gz: 88ba353c711f596a745a8c406a222859c517c1392571791d91c833713d46a56a15f313428eae6af39e042b7c8ffc8aa1b75db969d1f950def5b824bb6b95fe19
+  data.tar.gz: 082bba0e14fab78aba984e1d3e1b94ce08841c092ff24e834804bf15478c8cc02c2050df8ab1c15701530158d30954222261f86c7ac09abcbc24bca6ee4a62be

data/CHANGELOG.md

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

data/README.md

@@ -27,15 +27,102 @@ rake db:migrate
 
 ## How It Works
 
-Ahoy creates an `Ahoy::Message` record when an email is sent. It also adds:
+Ahoy creates an `Ahoy::Message` record when an email is sent.
 
-- open tracking
-- click tracking
-- UTM parameters
+### Open
+
+An invisible pixel is added right before the closing `</body>` tag to HTML emails.
+
+If a recipient has images enabled in his / her email client, the pixel is loaded and an open is recorded.
+
+### Click
+
+Links in HTML emails are rewritten to pass through your server.
+
+````
+http://chartkick.com
+```
+
+becomes
+
+```
+http://yoursite.com/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>`.
+
+### UTM Parameters
+
+UTM parameters are added to each link if they don’t already exist.
+
+By default, `utm_medium` is set to `email`.
+
+### User
+
+To specify the user, use:
+
+```ruby
+class UserMailer < ActionMailer::Base
+  def welcome_email(user)
+    # ...
+    ahoy 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
+
+There are 3 places to set options.
+
+### Global
+
+The defaults are listed below.
+
+```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
+}
+```
+
+### Mailers
+
+```ruby
+class UserMailer < ActionMailer::Base
+  ahoy utm_campaign: "boom"
+end
+```
+
+### Action
+
+``` ruby
+class UserMailer < ActionMailer::Base
+  def welcome_email(user)
+    # ...
+    ahoy user: user
+    mail to: user.email
+  end
+end
+```
 
 ## TODO
 
-- Subscription management (lists, opt-outs)
+- Subscription management (lists, opt-outs) [separate gem]
+
+## History
+
+View the [changelog](https://github.com/ankane/ahoy_email/blob/master/CHANGELOG.md)
 
 ## Contributing
 

data/ahoy_email.gemspec

@@ -19,6 +19,8 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "actionmailer"
+  spec.add_dependency "addressable"
+  spec.add_dependency "nokogiri"
 
   spec.add_development_dependency "bundler", "~> 1.6"
   spec.add_development_dependency "rake"

data/app/controllers/ahoy/messages_controller.rb

@@ -1,8 +1,33 @@
 module Ahoy
   class MessagesController < ActionController::Base
+    before_filter :set_message
 
     def open
-      puts "OPENED!"
+      if @message and !@message.opened_at
+        @message.opened_at = Time.now
+        @message.save!
+      end
+      send_data Base64.decode64("R0lGODlhAQABAPAAAAAAAAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw=="), type: "image/gif", disposition: "inline"
+    end
+
+    def click
+      if @message and !@message.clicked_at
+        @message.clicked_at = Time.now
+        @message.save!
+      end
+      url = params[:url]
+      signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::Digest.new("sha1"), AhoyEmail.secret_token, url)
+      if params[:signature] == signature
+        redirect_to url
+      else
+        redirect_to main_app.root_url
+      end
+    end
+
+    protected
+
+    def set_message
+      @message = Ahoy::Message.where(token: params[:id]).first
     end
 
   end

data/app/models/ahoy/message.rb

@@ -1,4 +1,7 @@
 module Ahoy
   class Message < ActiveRecord::Base
+    self.table_name = "ahoy_messages"
+
+    belongs_to :user, polymorphic: true
   end
 end

data/config/routes.rb

@@ -3,7 +3,10 @@ Rails.application.routes.draw do
 end
 
 AhoyEmail::Engine.routes.draw do
-  resources :messages, only: [] do
-    get :open, on: :collection
+  scope module: "ahoy" do
+    resources :messages, only: [] do
+      get :open, on: :member
+      get :click, on: :member
+    end
   end
 end

data/lib/ahoy_email.rb

@@ -1,6 +1,53 @@
 require "ahoy_email/version"
 require "action_mailer"
+require "nokogiri"
+require "addressable/uri"
+require "openssl"
+require "ahoy_email/processor"
 require "ahoy_email/interceptor"
 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,
+    utm_medium: "email",
+    utm_term: nil,
+    utm_content: nil,
+    utm_campaign: 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
+
+  end
+end

data/lib/ahoy_email/engine.rb

@@ -1,5 +1,9 @@
 module AhoyEmail
   class Engine < ::Rails::Engine
-    isolate_namespace AhoyEmail
+
+    initializer "ahoy_email" do |app|
+      AhoyEmail.secret_token = app.config.try(:secret_key_base) || app.config.try(:secret_token)
+    end
+
   end
 end

data/lib/ahoy_email/interceptor.rb

@@ -1,24 +1,11 @@
 module AhoyEmail
   class Interceptor
-    # include ActionView::Helpers::AssetTagHelper
+    class << self
 
-    def self.delivering_email(message)
-      # body = (message.html_part || message).body.raw_source
-      # p AhoyEmail::Engine.routes
-      # if body
-      #   regex = /<\/body>/i
-      #   pixel = image_tag(AhoyEmail::Engine.routes.url_helpers.url_for(controller: "messages", action: "open"))
-      #   if body.match(regex)
-      #     body.gsub!(regex, "#{pixel}\\0")
-      #   else
-      #     body << pixel
-      #   end
-      # end
-      Ahoy::Message.create!(
-        subject: message.subject,
-        content: message.to_s
-      )
-    end
+      def delivering_email(message)
+        AhoyEmail::Processor.new(message).mark_sent!
+      end
 
+    end
   end
 end

data/lib/ahoy_email/processor.rb

@@ -0,0 +1,143 @@
+module AhoyEmail
+  class Processor
+    include ActionView::Helpers::AssetTagHelper
+
+    attr_reader :message, :options, :ahoy_message
+
+    def initialize(message, options = {})
+      @message = message
+      @options = options
+      @ahoy_message = Ahoy::Message.new
+    end
+
+    def process!
+      if options[:create_message]
+        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]
+
+        # 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
+      end
+    rescue => e
+      report_error(e)
+    end
+
+    def mark_sent!
+      if (message_id = message["Ahoy-Message-Id"])
+        ahoy_message = Ahoy::Message.where(id: message_id).first
+        if ahoy_message
+          ahoy_message.sent_at = Time.now
+          ahoy_message.save
+        end
+        message["Ahoy-Message-Id"] = nil
+      end
+    rescue => e
+      report_error(e)
+    end
+
+    protected
+
+    def generate_token
+      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!
+      if html_part?
+        raw_source = (message.html_part || message).body.raw_source
+        regex = /<\/body>/i
+        url =
+          AhoyEmail::Engine.routes.url_helpers.url_for(
+            Rails.application.config.action_mailer.default_url_options.merge(
+              controller: "ahoy/messages",
+              action: "open",
+              id: ahoy_message.token,
+              format: "gif"
+            )
+          )
+        pixel = image_tag(url, size: "1x1", alt: nil)
+
+        # try to add before body tag
+        if raw_source.match(regex)
+          raw_source.gsub!(regex, "#{pixel}\\0")
+        else
+          raw_source << pixel
+        end
+      end
+    end
+
+    def track_click!
+      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
+            signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::Digest.new("sha1"), AhoyEmail.secret_token, link["href"])
+            url =
+              AhoyEmail::Engine.routes.url_helpers.url_for(
+                Rails.application.config.action_mailer.default_url_options.merge(
+                  controller: "ahoy/messages",
+                  action: "click",
+                  id: ahoy_message.token,
+                  url: link["href"],
+                  signature: signature
+                )
+              )
+
+            link["href"] = url
+          end
+        end
+
+        # hacky
+        body.raw_source.sub!(body.raw_source, doc.to_s)
+      end
+    end
+
+    def html_part?
+      (message.html_part || message).content_type =~ /html/
+    end
+
+    # not a fan of quiet errors
+    # but tracking should *not* break
+    # email delivery in production
+    def report_error(e)
+      if Rails.env.production?
+        $stderr.puts e
+      else
+        raise e
+      end
+    end
+
+  end
+end

data/lib/ahoy_email/version.rb

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

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

@@ -1,11 +1,13 @@
 class <%= migration_class_name %> < ActiveRecord::Migration
   def change
     create_table :ahoy_messages do |t|
+      t.string :token
+
       # user
       t.integer :user_id
       t.string :user_type
 
-      # message
+      # optional
       t.text :subject
       t.text :content
 
@@ -15,6 +17,7 @@ class <%= migration_class_name %> < ActiveRecord::Migration
       t.timestamp :clicked_at
     end
 
+    add_index :ahoy_messages, [:token]
     add_index :ahoy_messages, [:user_id, :user_type]
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ahoy_email
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Andrew Kane
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-28 00:00:00.000000000 Z
+date: 2014-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionmailer
@@ -24,6 +24,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: addressable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -60,6 +88,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -71,6 +100,7 @@ files:
 - lib/ahoy_email.rb
 - lib/ahoy_email/engine.rb
 - lib/ahoy_email/interceptor.rb
+- lib/ahoy_email/processor.rb
 - lib/ahoy_email/version.rb
 - lib/generators/ahoy_email/install_generator.rb
 - lib/generators/ahoy_email/templates/install.rb