Ahoy Email

面向 Rails 的第一方邮件分析工具

Ahoy Email 3.0 版本已发布 - 请查看升级方法

🔥 如需 Web 和原生应用分析工具，请查看 Ahoy

🚄 如需管理邮件订阅，请查看 Mailkick

安装

在应用的 Gemfile 中添加以下代码：

gem "ahoy_email"

开始使用

有三个主要功能，可独立使用：

• 消息历史记录
• UTM 标记
• 点击分析

消息历史记录

若要使用 Lockbox 加密电子邮件地址，请安装 Lockbox 和 Blind Index，然后运行：

rails generate ahoy:messages --encryption=lockbox
rails db:migrate

要使用 Active Record 加密，请运行：

rails generate ahoy:messages --encryption=activerecord
rails db:migrate

如果您不想加密数据，请运行：

rails generate ahoy:messages --encryption=none
rails db:migrate

然后，添加到邮件发送器中：

class CouponMailer < ApplicationMailer
  has_history
end

使用 Ahoy::Message 模型查询消息：

Ahoy::Message.last

使用 only 和 except 来限制操作

class CouponMailer < ApplicationMailer
  has_history only: [:welcome]
end

要存储所有邮件程序的历史记录，请创建 config/initializers/ahoy_email.rb 文件，并添加以下内容：

AhoyEmail.default_options[:message] = true

用户

默认情况下，Ahoy Email 会尝试通过 @user、然后 params[:user]、再然后 User.find_by(email: message.to) 来查找用户。你可以通过以下方式传递特定用户：

class CouponMailer < ApplicationMailer
  has_history user: -> { params[:some_user] }
end

用户关联是多态的，因此可与任何模型配合使用。

若要获取发送给某个用户的所有消息，请添加关联：

class User < ApplicationRecord
  has_many :messages, class_name: "Ahoy::Message", as: :user
end

然后运行：

user.messages

额外数据

为邮件添加额外数据。创建如下迁移：

class AddCouponIdToAhoyMessages < ActiveRecord::Migration[8.1]
  def change
    add_column :ahoy_messages, :coupon_id, :integer
  end
end

并且使用：

class CouponMailer < ApplicationMailer
  has_history extra: {coupon_id: 1}
end

您也可以使用 proc。

class CouponMailer < ApplicationMailer
  has_history extra: -> { {coupon_id: params[:coupon].id} }
end

选项

设置全局选项

AhoyEmail.default_options[:user] = -> { params[:admin] }

使用不同的模型

AhoyEmail.message_model = -> { UserMessage }

或者完全自定义消息的跟踪方式

AhoyEmail.track_method = lambda do |data|
  # your code
end

数据保留

可通过以下方式删除较旧的数据：

Ahoy::Message.where("sent_at < ?", 1.year.ago).in_batches.delete_all

使用以下命令删除特定用户的数据：

Ahoy::Message.where(user_id: 1, user_type: "User").in_batches.delete_all

UTM 标记

使用 UTM 标记可将访问或转化归因于电子邮件营销活动。通过以下方式为链接添加 UTM 参数：

class CouponMailer < ApplicationMailer
  utm_params
end

默认值如下：

• utm_medium - email
• utm_source - 邮件发送器名称，例如 coupon_mailer
• utm_campaign - 邮件发送器操作，例如 offer

您可以通过以下方式自定义它们：

class CouponMailer < ApplicationMailer
  utm_params utm_campaign: -> { "coupon#{params[:coupon].id}" }
end

仅使用 only 和 except 来限制操作

class CouponMailer < ApplicationMailer
  utm_params only: [:welcome]
end

使用以下方式跳过特定链接：

<%= link_to "Go", some_url, data: {skip_utm_params: true} %>

点击分析

您可以追踪点击率，了解营销活动的表现情况。统计数据可存储在您的数据库、Redis 或其他任何数据存储中。

数据库

运行以下命令：

rails generate ahoy:clicks
rails db:migrate

并创建 config/initializers/ahoy_email.rb 文件，内容如下：

AhoyEmail.subscribers << AhoyEmail::DatabaseSubscriber
AhoyEmail.api = true

Redis

在应用的 Gemfile 中添加以下代码行：

gem "redis"

并创建 config/initializers/ahoy_email.rb 文件，内容如下：

# pass your Redis client if you already have one
AhoyEmail.subscribers << AhoyEmail::RedisSubscriber.new(redis: Redis.new)
AhoyEmail.api = true

其他

创建 config/initializers/ahoy_email.rb 文件，内容如下：

class EmailSubscriber
  def track_send(data)
    # your code
  end

  def track_click(data)
    # your code
  end

  def stats(campaign)
    # optional, for AhoyEmail.stats
  end
end

AhoyEmail.subscribers << EmailSubscriber
AhoyEmail.api = true

使用方法

添加到您想要跟踪的邮件程序中

class CouponMailer < ApplicationMailer
  track_clicks campaign: "my-campaign"
end

如果要将统计数据存储在数据库中，邮件程序还应使用 has_history

使用 only 和 except 来限制操作

class CouponMailer < ApplicationMailer
  track_clicks campaign: "my-campaign", only: [:welcome]
end

或者让它具备条件性

class CouponMailer < ApplicationMailer
  track_clicks campaign: "my-campaign", if: -> { params[:user].opted_in? }
end

你也可以使用 proc

class CouponMailer < ApplicationMailer
  track_clicks campaign: -> { "coupon-#{action_name}" }
end

使用以下方式跳过特定链接：

<%= link_to "Go", some_url, data: {skip_click: true} %>

默认情况下，退订链接会被排除。若要更改此设置，请使用：

AhoyEmail.default_options[:unsubscribe_links] = true

您可以使用以下方式指定要使用的域名：

AhoyEmail.default_options[:url_options] = {host: "mydomain.com"}

统计数据

获取某个活动的统计数据

AhoyEmail.stats("my-campaign")

升级

3.0

2024年6月发布的2.3.0版本之前创建的使用点击分析的链接，默认情况下将不再有效。如需恢复支持，请确定之前的密钥令牌并创建一个初始化器，内容如下：

AhoyEmail.secret_token = [AhoyEmail.secret_token, previous_secret_token]

此外，当 Nokogiri 的 HTML5 解析器可用时，现在会使用它来重写链接以进行 UTM 标记和点击分析。要使用 HTML4 解析，请使用以下代码创建一个初始化器：

AhoyEmail.default_options[:html5] = false

历史记录

查看更新日志

贡献指南

我们鼓励所有人为改进此项目提供帮助。以下是几种参与方式：

• 报告漏洞
• 修复漏洞并提交拉取请求
• 编写、澄清或修正文档
• 建议或添加新功能

开始开发前，请执行以下步骤：

git clone https://github.com/ankane/ahoy_email.git
cd ahoy_email
bundle install
bundle exec rake test