JustTrack

Just Eat解决iOS上更好地管理分析跟踪并与您的BI团队建立更好关系的方案。

• Just Eat Tech博客

概览

在 Just Eat，跟踪事件是我们业务分析的基础，我们收集的信息为我们提供了技术决策和战略决策。为了收集所需的信息，我们需要一个灵活、面向未来的和易于使用的跟踪系统，使我们能够在对应用程序代码影响最小的情况下添加、删除和交换与分析系统和服务的底层集成。我们还希望解决要求改变时保持所需事件元数据更新的问题。

JustTrack 是我们为此构建的事件跟踪解决方案。

对于任何功能请求、错误报告或问题，请使用 问题 页面和适当的 标签。

功能

• 事件 在 .plist 文件中声明，并在构建时从它自动生成 Swift 代码。
• 事件可以同时发送到多个目的地（称为 追踪器）。
• 自定义 追踪器 易于创建和使用。

安装

JustTrack 通过 CocoaPods 提供。要安装，只需将以下行添加到你的 Podfile 中

pod "JustTrack"

按照如下方式将库导入到你的文件中

// swift
import JustTrack

// Objective-C
@import JustTrack;

在你的目标 构建阶段 中添加以下脚本

xcrun --sdk macosx swift "${PODS_ROOT}/../../JustTrack/EventsGenerator/main.swift" "${SRCROOT}/JustTrack/Events.plist" "${SRCROOT}/JustTrack/TrackingEvents.swift"

Objective C (版本 перед 4.0)

xcrun --sdk macosx swift "${PODS_ROOT}/../../JustTrack/JEEventsGenerator/main.swift" "${SRCROOT}/JustTrack/Events.plist" "${SRCROOT}/JustTrack/TrackingEvents.swift"

位置

• ${SRCROOT}/JustTrack/Events.plist 是你的事件声明 plist 文件的路径，可以在项目的任何地方。
• "${SRCROOT}/JustTrack/TrackingEvents.swift" 是自动生成的 Swift 代码的目标文件。

注意： 给这个脚本一个有意义的名称（例如：“名称：JustTrack 事件生成”）

使用方法

让我们看看如何使用 JustTrack

JustTrack 配置

Swift

func configureJustTrack() -> EventTracking {
    // configure the tracking Singleton with settings and trackers
    
    let eventTracker: EventTracking = EventTracking.sharedInstance
    eventTracker.deliveryType = .batch
    
    eventTracker.logClosure = { (logString: String, logLevel: TrackingLogLevel) -> Void in
        print("[EventTracker] [\(logLevel.rawValue)] \(logString)")
    }
    
    // load the default tracker, in this case the console tracker
    
    eventTracker.loadDefaultTracker(.consoleLogger)
    
    //enable JustTrack
    eventTracker.enable()
    
    return eventTracker
}

事件定义

我们发现在现有的解决方案中，事件是在代码中声明的，因此只能由开发人员维护。同样，现有的解决方案为开发人员提供了非常通用的跟踪功能。正因为如此，当任何原因导致与事件关联的元数据发生变化时，开发人员必须搜索整个代码库并更新事件的所有实例以实现正确的实现。这当然是一个非常脆弱的过程，容易出错。

JustTrack通过在plist文件中声明事件来试图解决这些问题，该文件用于自动生成在Swift中可以使用的事件的等效定义。这带来了以下几点益处：

• 每个事件都是唯一标识的
• 每个事件的相关元数据都经过类型检查
• 当事件的需求发生变化时，开发者可以通过自然出现的项目构建错误和警告来查看
• Plist可以像XML一样进行编辑，这意味着业务中的任何人都可以编辑它们
• 可以轻松搜索不再使用的事件，并且删除的事件无法编译

事件的结构

事件由以下部分组成：

• 名称：唯一的标识符
• 已注册的追踪器：事件的接收列表（例如，谷歌分析）
• 负载：与事件关联的元数据（目前只支持字符串键值对）

Plist格式

<key>User</key>
<dict>
    <key>registeredTrackers</key>
    <array>
        <string>console</string>
        <string>Firebase</string>
    </array>
    <key>payloadKeys</key>
    <array>
        <string>action</string>
        <string>response</string>
        <string>extra</string>
    </array>
</dict>

生成的Swift类

public class EventUser: NSObject, Event {
    public let name: String = "User"

    public var payload: Payload {
        return [
            kAction: action == "" ? NSNull() : action as NSString, 
            kResponse: response == "" ? NSNull() : response as NSString, 
            kExtra: extra == "" ? NSNull() : extra as NSString
        ]
    }

    public var registeredTrackers: [String] {
        return ["console", "Firebase"]
    }

    private let kAction = "action"
    private let kResponse = "response"
    private let kExtra = "extra"

    public var action: String = ""
    public var response: String = ""
    public var extra: String = ""

    public init(action: String,
                response: String,
                extra: String) {
        super.init()
        self.action = action
        self.response = response
        self.extra = extra
    }
}

使用事件

//Swift
let trackingService: EventTracking = configureJustTrack()
trackingService.trackEvent(EventUser(action: "UserLogIn", response: "success", extra: "Additional info"))

//Objective-C
JETracking *trackingService =  [self configureJustTrack];
[trackingService trackEvent:[[JEEventUser alloc] initWithAction:@"UserLogIn" response:@"success" extra:@"Additional info"] ];

硬编码的事件

您还可以通过实现事件协议来创建“硬编码”的事件。但我们强烈建议您专用地使用plist文件。

追踪器

追踪器是一个实现了追踪器协议的对象，并通过tracker.loadCustomTracker( ... )函数加载。您可以根据需要实现任何追踪器，“JustTrack”提供了一些默认追踪器。

• 追踪器控制台 - 将事件打印到系统的控制台
• Facebook追踪器（尚未实现）
• GoogleAnalytics追踪器（尚未实现，Google的Pod不能作为库依赖项使用）
• TrakerFirebase（尚未实现，Google的Pod不能作为库依赖项使用）

升级到v4.0

在版本4.0中，JustTrack已重构以符合当前的Swift标准。因此，JustTrack不再支持Objective-C实现。请更新任何使用此功能的应用程序。因此，事件命名的以及调用方式已发生重大调整。升级时请考虑以下要点。

采用Swift

这次对JustTrack的更新去除了Objective-C属性和前缀，使实现符合Swift标准，同时移除了Objective-C的互操作性。

例如，之前定义的事件类现在是

JEEventUser

现在采用命名方案

EventUser

这种变化对您预先定义事件的 影响，可以在生成的TrackingEvents.swift文件中确定。

请注意，任何采用此版本的程序都需要采用这个新的命名方案。

更新的命名

事件和相关有效负载的命名也进行了调整，以确保遵守camelCase命名约定。

跨运行保持顺序

版本4.0中的另一个更改是保持自动生成的TrackingEvents.swift文件中的顺序。这在进行更改比较时提供了更大的清晰度。

促进对象数组

JustTrack现在允许实现包含在有效负载中的对象数组。为了实现此类事件，请创建一个新的字典类型项，并按照示例事件中详细说明的objectPayloadKeys表示遵守。对象数组也支持不同数据类型。要将其添加到您的对象数组中，只需将变量类型附加到值末尾即可，如下所示：

整数

itemNumber_int

双精度浮点数

itemPrice_double

布尔值

itemAvailable_bool

升级到v3.0

在JustTrack的3.0版本中，已从JETracker协议中删除了Configuration类。

如果您的客户端代码使用Objective-C，则在升级时您的代码应继续按原样运行。

如果您的客户端代码使用Swift，那么您有两个选择。

选项1)升级到SDK的3.0版本的最简单方法是在客户端代码中重新引入Configuration typealias，如下所示

public typealias Configuration = [String : String]

选项2)用等效方式替换您的初始化方法。例如，这个旧的init方法...

public init(configuration: Configuration) {
    super.init()
    self.token = conifiguration[TokenKey]
}

可能成为...

public init(token: String) {
    super.init()
    self.token = token
}

许可证

JustTrack在Apache License, Version 2.0下提供。有关更多信息，请参阅LICENSE文件。

• Just Eat iOS团队