README.md master

机器翻译正文由机器翻译自项目原始文档（英文），排版经程序统一处理，可能存在偏差，请以原项目仓库为准。

Rack::追踪器

📷 原文此处有图片，请前往 GitHub 仓库查看完整内容。

理由

我们正在开发的大多数应用程序都在使用某种跟踪/分析服务，
Google Analytics 是首选，但随着项目的增长，很可能会添加更多服务。
通常，你会继续在应用程序中添加一些局部视图，以渲染所需的跟踪代码。随着时间的推移，你会发现自己会有很多跟踪片段，会导致代码库杂乱 :) 当仅仅看 Analytics 时，有一些解决方案比如 rack-google-analytics ，但它们只处理单一服务的存在问题。

我们希望有一个将所有服务整合到一个地方，并提供简单界面以添加新服务的解决方案。这就是为什么我们创建了 rack-tracker ，一个可以连接到多个服务并以统一方式暴露的 Rack 中间件。它分两部分，第一部分是实际的中间件，你可以将它添加到中间件堆栈中；第二部分是你将在应用中使用的服务处理器。添加你自己的自定义处理器非常容易，但为了帮助你入门，我们提供了对下列服务的支持
开箱即用：

尊重“不跟踪”(DNT) HTTP 头

Do Not Track (DNT) HTTP 头是一个 HTTP 头，请求服务器禁止跟踪单个用户。
这是大多数浏览器支持的选择退出选项。此选项默认禁用，必须显式启用以表示用户希望选择退出。
我们认为每个应用程序都应尊重用户选择退出的意愿，并尊重此 HTTP 头。

自 2.0.0 版本起，rack-tracker 默认尊重该请求头。这意味着如果 DNT 头设置为“1”，将不会注入任何跟踪器。

此选项可以使用 DO_NOT_RESPECT_DNT_HEADER => true 选项覆盖，该选项必须设置在任何应忽略 DNT 头的处理器上。（但请在执行此操作前仔细考虑）

关于如何不尊重 DNT 头的示例

use Rack::Tracker do
  # this tracker will be injected EVEN IF the DNT header is set to 1
  handler :maybe_a_friendly_tracker, { tracker: 'U-XXXXX-Y', DO_NOT_RESPECT_DNT_HEADER: true }
  # this tracker will NOT be injected if the DNT header is set to 1
  handler :google_analytics, { tracker: 'U-XXXXX-Y' }
end

关于 DNT 头的进一步阅读：

安装

将此行添加到您的应用程序的 Gemfile 中：

gem 'rack-tracker'

然后执行：

$ bundle

或者自己安装：

$ gem install rack-tracker

使用方法

将它添加到你的中间件栈中

config.middleware.use(Rack::Tracker) do
  handler :google_analytics, { tracker: 'U-XXXXX-Y' }
end

这将添加 Google Analytics 作为跟踪处理器。

Sinatra / Rack

你甚至可以在 Sinatra 或每个 Rack 应用程序中使用 Rack::Tracker

只需将 Tracker 插入到你的 Rack 堆栈中：

web = Rack::Builder.new do
  use Rack::Tracker do
    handler :google_analytics, { tracker: 'U-XXXXX-Y' }
  end
  run Sinatra::Web
end

run web

尽管出于明显的原因你无法使用 Rails 控制器扩展，但很容易将任意事件注入到请求环境中。

request.env['tracker'] = {
  'google_analytics' => [
    { 'class_name' => 'Send', 'category' => 'Users', 'action' => 'Login', 'label' => 'Standard' }
  ]
}

服务

Google 全球网站标签 (gtag.js)

:anonymize_ip - 设置跟踪器以从所有 IP 地址中删除最后一个八位字节，详情请参见 https://developers.google.com/analytics/devguides/collection/gtagjs/ip-anonymization。
:cookie_domain - 设置 GATC cookies 的域名。如果未设置，则使用网站域名，并移除 www. 前缀。
:user_id - 定义一个过程以设置 userId。例如：user_id: lambda { |env| env['rack.session']['user_id'] } 将返回会话中的 user_id。
:link_attribution - 启用增强链接归因。
:allow_display_features - 可用于禁用展示功能。
:custom_map - 用于配置和发送自定义维度
:optimize_id - 用于使用 gtag 部署 Optimize
:set - 在 set 命令配置多个属性中使用。

跟踪器

Google 全球网站标签允许配置多个跟踪器。使用 tracker 选项来配置 ID：

config.middleware.use(Rack::Tracker) do
  handler :google_global, { trackers: [ { id: 'U-XXXXX-Y' }, { id: 'U-WWWWWW-Z'} ] }
end

谷歌分析

:anonymize_ip - 设置追踪器以从所有IP地址中移除最后一个八位字节，详情见 https://developers.google.com/analytics/devguides/collection/gajs/methods/gaJSApi_gat?hl=de#_gat._anonymizeIp。
:cookie_domain - 设置 GATC cookies 的域名。如果未设置，则默认为网站域名，并去掉 www. 前缀。
:user_id - 定义一个方法以设置 userId。例如：user_id: lambda { |env| env['rack.session']['user_id'] } 将从会话中返回 user_id。
:site_speed_sample_rate - 为网站速度数据收集定义新的样本集大小，详情见 https://developers.google.com/analytics/devguides/collection/gajs/methods/gaJSApiBasicConfiguration?hl=de#_gat.GA_Tracker_._setSiteSpeedSampleRate。
:adjusted_bounce_rate_timeouts - 一个以秒为单位的时间数组，追踪器将用它来设置调整后跳出率追踪的超时。详情见 http://analytics.blogspot.ca/2012/07/tracking-adjusted-bounce-rate-in-google.html。
:enhanced_link_attribution - 启用增强型链接归因。
:advertising - 启用展示功能。
:ecommerce - 启用电子商务追踪。
:enhanced_ecommerce - 启用增强型电子商务跟踪
:optimize - 传递 Google Optimize 容器ID 作为值（例如，optimize: 'GTM-1234'）。
:pageview_url_script - 一个字符串，其中包含自定义 JS 脚本，用于计算应传递给 pageview 事件的 URL。默认值为 window.location.pathname + window.location.search。
:explicit_pageview - 一个布尔值，用于控制是否在页面加载时发送 pageview 事件。默认值为 true。

事件

若要从服务器端触发事件，只需在控制器中调用 tracker 方法。

  def show
    tracker do |t|
      t.google_analytics :send, { type: 'event', category: 'button', action: 'click', label: 'nav-buttons', value: 'X' }
    end
  end

它将把以下内容呈现到网站源代码中：

  ga('send', { 'hitType': 'event', 'eventCategory': 'button', 'eventAction': 'click', 'eventLabel': 'nav-buttons', 'value': 'X' })

参数

您也可以在控制器中设置参数：

  def show
    tracker do |t|
      t.google_analytics :parameter, { dimension1: 'pink' }
    end
  end

将呈现这一：

  ga('set', 'dimension1', 'pink');

增强型电子商务

您可以在控制器中设置参数：

  def show
    tracker do |t|
      t.google_analytics :enhanced_ecommerce, {
        type: 'addItem',
        id: '1234',
        name: 'Fluffy Pink Bunnies',
        sku: 'DD23444',
        category: 'Party Toys',
        price: '11.99',
        quantity: '1'
      }
    end
  end

将呈现这一：

  ga("ec:addItem", {"id": "1234", "name": "Fluffy Pink Bunnies", "sku": "DD23444", "category": "Party Toys", "price": "11.99", "quantity": "1"});

电子商务

您甚至可以直接从控制器内触发电子商务：

  def show
    tracker do |t|
      t.google_analytics :ecommerce, { type: 'addItem', id: '1234', affiliation: 'Acme Clothing', revenue: '11.99', shipping: '5', tax: '1.29' }
    end
  end

会给你这个：

  ga('ecommerce:addItem', { 'id': '1234', 'affiliation': 'Acme Clothing', 'revenue': '11.99', 'shipping': '5', 'tax': '1.29'  })

要加载 ecommerce 插件，请在中间件初始化时添加一些配置。
这对于上述功能的运行不是必须的，但建议这样做，这样你就不必自己处理插件。

  config.middleware.use(Rack::Tracker) do
    handler :google_analytics, { tracker: 'U-XXXXX-Y', ecommerce: true }
  end

谷歌广告转化

您可以使用默认选项配置处理程序：

config.middleware.use(Rack::Tracker) do
  handler :google_adwords_conversion, { id: 123456,
                                        language: "en",
                                        format: "3",
                                        color: "ffffff",
                                        label: "Conversion label",
                                        currency: "USD" }
end

要从服务器端跟踪 AdWords 转化，只需在控制器中调用 tracker 方法。

  def show
    tracker do |t|
      t.google_adwords_conversion :conversion, { value: 10.0 }
    end
  end

你也可以指定一个不同于默认选项的值：

  def show
    tracker do |t|
      t.google_adwords_conversion :conversion, { id: 123456,
                                                 language: 'en',
                                                 format: '3',
                                                 color: 'ffffff',
                                                 label: 'Conversion Label',
                                                 value: 10.0 }
    end
  end

谷歌标签管理器

谷歌标签管理器代码片段支持容器ID

  config.middleware.use(Rack::Tracker) do
    handler :google_tag_manager, { container: 'GTM-XXXXXX' }
  end

你也可以使用一个实验性功能来跟踪 turbolinks 下的页面浏览量，它会添加一个带有当前 URL 的 pageView 事件和 virtualUrl。

  config.middleware.use(Rack::Tracker) do
    handler :google_tag_manager, { container: 'GTM-XXXXXX', turbolinks: true }
  end

数据层

GTM 支持一个 dataLayer 用于推送事件以及变量。

要从服务器端将事件或变量添加到 dataLayer，只需在您的控制器中调用 tracker 方法。

  def show
    tracker do |t|
      t.google_tag_manager :push, { price: 'X', another_variable: ['array', 'values'] }
    end
  end

脸书

Facebook Pixel - 添加 Facebook Pixel

与 Facebook Helper 一起使用，以确认您的事件触发正确。

首先，将以下内容添加到您的配置中：

  config.middleware.use(Rack::Tracker) do
    handler :facebook_pixel, { id: 'PIXEL_ID' }
  end

动态像素配置

如果您需要拥有不同的像素ID，例如基于请求或为不同账户提供页面，您可以通过传递一个lambda来实现这一点：

  config.middleware.use(Rack::Tracker) do
    handler :facebook_pixel, { id: lambda { |env| env['PIXEL_ID'] } }
  end

并在请求 env 变量中设置像素 ID。这里是一个在 Rails 动作中如何实现的示例：

  class MyController < ApplicationController
    def show
      request.env['PIXEL_ID'] = 'DYNAMIC_PIXEL_ID'
    end
  end

标准事件

要从服务器端跟踪标准事件，只需在控制器中调用 tracker 方法。

  def show
    tracker do |t|
      t.facebook_pixel :track, { type: 'Purchase', options: { value: 100, currency: 'USD' } }
    end
  end

将导致以下结果：

  fbq("track", "Purchase", {"value":"100.0","currency":"USD"});

当你不需要追踪或优化转化时，你也可以使用非标准（自定义）事件名称来进行受众构建。

  tracker do |t|
    t.facebook_pixel :track_custom, { type: 'FrequentShopper', options: { purchases: 24, category: 'Sport' } }
  end

视觉网站优化器 (VWO)

只需将处理程序与匹配的 account_id 集成，你就可以开始使用了

  use Rack::Tracker do
    handler :vwo, { account_id: 'YOUR_ACCOUNT_ID' }
  end

GoSquared

启用 GoSquared 跟踪：

config.middleware.use(Rack::Tracker) do
  handler :go_squared, { tracker: 'ABCDEFGH' }
end

这将像这样将跟踪器添加到页面中：

  _gs('ABCDEFGH');

如果需要，你也可以设置多个命名跟踪器：

config.middleware.use(Rack::Tracker) do
  handler :go_squared, {
    trackers: {
      primaryTracker: 'ABCDEFGH',
      secondaryTracker: '1234567',
    }
  }
end

这将像下面这样将指定的跟踪器添加到页面中：

  _gs('ABCDEFGH', 'primaryTracker');
  _gs('1234567', 'secondaryTracker');

您可以通过传递以下设置来设置各种选项。如果您没有设置以下任何选项，它们将从生成的代码中被省略。

:anonymize_ip
:cookie_domain
:use_cookies
:track_hash
:track_local
:track_params

访问者名称

要从服务器端跟踪访问者名称，只需在您的控制器中调用 tracker 方法。

  def show
    tracker do |t|
      t.go_squared :visitor_name, { name: 'John Doe' }
    end
  end

它将把以下内容呈现到网站源代码中：

  _gs("set", "visitorName", "John Doe");

访客属性

要从服务器端跟踪访客属性，只需在你的控制器中调用tracker方法。

  def show
    tracker do |t|
      t.go_squared :visitor_info, { age: 35, favorite_food: 'pizza' }
    end
  end

它将把以下内容呈现到网站源代码中：

  _gs("set", "visitor", { "age": 35, "favorite_food": "pizza" });

Criteo

Criteo 重定向服务。

基本配置

config.middleware.use(Rack::Tracker) do
  handler :criteo, { set_account: '1234' }
end

其他全球 Criteo 处理程序选项包括：

set_customer_id: 'x'
set_site_type: 'd' - 可能的值为 m（移动设备）、t（平板）、d（桌面）
set_email: 'email'

选项值可以是静态的，也可以是动态的，通过提供一个在每个请求时重新评估的 lambda，例如 set_customer_id: lambda { |env| env['rack.session']['user_id'] }

跟踪事件

这将跟踪一个基础事件：

def show
  tracker do |t|
    t.criteo :view_item, { item: 'P0001' }
  end
end

这将呈现为 JS 中的以下代码：

window.criteo_q.push({"event": "viewItem", "item": "P001" });

t.criteo 的第一个参数总是 criteo 事件（例如 :view_item、:view_list、:track_transaction、:view_basket），第二个参数是该事件的附加属性。

另一个例子

t.criteo :track_transaction, { id: 'id', item: { id: "P0038", price: "6.54", quantity: 1 } }

Zanox

基本配置

config.middleware.use(Rack::Tracker) do
  handler :zanox, { account_id: '1234' }
end

主标签

这是一个主标签的示例：

def show
  tracker do |t|
    t.zanox :mastertag, { id: "25GHTE9A07DF67DFG90T", category: 'Swimming', amount: '3.50' }
  end
end

这将呈现为 JS 中的以下代码：

window._zx.push({"id": "25GHTE9A07DF67DFG90T"});

以及以下变量：

zx_category = 'Swimming';
zx_amount = '3.50';

转化追踪

这是一个潜在客户事件的示例：

def show
  tracker do |t|
    t.zanox :lead, { order_i_d: 'DEFC-4321' }
  end
end

这是一次促销活动的示例：

def show
  tracker do |t|
    t.zanox :sale, { customer_i_d: '123456', order_i_d: 'DEFC-4321', currency_symbol: 'EUR', total_price: '150.00' }
  end
end

Hotjar

config.middleware.use(Rack::Tracker) do
  handler :hotjar, { site_id: '1234' }
end

必应

添加跟踪代码片段：

config.middleware.use(Rack::Tracker) do
  handler :bing, { tracker: '12345678' }
end

发送转化事件：

tracker do |t|
  t.bing :conversion, {
    type: 'event',
    category: 'Users',
    action: 'Login',
    label: 'Standard',
    value: 10
  }
end

Hubspot

config.middleware.use(Rack::Tracker) do
  handler :hubspot, { site_id: '1234' }
end

漂移

Drift

config.middleware.use(Rack::Tracker) do
  handler :drift, account_id: 'DRIFT_ID'
end

堆

堆。堆有项目（例如“Main”），每个项目有多个
环境（例如“Production”或“Development”）。因此 env_id 是表示环境的数字 ID。在你的仪表板中查看设置 -> 项目 -> 环境。

config.middleware.use(Rack::Tracker) do
  handler :heap, env_id: 'HEAP_ID'
end

自定义处理器

虽然我们直接提供了一些跟踪服务的处理器，但你可能会有兴趣为你的自定义跟踪/分析服务添加支持。

编写处理器很简单 ;)，你的类只需要实现几个方法。

从一个继承自 Rack::Tracker::Handler 的普通 Ruby 类开始

class MyHandler < Rack::Tracker::Handler
  ...
end

如果你想自定义模板的渲染，你可以重写处理程序 #render 方法：

def render
  Tilt.new( File.join( File.dirname(__FILE__), 'template', 'my_handler.erb') ).render(self)
end

可能会有需要在多个地方修改响应的情况。为此，您可以
在您的处理程序中重写 #inject 方法。有关示例，请查看
Google 标签管理器实现。

这将渲染 template/my_handler.erb 并将结果注入到源中。您可以自由决定模板的存放位置，但我们通常将它们放在实际处理程序代码附近。


  console.log('my tracker: ' + <%= options.to_json %>)

让我们试一试！我们需要在 Rack::Tracker 中间件中安装我们的新处理器

  config.middleware.use(Rack::Tracker) do
    handler MyHandler, { awesome: true }
  end

你传递给 handler 的所有内容都将在你的模板中作为 #options 可用，因此你还可以访问当前请求所属的 env -hash。

运行你的应用程序并发出请求，上述模板的结果可以在 </head> 之前找到。你可以在你的处理程序代码中更改位置：

class MyHandler < Rack::Tracker::Handler
  self.position = :body

  ...
end

然后这个片段将在 </body> 之前渲染。

要在你的控制器中启用 tracker dsl 功能，你需要在你的处理程序上实现 track 类方法：

def self.track(name, *event)
  # do something with the event(s) to prepare them for your template
  # and return a hash with a signature like { name => event }
end

查看 lib/rack/tracker 中现有的处理程序以获取一些灵感。:)

请注意

大多数跟踪是使用某种 Javascript 完成的，任何跟踪数据都只是被传递下去。
在跟踪中使用未经验证的用户输入可能会导致 XSS 问题。请仅使用安全数据。

贡献

首先，感谢你的帮助！:green_heart:

如果你想实现一个功能，完成它的最佳方法是提交一个实现该功能的拉取请求。
测试、读我文件和变更日志条目会很好。

Fork 它 ( http://github.com/railslove/rack-tracker/fork )
创建你的功能分支 ( git checkout -b my-new-feature )
提交你的更改 ( git commit -am 'Add some feature' )
推送到分支 ( git push origin my-new-feature )
创建新的拉取请求

本文标题：rack-tracker - 轻松跟踪：不要再为在应用中添加跟踪和分析片段而浪费时
本文链接：https://www.cn121.com/shop/railslove-rack-tracker.html
原项目：railslove/rack-tracker　版权归原作者 railslove 及贡献者所有
收录信息：本站于 2026-10-09 收录本项目，本页所列协议与仓库指标均为收录当时的状态；该日期之后原项目的版本更新与协议变更，本页不作同步。
开源协议：收录时本项目采用 MIT（查看 LICENSE 原文），本站译文为其衍生内容；使用、修改、分发请以该仓库 LICENSE 原文为准。
站点出处：本文首发于 OneTwoOne，收录自 GitHub 开源项目 railslove/rack-tracker。
翻译说明：本页正文为人工智能生成内容——由机器翻译对原项目 README 初译、经程序校验排版，可能存在错漏，请以原项目文档为准。
引用声明：商业转载、第三方聚合或 AI 检索训练引用时，请务必保留以上来源出处、本文永久链接，以及原项目的版权声明与许可信息。
下架通道：若原项目此后变更或收紧了许可协议、或作者／权利人认为本站的收录方式（译文、排版适配、简介翻译等）超出其授权范围，请通过 xyd3302001@163.com 发送下架通知，并附上项目地址与本页链接。本站核实后将第一时间删除本页内容，或改为不复制原文的目录性收录；署名更正等其他要求可一并提出。

仓库档案 (Facts)

作者 / 机构 railslove
开源协议 MIT
默认分支 master
主要语言 Ruby
代码库大小 516 KB
开源创建 2014-08-19
最后推送 2 年前
数据来源 GitHub REST API