跟踪HTTP API

要跟踪页面视图,事件,访问,你必须发送一个HTTP请求(GET或POST)到跟踪HTTP API端点,例如,https://your-matomo-domain.example/matomo.php设置正确的查询参数。

支持的查询参数

本节列出跟踪API支持的各种查询参数。其中一些字段的数据在你的应用程序/软件中是不可用的,但你应该提供尽可能多的信息。

注意:所有参数值都是字符串(如'url', 'action_name'等)必须是url编码。

必需的参数

  • idsite(必需)-我们正在跟踪访问/操作的网站的ID。
  • 矩形(必需)-跟踪所需,必须设置为1,例如,rec = 1
  • action_name(推荐)-正在跟踪的动作的标题。这是可能的使用斜杠/可以设置一个或多个此操作的类别.例如,帮助/反馈将创建动作反馈在这个类别中帮助
  • url(推荐)-当前操作的完整URL。
  • _id(推荐)—唯一的访问者ID,必须是16个字符的16进制字符串。每个唯一访问者必须分配一个不同的ID,并且这个ID在分配后不能更改。如果没有设置这个值,Matomo(以前的Piwik)仍然会跟踪访问,但唯一访问者指标可能不太准确。
  • 兰德(推荐)-意味着保存在每个请求之前生成的随机值。使用它可以帮助避免跟踪请求被浏览器或代理缓存。
  • apiv(推荐)参数&apiv=1定义了要使用的api版本(当前总是设置为1)

可选用户信息

(如果信息可用并且与您的用例相关,我们建议使用这些参数。)

  • urlref-完整的HTTP Referrer URL。此值用于确定某人如何访问您的网站(即,通过网站,搜索引擎或活动)。
  • _cvar-参观范围自定义变量.这是一个JSON编码的自定义变量数组字符串(参见下面的示例值)。
  • _rcn-活动名称(见跟踪活动).用于填充推荐者>活动报告。注意:此参数仅用于访问的第一页浏览量。
  • _rck-活动关键字(请参阅跟踪活动).用于填充推荐者>活动报告(点击一个活动加载该活动的所有关键字)。注意:此参数仅用于访问的第一页浏览量。
  • res-访问者正在使用的设备的分辨率,例如1280 x1024
  • h—当前小时(当地时间)。
  • —当前分钟(当地时间)。
  • 年代—当前秒(当地时间)。
  • 访问者使用的插件可以通过以下参数设置为1来指定:佛罗里达州(Flash),java(Java),dir(主任)qt(Quicktime),realp(真正的球员),pdf(PDF),的wma(Windows Media),齿轮(齿轮),ag)(Silverlight)。
  • 饼干—当设置为1时,表示已知访问者的客户端支持cookie。

  • ua控件的覆盖值用户代理HTTP报头字段。用户代理用于检测所使用的操作系统和浏览器。

  • uadata- JSON编码客户端提示由javascript收集。这将用于丰富检测到的用户代理数据。(需要Matomo 4.12.0)
  • 控件的覆盖值接收语言HTTP报头字段。此值用于检测访问者的国家GeoIP未启用。
  • uid-定义用户ID对于这个请求。用户ID是标识用户的任何非空唯一字符串(例如电子邮件地址或用户名)。要访问这个值,用户必须登录到您的系统中,这样您就可以从系统中获取这个用户ID,并将它传递给Matomo。用户ID显示在访问日志、访问者配置文件中报告一个或多个用户ID (用户标识段)。当指定时,用户ID将被“强制执行”。这意味着如果最近没有使用该用户ID的访问,将创建一个新的用户ID。如果在过去30分钟内发现了使用您指定的用户ID的访问,则新的操作将被记录到此现有访问中。
  • cid-为这个请求定义访问者ID。您必须将此值设置为精确的16个字符的十六进制字符串(仅包含字符01234567890abcdefABCDEF)。我们建议设置用户ID viauid而不是使用这个cid
  • new_visit-如果设置为1,将强制为该操作创建一个新的访问。这个特性也是可用JavaScript
  • 维度(0 - 999)-特定自定义维度ID的自定义维度值(需要Matomo 2.15.1 +)自定义尺寸插件看到自定义尺寸指南).如果自定义维度ID为2使用dimension2 = dimensionValue发送此维度的值。配置的自定义维度必须在“访问”范围内。
  • cvar-页面范围自定义变量.这是一个JSON编码的自定义变量数组字符串(参见下面的示例值)。
  • 链接—用户已打开的外部URL。用于跟踪外链接点击。我们建议还设置url参数设置为相同的值。
  • 下载-用户已下载文件的URL地址。用于跟踪下载。我们建议还设置url参数设置为相同的值。
  • 搜索—站点搜索关键字。当指定时,请求将不会被跟踪为一个正常的页面浏览量,而是被跟踪为网站搜索请求。
  • search_cat——当搜索指定时,您可以选择使用此参数指定搜索类别。
  • search_count——当搜索,我们还建议将search_count设置为结果页面上显示的搜索结果的数量。当使用&search_count=0跟踪关键字时,它们将出现在“无结果搜索关键字”报告中。
  • pv_id-接受一个6个字符的唯一ID,用于识别在特定页面视图上执行了哪些操作。当一个页面被查看时,该页面查看期间的所有跟踪请求(如事件)应该使用相同的页面视图ID。一旦查看了另一个页面,就应该生成一个新的惟一ID。使用(0-9a-Z)作为唯一ID的可能字符。
  • idgoal—如果指定,跟踪请求将触发目标被这个ID追踪的网站
  • 收入-通过目标转换产生的货币价值。仅在以下情况下使用idgoal在请求中指定。
  • gt_ms-服务器生成该操作所花费的时间,以毫秒为单位。此值用于处理页面速度报告平均生成时间页面URL和页面标题报告中的列,以及站点范围内服务器的平均运行速度。注意:当使用JavaScript跟踪器时,这个值被设置为服务器生成响应的时间+客户端下载响应的时间。
  • cs-被跟踪页面的字符集。如果发送给Matomo的数据编码的字符集与默认字符集不同,则指定字符集utf - 8
  • 维度(0 - 999)-特定自定义维度ID的自定义维度值(需要Matomo 2.15.1 +)自定义尺寸插件看到自定义尺寸指南).如果自定义维度ID为2使用dimension2 = dimensionValue发送此维度的值。配置的自定义维度必须在“动作”范围内。
  • ca—自定义动作。及长安= 1可以选择沿任何跟踪请求,不是一个页面视图发送。例如,它可以与事件跟踪请求一起发送e_a = Action&e_c = Category&ca = 1.好处是,如果你曾经禁用事件插件,那么事件跟踪请求将被忽略,而如果没有设置参数,一个页面视图将被跟踪,即使它不是一个页面视图。欲了解更多背景信息,请查看# 16570.该参数不能与萍= 1跟踪的要求。

可选页面的性能信息

对于页面浏览量,可以跟踪以下页面性能指标:

  • pf_net—网络时间。连接到服务器需要多长时间。
  • pf_srv—服务器时间。服务器生成页面所需的时间。
  • pf_tfr-转移时间。浏览器从服务器下载响应需要多长时间
  • pf_dm1—Dom处理时间。在完全接收到响应后,浏览器花费多长时间加载网页,直到用户可以开始与它交互。
  • pf_dm2- Dom完成时间。浏览器加载媒体和执行监听DOMContentLoaded事件的Javascript代码需要多长时间。
  • pf_onl-加载时间。浏览器执行Javascript代码等待窗口所需的时间。负载的事件。

所有页面性能指标的值都以毫秒为单位。

可选事件跟踪信息

  • e_c—事件类别。一定不能空。(如。视频、音乐、游戏……)
  • e_a—事件动作。一定不能空。(如。播放,暂停,持续时间,添加播放列表,下载,点击…)
  • e_n—事件名称。(如。电影名、歌曲名或文件名……)
  • e_v—事件值。必须是浮点数或整数值(数字),而不是字符串。

注意:将从参数值中删除尾随和前导空白e_ce_a而且e_n.用空格填充的字符串将被认为是(无效的)空值。

可选内容跟踪信息

  • c_n—内容名称。比如Ad Foo Bar
  • c_p-实际内容部分。例如,图像、视频、音频、任何文本的路径
  • c_t-内容的目标。例如,登录页面的URL
  • 为c_i-与内容交互的名称。例如,点击

跟踪一个内容印象集c_n和(可选)c_p而且c_t.跟踪内容交互集为c_i而且c_n和(可选)c_p而且c_t.要将交互映射到印象,请确保为其设置相同的值c_n而且c_p.建议设置为c_p

可选电子商务信息

使用以下值记录购物车和/或电子商务订单。

  • 你必须设置&idgoal = 0在跟踪电子商务交互的请求中:购物车更新或电子商务订单。
  • ec_id电子商务订单的唯一字符串标识符(跟踪电子商务订单时需要)
  • ec_items-电子商务订单中的项目。这是一个JSON编码的项目数组。每一项都是一个数组,按照顺序包含以下信息:

    • 项目sku(必需),
    • 项目名称(如果不适用,则设置为空字符串),
    • 项目类别(如果不适用,则设置为空字符串),
    • 物品价格(如果不适用,设置为0),
    • 项目数量(如果不适用,设置为1)。

    的示例值ec_items是:% 5 b % 5 b % 22 item1 % 20 sku % 22% 2 c % 22 item1 % 20名% 22% 2 c % 22 item1 % 20类别% 22% 2 c11.1111 % 2 c2 % 5 d % 2 c % 5 b % 22第二条% 20 sku % 22% 2 c % 22第二条% 20名% 22% 2 c % 22% 22% 2 c0 % 2 c1 % 5 d % 5 d(网址解码后的版本为:[[“item1 SKU”、“item1名称”、“item1类别”,11.1111,2],[“第二条SKU”,“第二条名称”,“”,0,1]]).

  • 收入-电子商务订单的总金额(跟踪电子商务订单时需要)
  • ec_st-订单的小计;不包括航运。
  • ec_tx-订单的税额
  • ec_sh-订单的运费
  • ec_dt-提供的折扣

其他参数(需要通过token_auth

以下参数需要您设置&token_auth =到超级用户的token_auth值,或具有管理网站访问许可正在被追踪。

  • token_auth—32个字符的授权密钥,用于对API请求进行认证。我们建议创建一个专门用于访问跟踪API的用户,并只提供该用户对网站的许可。
  • cip—覆盖访问者IP的值(支持IPv4和IPv6表示法)。
  • cdt-覆盖请求的datetime(通常使用当前时间)。这可以用来记录过去的访问量和页面浏览量。期望的格式是一个日期时间,例如:2011-04-05 00:11:42(记住对值进行URL编码!),或者有效的UNIX时间戳,例如1301919102.datetime必须在UTC时区发送。注:如果你记录的是过去的数据,你将需要迫使Matomo重新处理过去日期的报告如果你设置cdt到一个超过24小时的日期时间token_auth必须设置。如果你设置cdt如果日期时间在过去24小时内,那么你不需要通过token_auth
  • 国家—国家的覆盖值。应该设置为访问者的两个字母的国家代码(小写),例如fr我们
  • 地区—区域的覆盖值。应设置为ISO 3166-2地区代码,这是由MaxMind的而且DB-IP的GeoIP2数据库。看到在这里查看每个国家的名单。
  • 城市—城市的覆盖值。访问者所在城市的名称,例如:东京
  • 纬度-访问者纬度的覆盖值,例如22.456
  • -一个覆盖值的访问者的经度,例如22.456

媒体分析参数

您的媒体内容(视频播放器和音频播放器)的分析可以使用付费记录媒体分析插件的HTTP跟踪API参数。

您的视频和音频的活动和消费可以通过参数来测量ma_idma_tima_rema_mtma_pnma_stma_lema_psma_ttpma_wma_hma_fsma_se

欲知详情,请浏览媒体分析HTTP跟踪API参考

队列跟踪参数

排队跟踪可以通过在Redis或Mysql中排队跟踪请求来扩展您的大流量Matomo (Piwik)服务,以便在遇到峰值时获得更好的性能和可靠性。

  • queuedtracking—当设置为时0(0),将不使用队列跟踪处理程序,而是直接执行跟踪请求。当您需要调试跟踪问题或希望测试跟踪是否正常工作时,这可能很有用。

其他参数

  • send_image—如果设置为0 (send_image = 0) Matomo将响应HTTP 204响应代码,而不是GIF图像。这可以提高性能,并可以修复错误,如果图像不允许直接获得(如Chrome应用程序)。自Matomo 2.10.0起可用
  • —如果设置为1 (萍= 1),则该请求将是一个心跳请求它不会跟踪任何新活动(如新访问、新行动或新目标)。当设置此参数时,心跳请求只会更新访问的总时间,以提供准确的“访问持续时间”度量。它不会记录任何其他数据。这意味着当用户离开你的网站或应用程序时,发送一个额外的跟踪请求萍= 1,您修复了在最后一个页面所花费的时间报告为0秒的问题。

跟踪机器人

默认情况下Matomo不会跟踪机器人。如果直接使用跟踪HTTP API,您可能会对跟踪机器人请求感兴趣。要在Matomo中启用Bot Tracking,请设置该参数机器人= 1在您的请求中matomo.php

跟踪请求示例

类使用的真实跟踪请求的示例Matomo手机应用在匿名跟踪移动应用程序使用情况时:

https://matomo-server/matomo.php?_cvar={"1":["OS","iphone 5.0"],"2":["Matomo Mobile Version","1.6.2"],"3":["Locale","en::en"],"4":["Num Accounts","2"]}&action_name=View settings&url=http://mobileapp.www.hju8.com/window/settings &idsite=8876&rand=351459&h=18&m=13&s=3 &rec=1&apiv=1&cookie=1&urlref=https://iphone.mobileapp.piwik.org&_id=af344a398df83874 &_idvc=19&res=320×480&

注意:为清晰起见,参数值在本例中不是URL编码。

解释:这个URL有自定义变量的操作系统,Matomo版本,创建的帐户数量。它跟踪一个名为视图设置使用假URL,记录屏幕分辨率,还包括一个自定义的唯一ID,以确保同一移动应用程序用户的所有请求都将记录在Matomo的同一次访问。

批量跟踪

的一些应用程序2021亚博最新 ,他们不得不同时跟踪很多次访问,有时是数十次、数百次、数千次甚至更多。用每次访问或操作一个HTTP请求跟踪这些请求会导致巨大的然而,使用批量跟踪功能,这些请求可以一次性发送,使应用程序更加高效。

要发送批量跟踪请求,必须使用JSON对象向Matomo跟踪端点发送HTTP POST。对象必须包含以下属性:

  • 请求-单个跟踪请求的数组。如果要单独跟踪该操作,每个跟踪请求都应该是发送的查询字符串。
    • 注意,为了Matomo准确地存储跟踪数据,跟踪请求应该按时间顺序发送(最早的请求应该出现在前面)。
  • token_auth-(可选)token_auth,在API页面中找到。仅在使用所需的任何参数时指定此参数token_auth

批量请求

这是一个批量跟踪请求的有效负载示例:

{"requests": ["?idsite=1&url=https://example.org&action_name=Test bulk log Pageview&rec=1", "?idsite=1&url=https://example.net/test.htm&action_name=Another bulk page view&rec=1"], "token_auth": "33dc3f2536d3025974cccb4b4d2d98f4"}

下面是使用curl将请求发送到Matomo的命令token_auth在这种情况下是可选的):

curl -i -X POST -d '{"requests":["?idsite=1&url=https://example.org&action_name=Test bulk log Pageview&rec=1","?idsite=1&url=http://example.net/test.htm&action_name=Another bulk page view&rec=1"]}' https://matomo.example.com/matomo.php

这将跟踪两个仅使用操作一个对Matomo的HTTP请求。

调试跟踪器

为了验证您的数据被正确跟踪,您可以在Matomo跟踪文件中启用调试日志,matomo.php

跟踪请求将输出跟踪日志消息,而不是显示1*1透明的GIF信标。出于安全原因,不应该在生产环境中这样做,或者只在很短的时间内这样做。

按照以下步骤启用和查看跟踪器的调试日志记录:

  1. 在配置文件中路径/ / matomo / config / config.ini.php,写如下:

    [Tracker] debug = 1

由于Matomo 3.10启用SQL查询分析,您还需要启用:

[Tracker] enable_sql_profiler = 1 .使用实例
  1. 查看发送到Matomo的HTTP请求。
    • 如果请求是在浏览器中发生的,则可以使用Firefox开发者版查看所有请求matomo.php
    • 如果请求是由应用程序或软件直接触发的,您可以输出或记录跟踪请求的输出,并查看调试消息。
    • 你也可以将消息记录到文件或数据库(至少需要Matomo 2.15.0)。

如果您收到了太多的跟踪请求,并且日志被这些请求发送成垃圾邮件,或者如果您只想调试某些特定的请求,您可以选择启用debug_on_demandconfig.ini.php:

[Tracker] debug_on_demand = 1 .使用实例

在这种情况下,只有具有URL参数的Tracker请求才会记录消息debug = 1集。这被认为是更安全的,但仍然应该只在短时间内启用。

了解更多

Baidu