MatomoTracker 7.6.0

MatomoTracker 7.6.0

×

由 Cornelius Horstmann 维护。

MatomoTracker 7.6.0

  • 作者
  • Mattias Levin 和 Cornelius Horstmann

MatomoTracker（前 PiwikTracker）iOS SDK

MatomoTracker 是一个 iOS、tvOS 和 macOS SDK，用于将应用分析数据发送到 Matomo 服务器。MatomoTracker 可以使用 Swift 和 Objective-C 来使用。

想要帮忙改进这个 SDK 吗？查看 该列表 来查看还有哪些可以改进的地方。

安装

MatomoTracker 可以通过 CocoaPods、Carthage 和 Swift 包管理器进行安装。在您想使用 MatomoTracker 的每个文件中，不要忘记使用 import MatomoTracker 语句导入框架。

CocoaPods

在您的 Podfile 中使用以下命令。

pod 'MatomoTracker', '~> 7.5'

然后运行 pod install

Carthage

Carthage 是将 MatomoTracker 安装到项目中的一种无侵入方式。它对您的 Xcode 项目和工作区不进行任何修改。将以下内容添加到您的 Cartfile 中

github "matomo-org/matomo-sdk-ios"
Swift 包管理器

您可以使用 Swift 包管理器作为集成方法。如果您想使用 Swift 包管理器作为集成方法，可以使用 Xcode 添加包依赖项，或在您的 Package.swift 中添加以下依赖项

.package(url: "https://github.com/matomo-org/matomo-sdk-ios.git", from: "v7.5"),

使用方法

Matomo 实例

Matomo iOS SDK 不提供 PiwikTracker 的实例。要能够跟踪数据，您首先需要创建一个实例。

let matomoTracker = MatomoTracker(siteId: "23", baseURL: URL(string: "https://demo2.matomo.org/piwik.php")!)

siteId 是您在 Matomo 网页界面中添加网站时可以获取的 ID。而 baseURL 是您的 Matomo 网页实例的 URL，并且必须包含 "piwik.php" 或 "matomo.php" 字符串。

您可以将这个实例传递，或者向 MatomoTracker 类添加一个扩展，并添加一个共享的实例属性。

extension MatomoTracker {
    static let shared: MatomoTracker = MatomoTracker(siteId: "1", baseURL: URL(string: "https://example.com/piwik.php")!)
}

siteId 是您在 Matomo 网页界面中添加网站时可以获取的 ID。而 baseURL 是您的 Matomo 网页实例的 URL，并且必须包含 "piwik.php" 或 "matomo.php" 字符串。

您可以在一个应用中使用多个实例。

选择退出

MatomoTracker SDK 支持选择退出跟踪。请使用 MatomoTracker 的 isOptedOut 属性来定义用户是否选择了退出跟踪。

matomoTracker.isOptedOut = true

跟踪页面浏览量

MatomoTracker 可以跟踪分层屏幕名称，例如 screen/settings/register。使用此方法在 Matomo 网页界面中创建层次化和逻辑分组屏幕查看。

matomoTracker.track(view: ["path","to","your","page"])

您也可以设置页面的 URL。

let url = URL(string: "https://matomo.org/get-involved/")
matomoTracker.track(view: ["community","get-involved"], url: url)

跟踪事件

事件可以用来跟踪用户交互，例如按钮的点击。事件包括四个部分：

  • 类别
  • 操作
  • 名称（可选，推荐）
  • 值（可选）
matomoTracker.track(eventWithCategory: "player", action: "slide", name: "volume", value: 35.1)

这将记录用户将播放器的音量滑块滑动到 35.1%。

跟踪搜索

MatomoTracker 可以跟踪用户如何使用您应用内的搜索。您可以跟踪搜索的关键词、他们使用的分类、某个搜索的结果数量以及没有结果的搜索。

matomoTracker.trackSearch(query: "Best mobile tracking", category: "Technology", resultCount: 15)

自定义维度

Matomo SDK 目前支持访问范围的“自定义维度”。使用自定义维度，您可以向整个访问添加属性，例如“用户是否完成了教程？”、“用户是否是付费用户？”或“正在使用应用程序的哪个版本？”等等。在发送自定义维度之前，请确保自定义维度已经正确安装和配置。您需要配置的维度 ID。

然后您可以为新的维度设置， 

matomoTracker.set(value: "1.0.0-beta2", forIndex: 1)

或移除已经设置的维度。

matomoTracker.remove(dimensionAtIndex: 1)

访问范围内的维度将随每次页面查看或事件一同发送。自定义维度不会由 SDK 缓存，必须在应用启动时重新配置。

自定义用户 ID

要添加一个 自定义用户 ID，只需设置您想使用的值在 tracker 的 userId 字段

matomoTracker.userId = "coolUsername123"

SDK 将追踪所有未来事件都将与此 userID 关联，而不是每个访问者默认创建的 UUID。

自定义访问者 ID 在应用启动时持久存储

MatomoTracker 首次使用时会生成一个 _id，并将使用此值来识别当前访问者。此 _id 将在应用启动时持久存储。

如果您要设置自己的访客ID，可以通过forcedVisitorId字段来设置。确保您使用16位长度的十六进制字符串。forcedVisitorId将在应用程序启动时持久保持。

matomoTracker.forcedVisitorId = "0123456789abcdef"

因为SDK在应用程序启动时持久化此访客ID，所以我们建议在跟踪您的应用程序用户之前先询问用户同意。

活动跟踪

Matomo iOS SDK支持活动跟踪。

matomoTracker.trackCampaign(name: "campaign_name", keyword: "campaign_keyword")

内容跟踪

Matomo iOS SDK支持内容跟踪。

matomoTracker.trackContentImpression(name: "preview-liveaboard", piece: "Malaysia", target: "https://dummy.matomo.org/liveaboard/malaysia")
matomoTracker.trackContentInteraction(name: "preview-liveaboard", interaction: "tap", piece: "Malaysia", target: "https://dummy.matomo.org/liveaboard/malaysia")

目标跟踪

Matomo iOS SDK支持目标跟踪。

matomoTracker.trackGoal(id: 1, revenue: 99.99)

订单跟踪

Matomo iOS SDK支持订单跟踪。

let items = [
  OrderItem(sku: "product_sku_1", name: "iPhone Xs", category: "phone", price: 999.99, quantity: 1),
  OrderItem(sku: "product_sku_2", name: "iPhone Xs Max", category: "phone", price: 1199.99, quantity: 1)
]

matomoTracker.trackOrder(id: "order_id_1234", items: items, revenue: 2199.98, subTotal: 2000, tax: 190.98, shippingCost: 9)

高级使用方法

手动触发

MatomoTracker会每30秒自动触发事件。如果您想手动触发事件，可以使用dispatch()函数。

会话管理

MatomoTracker在应用程序启动时开始一个新会话。如果您想手动开始一个新的会话，可以使用startNewSession()函数。例如，当用户进入应用程序时，您可以开始一个新会话。

func applicationWillEnterForeground(_ application: UIApplication) {
  matomoTracker.startNewSession()
}

日志记录

默认情况下，MatomoTracker会将warning和error消息记录到控制台。您可以通过修改LogLevel来更改日志级别。

matomoTracker.logger = DefaultLogger(minLevel: .verbose)
matomoTracker.logger = DefaultLogger(minLevel: .debug)
matomoTracker.logger = DefaultLogger(minLevel: .info)
matomoTracker.logger = DefaultLogger(minLevel: .warning)
matomoTracker.logger = DefaultLogger(minLevel: .error)

您也可以编写自己的Logger并将日志发送到您想要的地方。只需编写一个新类/结构体并让它符合Logger协议。

自定义用户代理

MatomoTracker会根据WKWebView用户代理创建一个默认用户代理。您可以使用您自己的用户代理来实例化MatomoTracker。

let matomoTracker = MatomoTracker(siteId: "5", baseURL: URL(string: "http://your.server.org/path-to-matomo/piwik.php")!, userAgent: "Your custom user agent")

发送自定义事件

您可以使用自定义函数来手动创建事件和屏幕视图，而不是使用事件和屏幕视图的便捷函数。您甚至可以发送自定义跟踪参数。此功能从Objective-C中不可用。

func sendCustomEvent() {
  guard let matomoTracker = MatomoTracker.shared else { return }
  let downloadURL = URL(string: "https://builds.matomo.org/piwik.zip")!
  let event = Event(tracker: matomoTracker, action: ["menu", "custom tracking parameters"], url: downloadURL, customTrackingParameters: ["download": downloadURL.absoluteString])
  matomoTracker.track(event)
}

所有自定义事件都将通过URL编码并与默认事件参数一起分发。请阅读跟踪API文档了解更多信息，包括哪些参数可以使用。

另外：您不能覆盖事件本身已定义的自定义参数键。如果将这些键设置在customTrackingParameters中，它们将被忽略。

自动URL生成

您可以为每个Event定义url属性。如果没有定义，SDK将尝试根据MatomoTracker的contentBase生成URL。如果contentBase为空，则不会生成URL。如果设置了contentBase，它将向其中添加事件的操作，并使用它作为URL。默认情况下，使用应用包标识符生成contentBase。例如http://org.matomo.skd。这将不会产生可解析的URL，但可以允许后端分析和结构化它们。

事件分派

只要您跟踪事件或页面浏览，它首先存储在内存中。在每个分派运行中，将发送一批这些事件到服务器。如果设备离线或服务器无响应，这些事件将被保留并在以后重发。目前事件未存储在磁盘上，如果应用程序终止，则将会丢失。#137

贡献

请阅读CONTRIBUTING.md以获取详细信息。

授权

MatomoTracker在MIT许可证下可用。