README.md in ahoy_email-0.5.0 vs README.md in ahoy_email-0.5.1

- old
+ new

@@ -3,12 +3,12 @@ :postbox: Simple, powerful email tracking for Rails You get: - A history of emails sent to each user -- Open and click tracking - Easy UTM tagging +- Open and click tracking Works with any email service. :bullettrain_side: To manage unsubscribes, check out [Mailkick](https://github.com/ankane/mailkick) @@ -26,11 +26,11 @@ And run the generator. This creates a model to store messages. ```sh rails generate ahoy_email:install -rake db:migrate +rails db:migrate ``` ## How It Works Ahoy creates an `Ahoy::Message` every time an email is sent by default. @@ -42,11 +42,11 @@ By default, Ahoy tries `User.where(email: message.to.first).first` to find the user. You can pass a specific user with: ```ruby -class UserMailer < ActionMailer::Base +class UserMailer < ApplicationMailer def welcome_email(user) # ... track user: user mail to: user.email end @@ -56,21 +56,38 @@ 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" +class User < ApplicationRecord + has_many :messages, class_name: "Ahoy::Message", as: :user end ``` And run: ```ruby user.messages ``` +### UTM Parameters + +UTM parameters are added to links if they don’t already exist. + +The defaults are: + +- utm_medium - `email` +- utm_source - the mailer name like `user_mailer` +- utm_campaign - the mailer action like `welcome_email` + +Use `track utm_params: false` to skip tagging, or skip specific links with: + + +```html +<a data-skip-utm-params="true" href="...">Break it down</a> +``` + ### 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. @@ -97,27 +114,10 @@ ```html <a data-skip-click="true" href="...">Can't touch this</a> ``` -### UTM Parameters - -UTM parameters are added to links if they don’t already exist. - -The defaults are: - -- utm_medium - `email` -- utm_source - the mailer name like `user_mailer` -- utm_campaign - the mailer action like `welcome_email` - -Use `track utm_params: false` to skip tagging, or skip specific links with: - - -```html -<a data-skip-utm-params="true" href="...">Break it down</a> -``` - ### Extra Attributes Create a migration to add extra attributes to the `ahoy_messages` table, for example: ```ruby @@ -150,11 +150,11 @@ There are 3 places to set options. Here’s the order of precedence. #### Action ``` ruby -class UserMailer < ActionMailer::Base +class UserMailer < ApplicationMailer def welcome_email(user) # ... track user: user mail to: user.email end @@ -162,11 +162,11 @@ ``` #### Mailer ```ruby -class UserMailer < ActionMailer::Base +class UserMailer < ApplicationMailer track utm_campaign: "boom" end ``` #### Global @@ -212,11 +212,11 @@ ## Reference You can use a `Proc` for any option. ```ruby -track utm_campaign: proc { |message, mailer| mailer.action_name + Time.now.year } +track utm_campaign: ->(message, mailer) { mailer.action_name + Time.now.year } ``` Disable tracking for an email ```ruby @@ -238,9 +238,15 @@ Customize domain ```ruby track url_options: {host: "mydomain.com"} +``` + +By default, unsubscribe links are excluded from tracking. To change this, use: + +```ruby +track unsubscribe_links: true ``` Use a different model ```ruby