API参考

JavaScript跟踪客户端

JavaScript跟踪客户端

用户指南

同时阅读JavaScript跟踪客户端用户指南，熟悉JavaScript跟踪客户端。

跟踪API中所有可用方法的列表

从Matomo(以前是Piwik)类请求跟踪器实例

  • Matomo。getTracker(trackerUrl, siteId)-获取一个新的跟踪器实例
  • Matomo。getAsyncTracker(optionalMatomoUrl, optionalMatomoSiteId)-获取用于异步跟踪的Tracker的内部实例

使用Tracker对象

  • trackPageView ([customTitle])—记录页面视图
  • trackEvent(类别，动作，[name]， [value])-记录事件的事件类别(视频，音乐，游戏…)，事件操作(播放，暂停，持续时间，添加播放列表，下载，单击…)，以及可选的事件名称和可选的数值。
  • trackSiteSearch(关键字，[类别]，[resultsCount])-在可选类别中记录特定关键字的内部站点搜索，指定页面中搜索结果的可选计数。
  • trackGoal(idGoal， [customRevenue]);-记录数字目标ID的转换，使用可选的数字自定义收入customRevenue。
  • trackLink(url, linkType)-从你自己的代码记录一次点击。url是完整的url，它将被跟踪为一个点击。linkType可以是'link'表示外链接，也可以是'download'表示下载。
  • trackAllContentImpressions ()-扫描整个DOM的所有内容块，并跟踪所有的印象，一旦DOM ready事件被触发。
  • trackVisibleContentImpressions (checkOnScroll, timeIntervalInMs)-扫描整个DOM的所有内容块，一旦页面被加载。它只在内容块实际可见时才跟踪印象。
  • trackContentImpressionsWithinNode(domNode)-扫描给定的DOM节点及其子节点的内容块，如果没有跟踪它们的印象，则跟踪它们的印象。
  • trackContentInteractionNode(domNode, contentInteraction)-跟踪与给定DOM节点/内容块的交互。
  • trackContentImpression(contentName, contentPiece, contentTarget)—使用指定的值跟踪内容印象。
  • trackContentInteraction(contentInteraction, contentName, contentPiece, contentTarget)—使用指定的值跟踪内容交互。
  • logAllContentBlocksOnPage ()-将页面中所有找到的内容块记录到控制台。这对于调试/测试内容跟踪非常有用。
  • ping ()—发送ping请求。Ping请求不跟踪新动作。如果在标准访问时间内发送，则会更新现有的访问时间。如果在标准访问长度之后发送，ping请求将被忽略。另请参阅enableHeartBeatTimer．
  • enableHeartBeatTimer(activeTimeInseconds)-安装一个心跳计时器，它会向Matomo发送额外的请求，以便更好地衡量在访问中花费的时间。这些请求只在用户正在积极地查看页面时(当选项卡处于活动状态并处于焦点状态时)才会被发送。这些请求不会跟踪额外的操作或页面浏览量。默认情况下,activeTimeInSeconds设置为15秒。这意味着只有当页面被浏览了至少15秒(并且用户离开页面或将焦点从标签上移开)，才会发送ping请求。另请参阅平和开发人员指南．
  • enableLinkTracking(启用)-在所有适用的链接元素上安装链接跟踪。将enable参数设置为true以使用伪单击处理程序(将中键单击和打开上下文菜单视为左键单击)。在链接上的右键单击(或任何打开上下文菜单的单击)将被跟踪，即使没有选择“在新选项卡中打开”。如果“false”(默认值)，在打开上下文菜单或中间单击时将不会跟踪任何内容。
  • disablePerformanceTracking—禁用页面性能跟踪功能。
  • enableCrossDomainLinking ()—启用跨域链接。默认情况下，标识唯一访问者的访问者ID存储在浏览器的第一方cookie中。这意味着cookie只能被同一域上的页面访问。如果您拥有多个域名，并希望跟踪特定访问者在同一次访问中的所有操作和页面浏览量，您可以启用跨域链接(了解更多)．每当用户点击一个链接时，它都会附加一个URL参数pk_vid到所单击的URL，该URL将当前访问者ID值转发到不同域的页面。
  • setCrossDomainLinkingTimeout(timeout)—设置跨域链接超时时间(单位:秒)。默认情况下，当点击链接并在180秒超时窗口内加载页面时，两次跨域访问将被链接在一起。”
  • getCrossDomainLinkingUrlParameter ()—获取附加到链接的查询参数，以处理跨域链接。使用它可以为动态添加到DOM的链接添加跨域支持。了解关于跨域链接的更多信息．
  • disableBrowserFeatureDetection ()-默认情况下，Matomo访问来自访问者浏览器的信息，以检测当前浏览器的分辨率以及支持哪些浏览器插件(例如PDF和cookie)。此信息用于向您显示访问者的浏览器分辨率、支持的浏览器插件的报告，还用于为每个访问者生成一个短期标识符，我们称之为config_id．一些隐私法规可能只允许在征得访问者同意后访问其设备上的信息。如果这适用于您，请调用此方法以不再访问此信息。了解有关浏览器特性检测的更多信息
    • enableBrowserFeatureDetection ()—如果您之前关闭了浏览器特性检测功能，则启用该功能。

Tracker对象的配置

  • setDocumentTitle(string)-覆盖document.title
  • setDomains(数组)—设置待处理的主机名或域的数组。对于通配符子域，您可以使用:setDomains(“.example.com”);或setDomains (* .example.com);．你也可以沿着域指定路径:setDomains(“* .example.com/subsite1”);
  • setCustomUrl(string)-覆盖页面报告的URL
  • setReferrerUrl(string)—覆盖检测到的Http-Referer。我们建议您在调用此方法之前，在跟踪代码的早期调用此方法trackPageView是否应该应用于所有跟踪请求。
  • setExcludedReferrers(string |数组)-设置需要忽略的主机名或域作为引用。对于通配符子域，您可以使用:setExcludedReferrers(“.example.com”);或setExcludedReferrers (* .example.com);．你也可以沿着域指定路径:setExcludedReferrers(“* .example.com/subsite1”);．该方法在Matomo 4.12可用。
  • getExcludedReferrers ()-返回被排除的引用者列表，这是之前使用setExcludedReferrers．
  • setSiteId(integer)—指定网站ID。冗余:可在getTracker ()构造函数。
  • setApiUrl(string)—指定Matomo HTTP API URL端点。指向piwik的根目录，例如https://matomo.example.org/或https://example.org/matomo/。此函数仅在'Overlay'报告不工作时有用。缺省情况下，不需要使用该功能。
  • setTrackerUrl(string)—指定Matomo服务器URL。冗余:可在getTracker ()构造函数。
  • getMatomoUrl ()—返回Matomo服务器的URL。
  • getPiwikUrl ()—弃用，使用getMatomoUrl ()代替。
  • getCurrentUrl ()-返回当前正在访问的页面的当前url。如果在调用此方法之前设置了自定义URL，则将返回自定义URL。
  • setDownloadClasses(string |数组)-将类设置为下载(除了matomo_download)
  • setdownloadadextensions (string |数组)-设置要识别为下载的文件扩展名列表。示例:'doc'或['doc'， 'xls']
  • adddownloadadextensions(字符串|数组)-指定将被识别为下载的其他文件扩展名。示例:'doc'或['doc'， 'xls']
  • removedownloadxtensions(字符串|数组)—在下载文件扩展名列表中指定要删除的文件扩展名。示例:'doc'或['doc'， 'xls']
  • setIgnoreClasses(string |数组)-设置link中存在的类被忽略(除了matomo_ignore和piwik_ignore)
  • setLinkClasses(string |数组)-将类设置为外链接(除了piwik_link)
  • setLinkTrackingTimer(整数)—设置链路跟踪延迟时间，单位为毫秒。
  • getLinkTrackingTimer ()-获取链路跟踪延迟(以毫秒为单位)。
  • discardHashTag(bool)—设置为true，表示不记录url的散列标签(锚)部分
  • appendToTrackingUrl (appendToUrl)-附加一个自定义字符串到HTTP请求的结束matomo.php?
  • setDoNotTrack(bool)-设置为true，不跟踪使用Mozilla的(建议的)不跟踪设置选择不跟踪的用户。
  • killFrame ()-启用框架破坏者，以防止被跟踪的网页被框架/框。
  • 重定向文件(url)-如果跟踪的网页是从本地文件加载(例如，保存到某人的桌面)，则强制浏览器加载实时URL。
  • setHeartBeatTimer(minimumVisitLength, heartBeatDelay)-如果达到minimumVisitLength(以秒为单位)，记录页面已经被浏览了多长时间;heartBeatDelay决定更新服务器的频率
  • getVisitorId ()—返回16个字符的访问者ID
  • setvistoriid (visitorId)-visitorId需要是16位十六进制字符串。visitorId不会保存在cookie中，需要在每次加载新页面时设置。
  • getVisitorInfo ()—以数组形式返回访问者cookie内容

  • getAttributionInfo ()-返回访客属性数组(推荐人信息和/或活动名称和关键字)。归因信息被Matomo用来信任正确的推荐人(第一个或最后一个推荐人)当用户触发目标转换时使用。

    你也可以使用以下任何函数来获取数据的特定属性:

    • matomoTracker.getAttributionCampaignName ()
    • matomoTracker.getAttributionCampaignKeyword ()
    • matomoTracker.getAttributionReferrerTimestamp ()
    • matomoTracker.getAttributionReferrerUrl ()

  • getUserId ()—如果设置了User ID，则返回字符串。

  • setUserId(userId)—设置用户ID发送给该用户(如电子邮件地址或用户名)。
  • resetUserId—清除(取消设置)用户ID。
  • setCustomVariable(索引，名称，值，范围)—自定义变量。
  • deleteCustomVariable(索引，范围)—删除自定义变量。
  • getCustomVariable(索引，范围)—检索自定义变量。
  • storeCustomVariablesInCookie ()-当调用时，范围为“visit”的自定义变量将存储(持久化)在第一方cookie的访问期间。如果你想打电话，这很有用getCustomVariable在访问之后。(默认情况下，自定义变量不存储在访问者的计算机上。)
  • setCustomDimension (customDimensionId, customDimensionValue)—自定义维度。(需要自定义尺寸插件）
  • deleteCustomDimension (customDimensionId)—删除自定义维度。(需要自定义尺寸插件）
  • getCustomDimension (customDimensionId)-检索自定义维度。(需要自定义尺寸插件）
  • setCampaignNameKey(名字)—设置活动名称参数。(帮助:自定义活动名称参数名称）
  • setCampaignKeywordKey(关键字)—设置活动关键字参数。(帮助:自定义Campaign关键字参数名称）
  • setconversionattributionfirstferrer (bool)-设置为true，将转换属性设置为第一个引用者。默认情况下，转换归属于最近的引用者。

电子商务

Matomo提供电子商务分析它可以让你测量添加到购物车中的物品，并了解关于废弃购物车和购买订单的详细指标。有关示例和更多信息，请点击这里．

  • setEcommerceView(productSKU, productName, categoryName, price)—将当前页面视图设置为产品或类别页面视图。当你打电话时setEcommerceView它后面必须有一个调用trackPageView记录产品或类别的页面视图。
  • addecommercer item (productSKU， [productName]， [productCategory]， [price]， [quantity])-在电子商务订单中添加一个产品。必须为订单中的每个产品调用。
  • removeEcommerceItem(产品sku)-从未跟踪的电子商务订单中删除指定产品。
  • clearEcommerceCart ()-删除未跟踪电子商务订单中的所有产品。_注:这是自动完成后trackEcommerceOrder ()被称为。
  • getEcommerceItems ()-返回当前未跟踪电子商务订单中的所有电子商务项目。返回的数组将是一个副本，因此更改它不会影响电子商务订单。要影响跟踪的内容，请使用addEcommerceItem ()/removeEcommerceItem ()/clearEcommerceCart ()方法。使用此方法可以在跟踪订单或购物车更新之前查看要跟踪的内容。
  • trackEcommerceCartUpdate(grandTotal)-跟踪购物车。每当用户从购物车中添加、更新或删除产品时，调用此javascript函数。
  • trackEcommerceOrder(orderId, grandTotal， [subTotal]， [tax]， [shipping]， [discount])-跟踪电子商务订单，包括之前添加到订单中的任何电子商务项目。orderId而且总计(即。收入)是必需的参数。

Matomo提供了一种机制来管理用户的跟踪同意。您可以在跟踪用户的任何操作之前要求用户同意，对不同意的用户禁用跟踪，并在以后对同意的用户重新启用跟踪。在未经同意的情况下，不会使用cookies。一旦得到同意，cookie将被使用。

  • requireConsent ()-默认情况下，Matomo跟踪器假设同意跟踪。要更改此行为，以便在用户同意之前不跟踪任何内容，必须调用requireConsent．
  • setConsentGiven ()—标记当前用户已同意。这种同意只是一次性的，所以在随后的浏览器会话中，用户将不得不再次同意。记住同意，请看下面的方法:rememberConsentGiven．
  • memorberconsentgiven (hoursToExpire)-标记当前用户已同意，并通过浏览器cookie记住此同意。用户下次访问网站时，Matomo将记住他们的同意，并跟踪他们。如果调用此方法，则不需要调用setConsentGiven．
  • forgetConsentGiven ()-删除用户的同意，如果同意只是一次性的，如果同意被记住。调用此方法后，用户必须再次同意才能被跟踪。
  • hasRememberedConsent ()-根据当前访问者之前是否同意，返回true或false。
  • getRememberedConsent ()-如果已给予同意，则返回访问者给予同意的时间戳。只有当rememberConsentGiven被使用过，而不是什么时候setConsentGiven是使用。时间戳是本地时间戳，取决于访问者的时间。
  • isConsentRequired ()—根据是否返回true或falserequireConsent之前被调用过。

Matomo还提供了一种机制来管理用户的cookie同意。您可以要求用户同意使用cookie。跟踪请求将始终发送，但取决于同意cookie将被使用或不被使用。

  • requireCookieConsent ()-默认情况下，Matomo跟踪器假设同意使用cookie。若要更改此行为，以便默认情况下不使用cookie，必须调用requireCookieConsent．
  • setCookieConsentGiven ()—标记当前用户已同意使用cookie。这种同意只是一次性的，所以在随后的浏览器会话中，用户将不得不再次同意。要记住cookie同意，请参见下面的方法:rememberCookieConsentGiven．
  • memorbercookieconsentgiven (hoursToExpire)-标记当前用户已同意使用cookie，并通过浏览器cookie记住这一同意。用户下次访问网站时，Matomo将记住他们已同意，并使用cookie。如果调用此方法，则不需要调用setCookieConsentGiven．
  • forgetCookieConsentGiven ()-删除用户的cookie同意，如果同意只是一次性的，如果同意被记住。调用此方法后，用户必须再次同意才能使用cookie。
  • areCookiesEnabled ()—根据cookie当前是否启用或禁用返回true或false。
  • getRememberedCookieConsent ()—如果cookie同意，则返回访问者同意的时间戳。只有当rememberCookieConsentGiven被使用过，而不是什么时候setCookieConsentGiven是使用。时间戳是本地时间戳，取决于访问者的时间。

管理退出

您是想建立一个自定义的选择退出表单，而不是同意屏幕，还是使用我们的退出iframe？查看指南创建自定义退出表单．

  • optUserOut ()-调用此函数后，用户将被退出，不再被跟踪。
  • forgetUserOptOut ()-调用此方法后，用户将再次被跟踪。如果用户之前选择退出，则调用此方法。
  • isUserOptedOut ()-根据用户是否选择退出，返回true或false。注意:如果您正在使用选择iframe．

您可以使用这些方法构建自己的同意书/页面。了解更多关于征求同意的信息。

跟踪cookie配置

Matomo使用第一方cookie随着时间的推移跟踪一些用户信息。必须考虑用户留存时间，避免与其他cookie、跟踪器和应用发生冲突。

  • disableCookies ()-禁用所有第一方cookie。本网站现有的Matomo cookie将在下一页视图中删除。如果用户同意使用该方法，cookie甚至会被禁用rememberCookieConsentGiven ()．
  • deleteCookies ()-删除当前设置的跟踪cookie(这是有用的创建新的访问）
  • hasCookies ()—返回本浏览器是否启用并支持cookie。
  • setCookieNamePrefix(prefix)-默认前缀是'pk”。
  • setcookie域(域)-默认为文档域;如果你的网站可以通过www.example.com和example.com访问，你可以使用:tracker.setCookieDomain(“.example.com”);或tracker.setCookieDomain (* .example.com);
  • setcookie路径—默认为“/”。
  • setSecureCookie(bool)-设置为true，在所有第一方cookie上启用安全cookie标志。当您的网站仅在HTTPS下可用时，应使用此选项，以便所有跟踪cookie始终通过安全连接发送。
  • setCookieSameSite(字符串)-默认为宽松的．可以设置为没有一个或严格的．没有一个要求所有流量都使用HTTPS，并将自动设置安全cookie。它可以是有用的，例如，如果跟踪的网站是一个iframe。严格的只有当你的Matomo和网站运行在同一个域名上。
  • setVisitorCookieTimeout(秒)—默认为13个月
  • setReferralCookieTimeout(秒)—默认为6个月
  • setSessionCookieTimeout(秒)—默认为30分钟

先进的使用

  • addListener(元素)-添加点击监听器到一个特定的链接元素。当点击时，Matomo将自动记录点击。
  • setRequestMethod(方法)—请求方式为GET或POST。要使用POST请求方法，要么1)Matomo主机与跟踪网站主机相同(Matomo安装在与跟踪网站相同的域中)，要么2)如果Matomo没有安装在与您的网站相同的主机上，您需要启用CORS(跨域请求)，详见本FAQ．请记住，当Matomo使用sendBeacon()发送跟踪请求(默认启用)时，它将通过POST发送数据。如果你想让Matomo永远不发送POST请求，你可以使用这个方法强制得到会自动禁用sendBeacon．
  • disableAlwaysUseSendBeacon ()-禁用发送跟踪跟踪请求navigator.sendBeacon默认启用。
  • setCustomRequestProcessing(函数)-设置一个处理请求内容的函数。一旦准备好请求(查询参数字符串)，并且在发送请求内容之前，将调用该函数。
  • setRequestContentType(内容类型)—设置请求内容类型头值。适用于“POST”请求方法使用viasetRequestMethod．
  • disableQueueRequest ()—禁用将多个跟踪请求分组并作为批量POST请求发送的功能。当您希望能够禁用此功能时，禁用此功能非常有用重播所有日志:必须使用disableQueueRequest禁用此行为，以便稍后能够重放已记录的Matomo日志(否则一部分请求将无法重放)。
  • setRequestQueueInterval(interval)-定义在请求最初排队后，排队请求将在多少毫秒后执行。该值越高，可以同时发送的跟踪请求就越多。时间间隔至少是1000(1000ms = 1s)，缺省值为2.5秒。
  • setPagePerformanceTiming([networkTimeInMs]， [serverTimeInMs]， [transferTimeInMs]， [domProcessingTimeInMs]， [domCompletionTimeInMs]， [onloadTimeInMs])-在单页应用中手动设置以毫秒为单位的性能指标，或者当Matomo无法检测到某些指标时。参数可以设置为未定义的如果您不想跟踪这个指标。至少需要设置一个参数。设置的性能计时只会在下一个页面视图中跟踪。如果跟踪另一个页面视图，则需要再次设置性能计时。需要Matomo 4.5或更新版本。

涵盖matomo.js的单元测试

Matomo JavaScript跟踪API由一个广泛的JavaScript单元测试套件覆盖，以确保代码质量尽可能高，并且我们永远不会破坏这个功能。测试使用QUnit编写。要运行测试，只需签出Matomo Git存储库然后转到/道路/ / matomo /测试/ javascript /．测试在浏览器内部运行。

Matomo JavaScript API已经在许多web浏览器上进行了测试。为了扩大覆盖范围，我们使用了crossbrowsertesting.com而且browsershots.org．

贬低matomo.js

matomo.js被缩小了，以减少网站访问者必须下载的大小。YUI压缩器是用来缩小JavaScript (更多的信息)．你可以在/ js / piwik.js．

Baidu