Flutter数据分析与跟踪插件matomo_forever的使用
Flutter数据分析与跟踪插件matomo_forever的使用
matomo_forever 是一个持久化的Dart插件，用于通过Flutter应用程序将数据发送到Matomo服务器。本插件基于Matomo HTTP跟踪API文档。
为什么选择 matomo_forever?
Matomo 是一个免费、开源、全面、可靠的解决方案，用于收集和分析应用和网站的使用情况。这可以通过Matomo云解决方案（付费）或通过本地服务器实现。
在编写本文时，pub.dev上提供了两个Matomo相关的插件，但它们都存在以下问题：
- 只支持iOS和Android。
- 即使在iOS和/或Android上也会导致故障。
- 不够灵活。
matomo_forever 提供了一个更简单且更具灵活性的实现方案。它支持：
- 所有在Matomo API中描述的字段。
- 设置自定义HTTP头。
- 批量发送。
平台支持
该插件已在以下平台成功测试过：Android、iOS、Linux、MacOS 和 Chrome。预计也能在Windows上正常工作。
示例
包含在主项目下的 example 文件夹中有一个示例应用项目。此示例应用是与Matomo服务器交互的一个好方法。
在线演示
你可以直接从浏览器访问此示例应用： 在线演示。
构建示例应用
你可以从CI/CD下载已构建的示例应用：
代码
插件使用
添加依赖
在 pubspec.yaml 的 dependencies 部分添加以下依赖项：
dependencies:
matomo_forever:
然后运行以下命令获取包：
flutter packages get
导入库
在你的Dart文件中导入以下库：
import 'package:matomo_forever/matomo_forever.dart';
初始化
调用 init 静态方法来初始化插件：
MatomoForever.init(
siteUrl,
idSite,
id: id,
apiV: apiV,
rec: rec,
method: MatomoForeverMethod.post,
bulkSize: bulkSize,
tokenAuth: tokenAuth,
headers: headers,
persistentParameters: persistentParameters,
);
其中：
siteUrl(必填): Matomo 或 piwik URL，例如https://matomo.example.com/matomo.phpidSite(必填): 要跟踪访问/操作的网站ID。id: 唯一访客ID，必须是一个16个字符的十六进制字符串。每个唯一访客必须分配不同的ID，并且在分配后不能更改。如果不设置此值，Matomo（前身为Piwik）仍会跟踪访问，但唯一访客指标可能不够准确。对应于_id在Matomo API中。apiV: 参数&apiv=1定义要使用的API版本（目前始终设置为1）。rec: 必须设置为true以进行跟踪。method: 可以是post或get，除了批量发送必须通过post方法发送外。bulkSize: 本地队列可以达到的最大大小，在发送请求之前。如果<= 0，则没有批量机制，请求会立即发送。批量发送需要设置tokenAuth。tokenAuth: 用于认证API请求的32个字符授权密钥。我们建议创建一个用户专门用于访问跟踪API，并只给该用户写权限。headers: 要随请求一起发送的头部信息。persistentParameters: 自定义参数，每次调用都会发送。参见Matomo API文档。
跟踪
调用 track 静态方法来跟踪：
bool result = await MatomoForever.track(
actionName,
url: url,
rand: rand,
urlRef: urlRef,
cvar: cvar,
idVc: idVc,
viewTs: viewTs,
idTs: idTs,
rcn: rcn,
rck: rck,
res: res,
h: h,
m: m,
s: s,
fla: fla,
java: java,
dir: dir,
qt: qt,
realp: realp,
pdf: pdf,
wma: wma,
gears: gears,
ag: ag,
cookie: cookie,
ua: ua,
lang: lang,
uid: uid,
cid: cid,
newVisit: newVisit,
dimension0: dimension0,
dimension1: dimension1,
dimension2: dimension2,
dimension3: dimension3,
dimension4: dimension4,
dimension5: dimension5,
dimension6: dimension6,
dimension7: dimension7,
dimension8: dimension8,
dimension9: dimension9,
dimension10: dimension10,
link: link,
download: download,
search: search,
searchCat: searchCat,
searchCount: searchCount,
pvId: pvId,
idGoal: idGoal,
revenue: revenue,
gtMs: gtMs,
cs: cs,
ca: ca,
pfNet: pfNet,
pfSrv: pfSrv,
pfTfr: pfTfr,
pfDm1: pfDm1,
pfDm2: pfDm2,
pfOnl: pfOnl,
eC: eC,
eA: eA,
eN: eN,
eV: eV,
cN: cN,
cP: cP,
cT: cT,
cId: cId,
ecId: ecId,
ecItems: ecItems,
ecSt: ecSt,
ecTx: ecTx,
ecSh: ecSh,
ecDt: ecDt,
ects: ects,
cip: cip,
cdt: cdt,
country: country,
region: region,
city: city,
lat: lat,
long: long,
maId: maId,
maRe: maRe,
maMt: maMt,
maTi: maTi,
maPn: maPn,
maSt: maSt,
maLe: maLe,
maPs: maPs,
maTtp: maTtp,
maW: maW,
maH: maH,
maFs: maFs,
maSe: maSe,
customData: customData,
);
其中：
actionName: 被跟踪的操作的标题。可以使用斜杠/来设置一个或多个类别。例如，Help / Feedback将在类别Help中创建操作Feedback。url: 当前操作的完整URL。rand: 用于在每次请求前生成的随机值。使用它可以避免请求被浏览器或代理缓存。urlRef: 完整的HTTP引用URL。此值用于确定某人如何到达您的网站（例如，通过网站、搜索引擎或活动）。cvar: 访问或页面范围的自定义变量。这是一个JSON编码的自定义变量数组字符串。idVc: 此访客当前访问次数。要正确设置此值，需要在您的应用程序中存储每个访客的值（使用会话或持久化到数据库）。然后您需要手动递增每次新访问或“会话”的计数。viewTs: 此访客上次访问的UNIX时间戳。此参数用于填充报告Visitors > Engagement > Visits by days since last visit。idTs: 此访客首次访问的UNIX时间戳。可以设置为用户首次使用您的软件/应用或创建账户的日期。此参数用于填充报告Goals > Days to Conversion。rcn: 活动名称（参见跟踪活动）。用于填充报告Referrers > Campaigns。注意：此参数仅用于访问的第一个页面视图。rck: 活动关键字（参见跟踪活动）。用于填充报告Referrers > Campaigns（点击活动将加载所有关键字）。注意：此参数仅用于访问的第一个页面视图。res: 访客使用的设备分辨率，例如1280x1024。h: 当前小时（本地时间）。m: 当前分钟（本地时间）。s: 当前秒（本地时间）。fla: Flash插件。java: Java插件。dir: Director插件。qt: Quicktime插件。realp: Real Player插件。pdf: PDF插件。wma: Windows Media插件。gears: Gears插件。ag: Silverlight插件。cookie: 当设置为1时，表示访客的客户端支持Cookie。ua: 用于覆盖User-Agent HTTP头字段的值。用户代理用于检测操作系统和浏览器。lang: 用于覆盖Accept-Language HTTP头字段的值。此值用于检测访客的国家，如果未启用GeoIP。uid: 定义此请求的用户ID。用户ID是任何非空唯一字符串，用于标识用户（如电子邮件地址或用户名）。用户必须登录到您的系统才能访问此用户ID，然后将其传递给Matomo。用户ID出现在访问日志、访客档案中，您可以根据一个或多个用户ID（userId段）对报告进行分段。当指定时，用户ID将被“强制执行”。这意味着如果没有最近的访问记录与此用户ID匹配，则将创建一个新的访问记录。如果在过去30分钟内找到具有您指定用户ID的访问记录，则将新的操作记录到此现有访问记录。cid: 定义此请求的访客ID。必须将其设置为恰好为16个字符的十六进制字符串（仅包含字符01234567890abcdefABCDEF）。我们建议使用uid而不是使用cid设置用户ID。newVisit: 如果设置为1，将强制为此操作创建新的访问。此功能也可在JavaScript中使用。dimension0到dimension999: 用于特定自定义维度ID的自定义维度值（需要Matomo 2.15.1 + 自定义维度插件，参见自定义维度指南）。如果自定义维度ID为2，则使用dimension2=dimensionValue发送此维度的值。配置的自定义维度必须在作用域为“访问”或“动作”范围内。link: 用户打开的外部URL。用于跟踪外部链接点击。我们建议同时设置url参数为相同的值。download: 用户下载的文件URL。用于跟踪下载。我们建议同时设置url参数为相同的值。search: 网站搜索关键词。当指定时，请求不会作为普通页面视图被跟踪，而是被跟踪为站点搜索请求。searchCat: 当搜索被指定时，您可以选择性地指定搜索类别。searchCount: 当搜索被指定时，我们还建议设置search_count为结果页上显示的搜索结果数量。当使用&search_count=0跟踪关键词时，它们将出现在“无结果搜索关键词”报告中。pvId: 接受一个六位字符的唯一ID，用于识别特定页面视图上执行的动作。当查看页面时，所有后续跟踪请求（如事件）在该页面视图期间应使用相同的页面视图ID。一旦查看了另一个页面，应生成新的唯一ID。使用[0-9a-Z]作为唯一ID的可能字符。idGoal: 如果指定，跟踪请求将触发与该ID对应的网站目标的转换。revenue: 由此目标转换产生的货币价值。只有在请求中指定了idgoal时才使用。也可以是电子商务订单的总金额（跟踪电子商务订单时需要）。gtMs: 服务器生成此操作所需的时间，以毫秒为单位。此值用于处理页面速度报告中的平均生成时间列，以及您的服务器的整体运行平均速度。注意：当使用JavaScript跟踪器时，此值设置为服务器生成响应的时间加上客户端下载响应的时间。cs: 被跟踪页面的字符集。如果发送到Matomo的数据编码方式与默认的UTF-8不同，请指定字符集。ca: 代表自定义操作。&ca=1可以可选地发送任何非页面视图的跟踪请求。例如，它可以与事件跟踪请求一起发送e_a=Action&e_c=Category&ca=1。其优点在于，如果您禁用了事件插件，则事件跟踪请求将被忽略，而如果没有设置该参数，即使不是页面视图，也将跟踪页面视图。更多背景信息请参阅 #16570。不要与ping=1的跟踪请求一起使用此参数。pfNet: 毫秒网络时间。连接到服务器所需的时间。pfSrv: 毫秒服务器时间。服务器生成页面所需的时间。pfTfr: 毫秒传输时间。浏览器从服务器下载响应所需的时间。pfDm1: 毫秒DOM处理时间。浏览器在完全接收响应后加载网页直到用户可以开始与其互动所需的时间。pfDm2: 毫秒DOM完成时间。浏览器加载媒体并执行侦听DOMContentLoaded事件的任何JavaScript代码所需的时间。pfOnl: 毫秒加载时间。浏览器执行等待window.load事件的JavaScript代码所需的时间。eC: 事件类别。不能为空（例如，Videos, Music, Games…）。eA: 事件操作。不能为空（例如，Play, Pause, Duration, Add Playlist, Downloaded, Clicked…）。eN: 事件名称（例如，电影名、歌曲名、文件名等）。eV: 事件值。必须是浮点数或整数值（数字），而不是字符串。cN: 内容名称。例如，‘Ad Foo Bar’。内容跟踪需要。cP: 实际内容片段。例如，图像、视频、音频或任何文本的路径。cT: 内容的目标。例如，着陆页的URL。cId: 与内容的交互名称。例如，‘click’。ecId: 电子商务订单的唯一字符串标识符（跟踪电子商务订单时需要）。必须设置idgoal=0。ecItems: 电子商务订单中的商品。这是一个JSON编码的商品数组。每个商品是一个数组，按以下顺序包含以下信息：商品SKU（必需）、商品名称（如果不可用，则设置为空字符串）、商品类别（如果不可用，则设置为空字符串）、商品价格（如果不可用，则设置为0）、商品数量（如果不可用，则设置为1）。例如，ec_items的值可以是：%5B%5B%22item1 SKU%22,%22item1 name%22,%22item1 category%22,11.1111,2%5D,%5B%22item2 SKU%22,%22item2 name%22,,0,1%5D%5D（解码后的版本是：[["item1 SKU","item1 name","item1 category",11.1111,2],[["item2 SKU","item2 name","",0,1]]]）。ecSt: 订单的子总额；不包括运费。ecTx: 订单的税额。ecSh: 订单的运费。ecDt: 订单提供的折扣。ects: 此客户的最后一个电子商务订单的UNIX时间戳。此值用于处理“天数以来的最后一次订单”报告。cip: 访客IP的覆盖值（支持IPv4和IPv6表示法）。cdt: 请求日期时间的覆盖值（通常使用当前时间）。这可用于记录过去日期的访问和页面视图。期望格式为：2011-04-05 00:11:42（记住要URL编码值！），或者有效的UNIX时间戳1301919102。日期时间必须以UTC时区发送。注意：如果你记录过去的日期数据，你需要强迫Matomo重新处理过去的日期报告。如果设置cdt为超过24小时的日期时间，则需要设置token_auth。如果设置cdt为最后24小时内的日期时间，则无需传递token_auth。country: 国家的覆盖值。应该设置为访客的两个字母国家代码（小写），例如fr,de,us。region: 地区的覆盖值。应该设置为MaxMind的和DB-IP的GeoIP2数据库使用的ISO 3166-2地区代码。参见每国的列表。city: 城市的覆盖值。访客所在的城市名称，例如东京。lat: 访客纬度的覆盖值，例如22.456。long: 访客经度的覆盖值，例如22.456。maId: (必需) 在播放媒体期间始终相同的唯一ID。只要播放的媒体发生变化（新的视频或音频开始），此ID必须改变。maRe: (必需) 媒体资源的URL。maMt: 视频或音频，取决于媒体类型。maTi: 媒体的名称/标题。maPn: 媒体播放器的名称，例如html5。maSt: 用户观看此媒体的时间（秒）。这个数字通常会在发送媒体跟踪请求时增加。如果媒体仅可见/印象但未播放，则应设置为0。不要在媒体暂停时增加此数字。maLe: 媒体的持续时间（长度）（秒）。例如，如果视频长度为90秒，则值应为90。maPs: 媒体中的进度/当前位置。基本上定义了用户在总长度中当前正在播放的位置。maTtp: 用户开始播放此媒体所需的秒数。例如，用户可能会在看到视频海报30秒后按下播放按钮。maW: 媒体的分辨率宽度（像素）。仅推荐为视频设置。maH: 媒体的分辨率高度（像素）。仅推荐为视频设置。maFs: 应该为0或1，并定义媒体是否当前处于全屏模式。仅推荐为视频设置。maSe: 可选的逗号分隔列表，表示用户在媒体中播放的位置。例如，如果用户观看了5秒、10秒、15秒和35秒，则需要发送5,10,15,35。我们建议四舍五入到最接近的5秒，不要为每一秒发送值。内部，Matomo可能会四舍五入到最接近的15秒或30秒。为了性能优化，我们建议不要发送相同的两次位置。也就是说，如果你已经发送了ma_se=10，则无需再次发送ma_se=10,20，而只需发送ma_se=20。customData: 需要发送到Matomo服务器的其他数据。
发送数据
除了调用 track 方法之外，还可以调用 sendDataOrBulk 方法，该方法接受一个更简单的 Map 作为参数。
bool result = await MatomoForever.sendDataOrBulk(
addedData,
);
其中：
addedData: 需要添加到初始化数据的数据。
发送批量数据
当发送批量数据（bulkSize > 0）时，可以调用 sendQueue 方法来推送批量数据：
bool result = await MatomoForever.sendQueue();
权限
与Matomo服务器通信需要互联网访问，特别是在Android和MacOS上。
Android权限
在 android/app/src/main/AndroidManifest.xml 中添加以下权限：
<uses-permission android:name="android.permission.INTERNET" />
MacOS权限
在 macos/Runner/DebugProfile.entitlements 和 macos/Runner/Release.entitlements 文件中添加以下权限：
<key>com.apple.security.network.client</key>
<true/>
更多关于Flutter数据分析与跟踪插件matomo_forever的使用的实战教程也可以访问 https://www.itying.com/category-92-b0.html
