PiwikTracker iOS SDK

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

想帮助改进此SDK？查看这个列表，看看还有什么可以改进。

安装

CocoaPods

在您的Podfile中使用以下内容。

pod 'PiwikTracker', '~> 4.4'

然后运行pod install。在每个需要使用PiwikTracker的文件中，别忘了使用import PiwikTracker导入框架。

用法

配置

在使用PiwikTracker之前，必须进行配置。最好在`AppDelegate`的`application(_:didFinishLaunchingWithOptions:)`方法中完成。

PiwikTracker.configureSharedInstance(withSiteID: "5", baseURL: URL(string: "http://your.server.org/path-to-piwik/piwik.php")!)

`siteId`是您在Piwik Web界面中添加网站后可以获得的一个ID。`baseURL`是您Piwik Web实例的URL，必须包含"piwik.php"字符串。

退出跟踪

PiwikTracker SDK支持退出跟踪。请使用PiwikTracker的`isOptedOut`属性来定义用户是否退出跟踪。

PiwikTracker.shared?.isOptedOut = true

跟踪页面视图

PiwikTracker可以跟踪层次结构的屏幕名称，例如screen/settings/register。使用此功能在Piwik Web界面中创建层次结构和逻辑的屏幕视图分组。

PiwikTracker.shared?.track(view: ["path","to","your","page"])

您也可以设置页面的URL。

let url = URL(string: "https://piwik.org/get-involved/")
PiwikTracker.shared?.track(view: ["community","get-involved"], url: url)

跟踪事件

事件可以用于跟踪用户交互，例如按钮的点击。事件由四个部分组成

• 类别
• 操作
• 名称（可选，推荐）
• 值（可选）

PiwikTracker.shared?.track(eventWithCategory: "player", action: "slide", name: "volume", value: 35.1)

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

自定义维度

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

之后您可以设置一个新的维度

PiwikTracker.shared?.set(value: "1.0.0-beta2", forIndex: 1)

或删除已经设置好的维度。

PiwikTracker.shared?.remove(dimensionAtIndex: 1)

访问范围的维度将随每个页面视图或事件一起发送。自定义维度不会由SDK持久存储，必须在应用启动时重新配置。

自定义用户ID

要添加自定义用户 ID，只需在共享 tracker 的 visitorId 字段设置您希望使用的值。

PiwikTracker.shared?.visitorId = "coolUsername123"

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

高级用法

手动调度

PiwikTracker 会自动每 30 秒调度一次事件。如果您想手动调度事件，可以使用 dispatch() 函数。例如，您可以在应用进入后台时进行调度。

func applicationDidEnterBackground(_ application: UIApplication) {
  PiwikTracker.shared?.dispatch()
}

会话管理

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

func applicationWillEnterForeground(_ application: UIApplication) {
  PiwikTracker.shared?.startNewSession()
}

日志记录

PiwikTracker 默认将 warning 和 error 消息记录到控制台。您可以根据需要更改 LogLevel。

PiwikTracker.shared?.logger = DefaultLogger(minLevel: .verbose)
PiwikTracker.shared?.logger = DefaultLogger(minLevel: .debug)
PiwikTracker.shared?.logger = DefaultLogger(minLevel: .info)
PiwikTracker.shared?.logger = DefaultLogger(minLevel: .warning)
PiwikTracker.shared?.logger = DefaultLogger(minLevel: .error)

您还可以编写自己的 Logger 并将日志发送到您想要的位置。只需编写一个新的类/结构，并让它符合 Logger 协议即可。

自定义用户代理

PiwikTracker 将创建一个默认的用户代理，该代理由 WKWebView 用户代理派生。
您可以使用自己的用户代理创建 PiwikTracker 实例。

PiwikTracker.configureSharedInstance(withSiteID: "5", baseURL: URL(string: "http://your.server.org/path-to-piwik/piwik.php")!, userAgent: "Your custom user agent")

Objective-C 兼容性

此 SDK 的第 4 版是用 Swift 编写的，但您也可以将其用于您的 Objective-C 项目。如果您不想更新，仍然可以使用不受支持的旧版本 3。从 Objective-C 使用 Swift SDK 应该非常直观。

[PiwikTracker configureSharedInstanceWithSiteID:@"5" baseURL:[NSURL URLWithString:@"http://your.server.org/path-to-piwik/piwik.php"] userAgent:nil];
[PiwikTracker shared] trackWithView:@[@"example"] url:nil];
[[PiwikTracker shared] trackWithEventWithCategory:@"category" action:@"action" name:nil number:nil];
[[PiwikTracker shared] dispatch];

发送自定义事件

您可以使用便利函数创建事件和屏幕视图，例如，您还可以手动创建事件，并发送自定义跟踪参数。此功能在 Objective-C 中不可用。

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

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

另外：您不能覆盖事件本身已定义的自定义参数键。如果将那些键设置为 customTrackingParameters，它们将被丢弃。

自动 URL 生成

您可以在每个 Event 上定义 URL 属性。如果没有定义，SDK 将尝试根据 PiwikTracker 的 contentBase 生成一个 URL。如果 contentBase 为 nil，则不会生成 URL。如果设置了 contentBase，则将其附加到事件的操作中，并用作 URL。默认情况下，使用应用包标识符生成 contentBase，例如 http://org.piwik.skd。这不会生成可解析的 URL，但允许后端对其进行分析和结构化。

贡献

有关详细信息，请阅读 CONTRIBUTING.md。

待办事项

这些功能尚未实现

• 基本功能
  • 持久化未调度的事件
  • 自定义维度（操作范围尚未实现）
• 跟踪更多内容
  • 异常
  • 社交交互
  • 搜索
  • 目标和转化
  • 出链
  • 下载
  • 电子商务交易
  • 活动
  • 内容印象/内容交互
• 自定义追踪器
  • 添加前缀？（objc-SDK 具有前缀功能）
  • 设置调度间隔
  • 使用不同的调度器（Alamofire）

许可证

Pywikitracker遵循MIT许可证提供。