JavaScript Tracking Client

JavaScript 跟踪客户端

您可以使用 JavaScript 跟踪客户端来跟踪任何支持 JavaScript 的应用程序：例如网站！

本指南将解释如何使用 JavaScript 跟踪客户端自定义在 Matomo（以前称为 Piwik）中记录某些网络分析数据的方式。

查找 Matomo 跟踪代码
要使用本页描述的所有功能，您需要使用最新版本的跟踪代码。要查找您网站的跟踪代码，请按以下步骤操作：

使用您的管理员或超级用户帐户登录 Matomo
点击右上角菜单中的“管理”（齿轮图标）
点击左侧菜单中的“跟踪代码”（在“可测量”或“网站”菜单下）
点击“JavaScript 跟踪”部分
选择您要跟踪的网站
将 JavaScript 跟踪代码复制并粘贴到您的网页中，紧接着开始标记之后（或在部分内）
跟踪代码如下：

<!-- Matomo -->
<script type="text/javascript">
  var _paq = window._paq = window._paq || [];
  _paq.push(['trackPageView']);
  _paq.push(['enableLinkTracking']);
  (function() {
    var u="//{$MATOMO_URL}/";
    _paq.push(['setTrackerUrl', u+'matomo.php']);
    _paq.push(['setSiteId', {$IDSITE}]);
    var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
    g.type='text/javascript'; g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
  })();
</script>
<!-- End Matomo Code -->

在您的跟踪代码中，{$MATOMO_URL}将被您的 Matomo URL 替换，并将{$IDSITE}被您在 Matomo 中跟踪的网站的 idsite 替换。

对于熟悉 JavaScript 的人来说，这段代码可能看起来有点奇怪，但那是因为它是异步运行的。换句话说，浏览器不会等待文件matomo.js下载完毕后才显示您的页面。

对于异步跟踪，配置和跟踪调用被推送到全局_paq数组上执行，与 的异步加载无关matomo.js。格式为：

paq.push([ ‘APImethod_name’, parameter_list ]);
您还可以推送要执行的函数。例如：

var visitor_id;
_paq.push([ function() { visitor_id = this.getVisitorId(); }]);

或者例如，使用异步代码获取自定义变量（名称，值）：

_paq.push(['setCustomVariable','1','VisitorType','Member']);
_paq.push([ function() { var customVariable = this.getCustomVariable(1); }]);

_paq即使matomo.js文件已加载并运行后，您也可以将其推送到数组。

如果您的 Matomo 跟踪代码与此不同，则您可能正在使用已弃用的版本。旧版本仍可按预期工作并跟踪您的访问者，但我们强烈建议您更新页面以使用最新的跟踪代码。

要求
支持的浏览器
JavaScript 跟踪器可在支持JSONAPI 的所有浏览器上运行。这包括 IE8 及更高版本。单击此处查看受支持的浏览器的完整列表。。如果您需要支持 IE7 及更早版本，那么您可以加载一个window.JSON可用的 polyfill，例如JSON3。在加载 Matomo JS 跟踪器之前，需要加载此 polyfill。

已知的不兼容问题
原型 JS 库会覆盖浏览器的 JSON API，并导致问题（例如自定义变量会导致错误）（请参阅#16596）。解决方法是删除原型 JS 库或手动覆盖 JSON 对象（参见上文，例如使用 JSON3）。
JavaScript 跟踪器功能
自定义页面标题
默认情况下，Matomo 使用 HTML 页面的标题来跟踪页面标题，您可以使用以下函数对其进行自定义setDocumentTitle：

_paq.push([‘setDocumentTitle’, document.title]);
_paq.push([‘trackPageView’]);
如果您在同一个网站中跟踪多个子域，您可能希望页面标题以子域为前缀，以便于您查看每个子域的流量和数据。您可以简单地这样做：

_paq.push([‘setDocumentTitle’, document.domain + “/“ + document.title]);
_paq.push([‘trackPageView’]);
高级用户还可以动态生成页面名称，例如使用 PHP：

_paq.push([‘setDocumentTitle’, ““]);
_paq.push([‘trackPageView’]);
自定义页面 URL
默认情况下，Matomo 使用当前页面的 URL 作为报告中的页面 URL。您可以使用功能自定义要跟踪的页面 URL setCustomUrl，在常见问题解答中了解更多信息如何使用 Matomo Javascript 跟踪器设置自定义 URL？

手动触发事件
默认情况下，当 JavaScript 跟踪代码在每次页面浏览时加载并执行时，Matomo 会跟踪页面浏览量。

然而，在现代网络应用程序中，用户交互不一定涉及加载新页面。例如，当用户点击 JavaScript 链接时，或者当他们点击选项卡（这会触发 JS 事件）时，或者当他们与用户界面元素交互时，您仍然可以使用 Matomo 跟踪这些交互。

要跟踪用户与 Matomo 的任何交互或点击，您可以手动调用 JavaScript 函数trackEvent()。例如，如果您想跟踪 JavaScript 菜单上的点击，您可以编写：

Freedom page
您可以在用户指南中了解有关跟踪事件的更多信息。

手动触发目标转化
默认情况下，Matomo 中的目标定义为“匹配”URL 的部分（以…开头、包含或正则表达式匹配）。您还可以跟踪给定页面浏览量、下载量或外部链接点击量的目标。

在某些情况下，您可能希望注册其他类型操作的转化，例如：

当用户提交表单时
当用户在页面上停留的时间超过一定时间时
当用户在 Flash 应用程序中进行某些交互时
当用户提交购物车并付款后：你可以将 Matomo 跟踪代码提供给付款网站，然后该网站会将转化记录到你的 Matomo 数据库中，并记录转化的自定义收入
要触发目标转化：

// logs a conversion for goal 1
_paq.push([‘trackGoal’, 1]);
您还可以使用自定义收入为此目标注册转化。例如，您可以生成动态调用trackGoal()以设置交易的收入：

// logs a conversion for goal 1 with the custom revenue set
_paq.push([‘trackGoal’, 1, getCartValue(); ?>]);
在“跟踪目标”文档中可以找到有关 Matomo 中的目标跟踪的更多信息。

准确衡量每个页面的浏览时间
默认情况下，当用户在访问期间仅访问一个页面时，Matomo 会假定访问者在网站上花费了 0 秒。这会带来一些后果：

当访问者仅浏览一个页面时，“访问时长”将为0秒。
当访问者查看多个页面时，此次访问的最后一个页面的“页面停留时间”将为 0 秒。
可以配置 Matomo，以便准确测量访问所花费的时间。为了更好地测量访问所花费的时间，请在 JavaScript 代码中添加以下内容：

// accurately measure the time spent in the visit
_paq.push([‘enableHeartBeatTimer’]);
只要用户正在主动查看页面（即选项卡处于活动状态且处于焦点状态），Matomo 就会发送请求来计算访问的实际时间。心跳请求在以下情况下执行：

当前选项卡处于活动状态至少 15 秒后切换到另一个浏览器选项卡（可以配置为如下所示）。
导航到同一选项卡内的另一个页面。
关闭标签。
// Change how long a tab needs to be active to be counted as viewed in seconds/
// Requires a page to be actively viewed for 30 seconds for any heart beat request to be sent.
_paq.push([‘enableHeartBeatTimer’, 30]);
注意：测试心跳定时器时，请记住确保浏览器选项卡具有焦点，而不是开发人员工具或其他面板。

电子商务追踪
Matomo 可实现先进而强大的电子商务跟踪。查看电子商务分析文档，了解有关电子商务报告以及如何设置电子商务跟踪的更多信息。

内部搜索追踪
Matomo 提供高级网站搜索分析功能，让您可以跟踪访问者如何使用内部网站搜索引擎。默认情况下，Matomo 可以读取包含搜索关键字的 URL 参数。但是，您也可以使用 JavaScript 函数手动记录网站搜索关键字trackSiteSearch(…)

在您的网站中，在标准页面中，您通常会通过 调用来记录页面浏览量matomoTracker.trackPageView()。在搜索结果页面上，您将调用函数 piwikTracker.trackSiteSearch(keyword, category, searchCount)来记录内部搜索请求。注意：’keyword’ 参数是必需的，但 category 和 searchCount 是可选的。

_paq.push([‘trackSiteSearch’,
// Search keyword searched for
“Banana”,
// Search category selected in your search engine. If you do not need this, set to false
“Organic Food”,
// Number of results on the Search results page. Zero indicates a ‘No Result Search Keyword’. Set to false if you don’t know
0
]);

// We recommend not to call trackPageView() on the Site Search Result page
// _paq.push([‘trackPageView’]);
我们还强烈建议设置 searchCount 参数，因为 Matomo 将专门报告“无结果关键字”，即搜索过但未返回任何结果的关键字。了解用户搜索但在您的网站上找不到（尚未找到？）的内容通常非常有趣。在用户文档中了解有关网站搜索分析的更多信息。

自定义变量
自定义变量是一项强大的功能，可让您跟踪每次访问和/或每次页面浏览的自定义值。请参阅跟踪自定义变量文档页面了解一般信息。

您可以为每次访问网站设置最多 5 个自定义变量（名称和值），以及/或者为每次浏览页面设置最多 5 个自定义变量。如果您为访问者设置自定义变量，当他们一小时或两天后回来时，这将是一次新的访问，他们的自定义变量将为空。

有两个“范围”可供您设置自定义变量。“范围”是函数的第 4 个参数setCustomVariable()。

当 scope = “visit” 时，自定义变量的名称和值将存储在数据库中的访问中。因此，您最多可以为每次访问存储 5 个范围为“visit”的自定义变量。
当 scope = “page” 时，自定义变量的名称和值将针对所跟踪的页面浏览量进行存储。因此，您最多可以为每个页面浏览量存储 5 个范围为“page”的自定义变量。
“index”参数是自定义变量槽索引，是一个从 1 到 5 的整数。（注意：如果您需要超过默认的 5 个槽，请阅读此常见问题解答）。

自定义变量统计信息在 Matomo 中的“访客”>“自定义变量”下报告。范围为“访问”和“页面”的自定义变量均在此报告中汇总。

访问的自定义变量
setCustomVariable(index, name, value, scope = “visit”)
此函数用于创建或更新自定义变量名称和值。例如，假设您想在每次访问时存储用户的性别。您可以使用名称 =“性别”、值 =“男性”或“女性”来存储自定义变量。

重要提示：给定的自定义变量名称必须始终存储在同一个“索引”中。例如，如果您选择将变量名称 =“性别”存储在索引 = 1中，并在索引 = 1 中记录另一个自定义变量，则“性别”变量将被删除并替换为存储在索引 1 中的新自定义变量。

_paq.push([‘setCustomVariable’,
// Index, the number from 1 to 5 where this custom variable name is stored
1,
// Name, the name of the variable, for example: Gender, VisitorType
“Gender”,
// Value, for example: “Male”, “Female” or “new”, “engaged”, “customer”
“Male”,
// Scope of the custom variable, “visit” means the custom variable applies to the current visit
“visit”
]);

_paq.push([‘trackPageView’]);
您只需设置一次范围为“访问”的变量，整个访问期间该值都会被记录下来。

页面浏览量的自定义变量
setCustomVariable(index, name, value, scope = “page”)
除了跟踪“访问”的自定义变量外，有时单独跟踪每个页面浏览的自定义变量也很有用。例如，对于“新闻”网站或博客，给定的文章可能被归类为一个或多个类别。在这种情况下，您可以使用 设置一个或多个自定义变量name=”category”，如果文章被归类为体育和欧洲类别，则使用value=”Sports”，另一个使用value=”Europe”。然后，自定义变量报告将报告您网站每个类别的访问次数和页面浏览量。使用标准 Matomo 报告可能难以获得此信息，因为它们报告“最佳页面 URL”和“最佳页面标题”，而这些可能不包含“类别”信息。

// Track 2 custom variables with the same name, but in different slots.
// You will then access the statistics about your articles’ categories in the ‘Visitors > custom variables’ report
_paq.push([‘setCustomVariable’, 1, ‘Category’, ‘Sports’, ‘page’]);

// Track the same name but in a different Index
_paq.push([‘setCustomVariable’, 2, ‘Category’, ‘Europe’, ‘page’]);
// Here you could track other custom variables with scope “page” in Index 3, 4 or 5
// The order is important: first setCustomVariable is called and then trackPageView records the request

_paq.push([‘trackPageView’]);
重要提示：可以将范围为“访问”的自定义变量存储在“索引”1 中，并将范围为“页面”的不同自定义变量存储在相同的“索引”1 中。因此，从技术上讲，您可以在网站的每个页面上跟踪最多 10 个自定义变量名称和值（5 个具有“页面”范围的变量存储在实际页面视图中，5 个具有“访问”范围的变量存储在访问中）。

_paq.push([‘setCustomVariable’,
// Index, the number from 1 to 5 where this custom variable name is stored for the current page view
1,
// Name, the name of the variable, for example: Category, Sub-category, UserType
“category”,
// Value, for example: “Sports”, “News”, “World”, “Business”, etc.
“Sports”,
// Scope of the custom variable, “page” means the custom variable applies to the current page view
“page”
]);

_paq.push([‘trackPageView’]);
删除自定义变量
deleteCustomVariable(index, scope)
如果您创建了自定义变量，然后决定从访问或页面视图中删除该变量，则可以使用 deleteCustomVariable。

为了在 Matomo 服务器中保留更改，必须在调用之前调用该函数trackPageView();

_paq.push([‘deleteCustomVariable’, 1, “visit”]); // Delete the variable in index 1 stored for the current visit
_paq.push([‘trackPageView’]);
检索自定义变量
getCustomVariable(index, scope)
此函数可用于获取自定义变量名称和值。默认情况下，它仅适用于在同一页面加载期间设置的自定义变量。

注意：可以配置 Matomo，以便getCustomVariable返回范围为“访问”的自定义变量的名称和值，即使它是在同一访问中的前一个页面浏览中设置的。要启用此行为，请storeCustomVariablesInCookie在调用 之前调用 JavaScript 函数trackPageView。这将允许将范围为“访问”的自定义变量存储在第一方 cookie 中。自定义变量 cookie 在访问期间有效（最后一次操作后 30 分钟）。然后，您可以使用 检索自定义变量名称和值getCustomVariable。如果请求的索引中没有自定义变量，它将返回 false。

_paq.push([ function() {

var customVariable = this.getCustomVariable( 1, "visit" );
// Returns the custom variable: [ "gender", "male" ]

// do something with customVariable...

}]);

_paq.push([‘trackPageView’]);
自定义尺寸
自定义尺寸是一项强大的功能，可让您跟踪每次访问和/或每个操作（页面浏览量、外部链接、下载）的自定义值。此功能不直接随 Matomo 提供，但可以通过Matomo 市场（CustomDimensions 插件）作为插件安装。在使用自定义尺寸之前，您需要安装插件并配置至少一个尺寸，请参阅自定义尺寸指南。您将获得每个配置的自定义尺寸的数字 ID，可用于为其设置值。

跨跟踪请求跟踪自定义维度
要跟踪某个值，只需指定 ID 后跟一个值：

_paq.push([‘setCustomDimension’, customDimensionId = 1, customDimensionValue = ‘Member’]);
请注意，一旦设置了自定义维度，该值将用于所有后续跟踪请求，如果不希望出现这种情况，可能会导致不准确的结果。例如，如果您跟踪页面浏览量，则自定义维度值也将在同一页面加载中跟踪每个后续事件、外链、下载等。调用此方法实际上不会触发跟踪请求，而是会将值与后续跟踪请求一起发送。要在跟踪请求后删除自定义维度值，请调用 _paq.push([‘deleteCustomDimension’, customDimensionId]);

为初始页面视图设置自定义尺寸
要为初始页面视图设置自定义尺寸，请确保将方法调用setCustomDimension置于之前trackPageView：

_paq.push([‘setCustomDimension’, customDimensionId = 1, customDimensionValue = ‘Member’]);
_paq.push([‘trackPageView’]);
// _paq.push([‘enableLinkTracking’]);
// rest of tracking code
仅跟踪一项特定操作的自定义维度
可以仅在访问范围级别为一项特定操作设置自定义维度。如果您想要跟踪页面浏览量，则可以随此跟踪请求一起发送一个或多个特定的自定义维度值，如下所示：

_paq.push([‘trackPageView’, pageTitle, {dimension1: ‘DimensionValue’}]);

要定义维度值，请传递一个定义一个或多个属性的对象作为最后一个参数（确保指定方法中定义的所有参数，我们不会自动假设最后一个参数是 customData，而是方法定义的所有参数都需要传递给每个方法）。维度的属性名称以 开头，dimension后跟自定义维度 ID，例如dimension1。其他几种方法也适用相同的行为：

_paq.push([‘trackEvent’, category, action, name, value, {dimension1: ‘DimensionValue’}]);
_paq.push([‘trackSiteSearch’, keyword, category, resultsCount, {dimension1: ‘DimensionValue’}]);
_paq.push([‘trackLink’, url, linkType, {dimension1: ‘DimensionValue’}]);
_paq.push([‘trackGoal’, idGoal, customRevenue, {dimension1: ‘DimensionValue’}]);
优点是设置的维度值将仅用于此特定操作，并且您不必在跟踪请求后删除该值。您可以像这样设置多个维度值：

_paq.push([‘trackPageView’, pageTitle, {dimension1: ‘DimensionValue’, dimension4: ‘Test’, dimension7: ‘Value’}]);

检索自定义尺寸值
getCustomDimension(customDimensionId)
此函数可用于获取自定义尺寸的值。仅当在同一页面加载期间设置了自定义尺寸时，此函数才会起作用。

用户身份
用户 ID是 Matomo 中的一项功能，可让您将从多个设备和多个浏览器收集的特定用户数据连接在一起。实现用户 ID 有两个步骤：

您必须分配一个唯一且持久的非空字符串来代表每个登录用户。通常，此 ID 将是您的身份验证系统提供的电子邮件地址或用户名。
您必须为每个页面浏览设置用户 ID，否则将在未设置用户 ID 的情况下跟踪页面浏览。
setUserId然后，您必须在调用任何track*函数（trackPageview、、、等trackEvent）之前通过方法调用将此用户 ID 字符串传递给 Matomo，trackGoal例如trackSiteSearch：
paq.push([‘setUserId’, ‘USERID_HERE’]);
paq.push([‘trackPageView’]);
注意：USERID_HERE必须是跨设备代表用户的唯一且持久的非空字符串。

当用户登录时，设置用户ID
让我们举个例子。假设您的网站使用 PHP 脚本通过登录表单验证用户身份。您的 Matomo JavaScript 代码片段可能如下所示：

var paq = window.paq = window._paq || [];

_paq.push([‘trackPageView’]);
_paq.push([‘enableLinkTracking’]);
当用户注销时，重置用户ID
当用户已注销且用户 ID 不再可用时，建议通过调用resetUserId之前的方法通知 Matomo trackPageView。

resetUserId如果您想在用户注销时创建新的访问，那么您也可以通过调用和（两次）强制 Matomo 创建新的访问，appendToTrackingUrl如下所示：

// User has just logged out, we reset the User ID
_paq.push([‘resetUserId’]);

// we also force a new visit to be created for the pageviews after logout
paq.push([‘appendToTrackingUrl’, ‘newvisit=1’]);

_paq.push([‘trackPageView’]);

// we finally make sure to not again create a new visit afterwards (important for Single Page Applications)
_paq.push([‘appendToTrackingUrl’, ‘’]);

内容追踪
有多种方法可以手动、半自动和自动跟踪内容展示和互动。请注意，内容展示将使用批量跟踪进行跟踪，POST即使GET配置为默认设置，它也始终会发送请求。有关更多详细信息，请参阅内容跟踪的深入指南。

跟踪页面内的所有内容展示
您可以使用该方法trackAllContentImpressions()扫描整个 DOM 以查找内容块。对于每个内容块，我们将立即跟踪内容印象。如果您只想跟踪可见内容印象，请查看trackVisibleContentImpressions()。

_paq.push([‘trackPageView’]);
_paq.push([‘trackAllContentImpressions’]);
如果您多次调用此方法，我们不会发送两次相同内容块的展示，除非trackPageView()同时调用。这对于单页应用程序很有用。

仅跟踪页面内可见的内容印象。
启用仅通过 跟踪可见内容展示trackVisibleContentImpressions(checkOnScroll, timeIntervalInMs)。可见的意思是内容块已在视口中并且未被隐藏（不透明度、可见性、显示等）。

您也可以通过传递 来告诉我们不要在每次滚动后重新扫描 DOM checkOnScroll=false。否则，我们将检查之前隐藏的内容块在滚动后是否变得可见，如果是，则跟踪印象。
限制：如果内容块位于可滚动元素（overflow: scroll）内，我们目前无法检测该元素何时变得可见。
您也可以选择通过 告诉我们每 X 毫秒重新扫描整个 DOM 以查找新内容展示timeIntervalInMs=500。默认情况下，我们将每 750 毫秒重新扫描一次 DOM。要禁用它，请传递timeIntervalInMs=0。
重新扫描整个 DOM 并检测内容块的可见状态可能需要一段时间，具体取决于浏览器、硬件和内容量。如果每秒帧数下降，您可能需要增加间隔或完全禁用它。如果禁用它，您仍然可以通过再次调用此方法或 随时手动重新扫描 DOM trackContentImpressionsWithinNode()。
第一次调用此方法后，checkOnScroll和都无法更改。timeIntervalInMs

_paq.push([‘trackPageView’]);
_paq.push([‘trackVisibleContentImpressions’, true, 750]);
仅跟踪页面部分内容的展示次数
如果您在我们跟踪初始展示后向 DOM 添加元素，请使用该方法trackContentImpressionsWithinNode(domNode, contentTarget)。调用此方法将确保跟踪此节点中包含的所有内容块的展示。

例子

var div = $(‘

_paq.push([‘trackContentImpressionsWithinNode’, div[0]]);
在此示例中，我们将检测到两个新的内容展示。如果您已启用仅跟踪可见内容块，我们将尊重您的设置。

半自动跟踪互动
通常在访问者点击内容块时，就会自动跟踪与内容块的交互。有时您可能希望手动触发交互，例如，如果您希望基于表单提交或双击触发交互。为此，请调用方法trackContentInteractionNode(domNode, contentInteraction)。

例子

formElement.addEventListener(‘submit’, function () {
_paq.push([‘trackContentInteractionNode’, this, ‘submittedForm’]);
});
传递的内容domNode可以是内容块内的任何节点或内容块元素本身。如果未找到内容块，则不会跟踪任何内容。
您也可以选择设置内容交互的名称，例如click或submit。如果没有提供，Unknown则将使用该值。
您应该通过设置 CSS 类piwikContentIgnoreInteraction或属性来禁用该内容块的自动交互跟踪data-content-ignoreinteraction。否则，只要访问者执行点击，交互就可能会被跟踪。
我们将这种跟踪称为半自动跟踪，因为您手动触发了交互，但内容名称、片段和目标会自动检测。自动检测内容名称和片段可确保我们可以将交互与之前跟踪的印象进行映射。

手动跟踪内容展示和互动
您应将方法trackContentImpression(contentName, contentPiece, contentTarget)和trackContentInteraction( contentInteraction, contentName, contentPiece, contentTarget)仅结合使用。不建议trackContentInteraction()在自动跟踪展示后使用，因为只有当您设置用于跟踪相关展示的相同内容名称和片段时，我们才能将交互映射到展示。

例子

_paq.push([‘trackContentImpression’, ‘Content Name’, ‘Content Piece’, ‘https://www.example.com']);

div.addEventListener(‘click’, function () {
_paq.push([‘trackContentInteraction’, ‘tabActivated’, ‘Content Name’, ‘Content Piece’, ‘https://www.example.com']);
});
请注意，每次调用这些方法都会向您的 Matomo 跟踪器实例发送一个请求。执行此操作次数过多可能会导致性能问题。

测量域和/或子域
无论您是在跟踪一个域、子域还是同时跟踪这两个域等，您都可能需要配置 Matomo JavaScript 跟踪代码。可能需要配置两件事：1) 如何创建和共享跟踪 cookie，以及 2) 哪些点击应作为“外链”进行跟踪。

跟踪一个域名
这是标准用例。Matomo 跟踪单个 Matomo 网站中一个没有子域名的域名的访问情况。

// Default Tracking code
_paq.push([‘setSiteId’, 1]);
_paq.push([‘setTrackerUrl’, u+’matomo.php’]);
_paq.push([‘trackPageView’]);
如果您正在跟踪一个特定的子域，此默认跟踪代码也有效。

跟踪同一网站中的一个域名及其子域名
为了在主域名及其任何子域中记录用户，我们告诉 Matomo 在所有子域之间共享 cookie。setCookieDomain()在 example.com/* 和所有子域中的 Matomo 跟踪代码中调用。

_paq.push([‘setSiteId’, 1]);
_paq.push([‘setTrackerUrl’, u+’matomo.php’]);

// Share the tracking cookie across example.com, www.example.com, subdomain.example.com, …
_paq.push([‘setCookieDomain’, ‘*.example.com’]);

// Tell Matomo the website domain so that clicks on these domains are not tracked as ‘Outlinks’
_paq.push([‘setDomains’, ‘*.example.com’]);

_paq.push([‘trackPageView’]);
跟踪同一网站上多个域名的访客
为了准确地将跨不同域名的访问者跟踪到 Matomo 网站内的一次访问中，我们需要设置所谓的跨域链接。Matomo 中的跨域跟踪可确保当访问者访问多个网站和域名时，访问者数据将存储在同一次访问中，并且访问者 ID 可在各个域名之间重复使用。需要跨域的一个典型用例是，例如，当电子商务在线商店处于开启状态www.awesome-shop.com并且电子商务购物车技术位于另一个域（例如）上时secure.cart.com。

跨域链接结合使用了两种跟踪器方法setDomains和enableCrossDomainLinking。在我们的指南中了解如何设置跨域链接：如何准确衡量跨多个域名的同一访问者（跨域链接）？

在单独的网站中跟踪域名的子目录
在自己独立的 Matomo 网站中跟踪域名的子目录时，建议定制跟踪代码以确保最佳的数据准确性和性能。

例如，如果您的网站提供“用户资料”功能，您可能希望在 Matomo 中单独的网站中跟踪每个用户资料页面。在主域主页中，您将使用默认跟踪代码：

// idSite = X for the Homepage
// In Administration > Websites for idSite=X, the URL is set to example.com/
_paq.push([‘setSiteId’, X]);
_paq.push([‘setTrackerUrl’, u+’matomo.php’]);
_paq.push([‘trackPageView’]);
在example.com/user/MyUsername页面中（以及在其他每个用户配置文件中），您可以构建对自定义的setSiteId和setCookiePath的调用setDomains：

// The idSite Y will be different from other user pages
// In Administration > Websites for idSite=Y, the URL is set to example.com/user/MyUsername
_paq.push([‘setSiteId’, Y]);

// Create the tracking cookie specifically in example.com/user/MyUsername
_paq.push([‘setCookiePath’, ‘/user/MyUsername’]);

// Tell Matomo the website domain so that clicks on other pages (eg. /user/AnotherUsername) will be tracked as ‘Outlinks’
_paq.push([‘setDomains’, ‘example.com/user/MyUsername’]);

_paq.push([‘setTrackerUrl’, u+’matomo.php’]);
_paq.push([‘trackPageView’]);
当跟踪独立网站中的许多子目录时，该功能setCookiePath可防止 Cookie 数量快速增加，并防止浏览器删除部分 Cookie。这可确保最佳数据准确性并提高用户的性能（每次请求发送的 Cookie 更少）。

该功能setDomains可确保离开您的网站（子目录example.com/user/MyUsername）的用户的点击被正确跟踪为“外部链接”。

跟踪单独网站中的一组页面
（自 Matomo 2.16.1 起可用）

在某些罕见情况下，您可能希望跟踪特定网站中与通配符匹配的所有页面，并将其他页面（与通配符不匹配）上的点击跟踪为“外部链接”。

在页面中/index_fr.htm或者/index_en.htm写入：

// clicks on links not starting with example.com/index will be tracked as ‘Outlinks’
_paq.push([‘setDomains’, ‘example.com/index*’]);

// when using a wildcard *, we do not need to configure cookies with setCookieDomain
// or setCookiePath as cookies are correctly created in the main domain by default

_paq.push([‘setTrackerUrl’, u+’matomo.php’]);
_paq.push([‘trackPageView’]);
笔记：

*仅当在字符串末尾指定时才支持通配符。
由于通配符可以匹配多条路径，因此省略对setCookieDomain或的setCookiePath调用以确保所有匹配通配符的页面正确共享跟踪 cookie。
有关在 Matomo 中跟踪网站和子域的更多信息，请参阅常见问题解答：如何配置 Matomo 以监控多个网站、域和子域

下载和出站链接跟踪
启用下载和出站链接跟踪
默认的 Matomo JavaScript 跟踪器代码会自动启用下载和出站链接跟踪，这是通过调用以下enableLinkTracking函数完成的：

// Enable Download & Outlink tracking
_paq.push([‘enableLinkTracking’]);

建议在第一次调用trackPageView或之后添加此行trackEvent。

自动跟踪外链
默认情况下，指向当前域以外的域的所有链接都启用了点击跟踪，每次点击都将计为一次出站链接。如果您使用多个域和子域，您可能会在“页面”>“出站链接”报告中看到子域的点击次数。

跟踪外部链接并忽略别名域
如果您只希望外部网站的点击出现在您的出站链接报告中，您可以使用该功能setDomains()指定别名域或子域的列表。支持通配符域 (*.example.org)，让您轻松忽略所有子域的点击。

// Don’t track Outlinks on all clicks pointing to .hostname1.com or *.hostname2.com
// Note: the currently tracked website is added to this array automatically
_paq([‘setDomains’, [“.hostname1.com”, “hostname2.com”]]);

_paq.push([‘trackPageView’]);
自 Matomo 2.15.1 起，您还可以将路径附加到域，并且 Matomo 将正确检测指向同一域但不同路径的链接作为外部链接。

// Don’t track Outlinks on all clicks pointing to .hostname1.com/product1/ or .hostname2.com/product1/
// Track all clicks not pointing to .hostname1.com/product1/ or .hostname2.com/product1/ as outlink.
_paq([‘setDomains’, [“*.hostname1.com/product1”, “hostname2.com/product1”]]);
了解有关此用例的更多信息在单独的网站中跟踪域的子目录。

通过 CSS 或 JavaScript 将点击作为出站链接进行跟踪
如果您想强制 Matomo 将某个链接视为外部链接（链接到当前域或别名域之一），您可以向链接添加matomo_link或css 类：piwik_link

Link I want to track as an outlink
注意：您可以自定义并重命名用于强制将点击记录为出站链接的 CSS 类：

// now all clicks on links with the css class “external” will be counted as outlinks

// you can also pass an array of strings
_paq.push([‘setLinkClasses’, “external”]);

_paq.push([‘trackPageView’]);
或者，您可以使用 JavaScript 手动触发对外部链接的点击（对于页面浏览量或文件下载，其作用相同）。在此示例中，单击电子邮件地址时会触发自定义外部链接：

namexyz@mydomain.co.uk
跟踪文件下载
默认情况下，任何以以下扩展名结尾的文件都将在 Matomo 界面中被视为“下载”：

7z|aac|arc|arj|apk|asf|asx|avi|bin|bz|bz2|csv|deb|dmg|doc|
exe|flv|gif|gz|gzip|hqx|jar|jpg|jpeg|js|mp2|mp3|mp4|mpg|
mpeg|mov|movie|msi|msp|odb|odf|odg|odp|ods|odt|ogg|ogv|
pdf|phps|png|ppt|qt|qtm|ra|ram|rar|rpm|sea|sit|tar|
tbz|tbz2|tgz|torrent|txt|wav|wma|wmv|wpd||xls|xml|z|zip
自定义下载跟踪的文件类型
要替换您想要跟踪的文件下载的扩展名列表，您可以使用setDownloadExtensions( string )：

// we now only track clicks on images
_paq.push([‘setDownloadExtensions’, “jpg|png|gif”]);

_paq.push([‘trackPageView’]);
如果您想要跟踪一种新的文件类型，您可以直接使用以下命令将其添加到列表中addDownloadExtensions( filetype )：

// clicks on URLs finishing by mp5 or mp6 will be counted as downloads
_paq.push([‘addDownloadExtensions’, “mp5|mp6”]);
_paq.push([‘trackPageView’]);
如果您想忽略特殊文件类型，您可以使用以下命令将其从列表中删除removeDownloadExtensions( filetype )：

// clicks on URLs ending in png or mp4 will not be counted as downloads
paq.push([‘removeDownloadExtensions’, “png|mp4”]);
_paq.push([‘trackPageView’]);
将点击记录为下载
如果您想强制 Matomo 将链接视为下载，您可以向链接添加matomodownload或css 类：piwik_download

Link I want to track as a download
注意：您可以自定义并重命名用于强制将点击记录为下载的 CSS 类：

// now all clicks on links with the css class “download” will be counted as downloads

// you can also pass an array of strings
_paq.push([‘setDownloadClasses’, “download”]);

_paq.push([‘trackPageView’]);
或者，您可以使用 JavaScript 手动触发下载点击。在此示例中，单击链接时会触发自定义下载：

Download
更改暂停计时器
当用户点击下载文件或点击出站链接时，Matomo 会记录它。为此，它会在用户重定向到请求的文件或链接之前添加一小段延迟。默认值为 500 毫秒，但您可以将其设置为更短的时间长度。但需要注意的是，这样做会导致这段时间不够长，无法将数据记录在 Matomo 中。

_paq.push([‘setLinkTrackingTimer’, 250]); // 250 milliseconds

_paq.push([‘trackPageView’]);
禁用下载和出站链接跟踪
默认情况下，Matomo 跟踪代码启用点击和下载跟踪。要禁用所有自动下载和出站链接跟踪，您必须删除对该enableLinkTracking()函数的调用：

_paq.push([‘trackPageView’]);

// we comment out the function that enables link tracking
// _paq.push([‘enableLinkTracking’]);
禁用特定的 CSS 类
您可以禁用具有特定 CSS 类的链接的自动下载和出站链接跟踪：

// you can also pass an array of strings
_paq.push([‘setIgnoreClasses’, “no-tracking”]);
_paq.push([‘trackPageView’]);
这将导致链接的点击次数Test不被计算。

禁用特定链接
如果您想忽略特定链接的下载或外部链接跟踪，您可以matomo_ignore向其中添加或“piwik_ignore”css 类：

File I don’t want to track as a download
征求同意
查看我们的集成指南，了解如何实施跟踪或 cookie 同意。

查看退出指南，了解如何使用内置 Matomo 选项实现退出表单

可选：创建自定义退出表单
如果您想让用户能够完全退出跟踪，则可以使用退出表单。Matomo 附带一个使用第三方 Cookie 的退出表单实现（您可以在 Matomo > 管理 > 隐私页面上的 Matomo 中配置）。

此表单嵌入起来很简单，因为它只需要您在网站上添加一个 iframe，但这并不总是理想的。有些用户会阻止第三方 cookie，因此退出表单对他们不起作用。您可能还想在退出表单中显示自定义文本或图形，或者您可能想允许用户单独退出您的网站，而不是全部退出。

在这种情况下，您可能需要考虑创建自定义退出表单。创建 HTML/JS 表单的细节超出了本文档的范围，但每个自定义退出表单都必须执行一些操作：检查用户当前是否已退出、 选择用户退出和选择用户加入。以下是如何执行这些操作：

检查用户当前是否选择退出

使用isUserOptedOut()方法如下：

_paq.push([function () {
if (this.isUserOptedOut()) {
// … change form to say user is currently opted out …
} else {
// … change form to say user is currently opted in …
}
}])
选择用户退出

使用optUserOut()方法：

_paq.push([‘optUserOut’]);
选择用户加入

使用forgetUserOptOut()方法：

_paq.push([‘forgetUserOptOut’]);
下面是一个示例退出表单，复制了内置的 Matomo 退出表单：

如果您尚未升级到 Matomo 2.16.2 或更高版本，请立即升级！（下面有 2.16.1 或更旧版本的说明。）

将您的数据复制到一个 Matomo 服务器中的不同网站
您可能需要将您的网络分析数据副本收集到同一个 Matomo 服务器的另一个网站上。

推荐解决方案：使用 RollUp Reporting 插件
当您需要将数据复制到另一个网站，或将多个网站合并为一个或多个组（称为 RollUps）时，推荐的解决方案是使用RollUp Reporting 高级插件。使用此插件比其他解决方案有几个优势，因为您可以轻松地将一个或多个网站分组在一起，并且 RollUps 不会导致跟踪数据重复，从而提高整体性能。

替代解决方案：复制跟踪数据
除了使用 RollUp Reporting 插件，您还可以复制跟踪数据。要复制数据，您可以addTracker使用 Matomo URL 和您的网站 ID 来复制数据：

var u=”//matomo.example.org/“;
_paq.push([‘setTrackerUrl’, u+’matomo.php’]);
_paq.push([‘setSiteId’, ‘1’]);

// We will also collect the website data into Website ID = 7
var websiteIdDuplicate = 7;
// The data will be duplicated into piwik.example.org/matomo.php
_paq.push([‘addTracker’, u+’matomo.php’, websiteIdDuplicate]);
// Your data is now tracked in both website ID 1 and website 7 into your piwik.example.org server!
由于此解决方案会导致每个访问者的事件、页面浏览量等在您的 Matomo 服务器中被跟踪两次，因此我们通常不推荐它。

将您的分析数据收集到两个或更多个 Matomo 服务器中
下面的示例展示了如何使用addTracker 方法将相同的分析数据跟踪到第二个 Matomo 服务器中。主 Matomo 服务器是piwik.example.org/matomo.php将数据存储到网站 ID 的地方1。第二个 Matomo 服务器是analytics.example.com/matomo.php将数据存储到网站 ID 的地方77。当您在网站中实现此功能时，请将这两个 Matomo URL 和 Matomo 网站 ID 替换为您自己的 Matomo URL 和网站 ID。

自定义其中一个跟踪器对象实例
注意：默认情况下，通过 添加的任何跟踪器都addTracker配置为与主默认跟踪器对象相同（关于 cookie、自定义尺寸、用户 ID、下载和链接跟踪、域和子域等）。如果您想配置通过 添加的 Matomo 跟踪器对象实例之一addTracker，您可以调用Matomo.getAsyncTracker(optionalMatomoUrl, optionalPiwikSiteId) 方法。此方法返回跟踪器实例对象，您可以将其配置为与主 JavaScript 跟踪器对象实例不同。

直接调用 JavaScript API 时复制跟踪数据（不是通过_paq.push）
您可以将分析数据跟踪到同一服务器上的不同网站 ID，也可以将数据的副本记录到另一个 Matomo 服务器中。每次调用都会Matomo.getTracker()返回一个可配置的唯一 Matomo Tracker 对象（实例）。

该matomoAsyncInit()方法将在 Matomo 跟踪器加载并初始化后执行。在早期版本中，您必须同步加载 Matomo。