jKool 对于 iOS 的跟踪 API

欢迎使用 jKool Tracking API for iOS。通过将此 Pod 导入您的应用程序并在您的 AppDelegate 中添加几行代码，用户的体验将被自动流式传输到您的 jKool 存储库。有了 jKool 订阅，您就可以查看有关用户的应用程序体验的数据。如果您没有 jKool 账户，您可以免费注册。由于对数据的图形表示，jKool 用户界面使得查看数据直观且易于理解。此外，使用 JKQL 查询语言，您可以使用类似英语的查询来查询和分析您的数据，以满足您的喜好。此 pod 会将用户的点击和访问的屏幕作为“事件”流式传输。它将用户整个会话的信息作为“活动”流式传输。请参阅下文了解更多有关数据结构的信息。

此 pod 利用 jKool Client API for iOS。jKool Client API 允许您流式传输、查询并订阅 jKool 数据。使用此 API，您可以流式传输自己的自定义数据，查询自己的自定义数据，并订阅自己的自定义数据。因此，通过导入跟踪 Cocoa Pod，您还将获得对客户端 API Cocoa Pod 的访问权限。请阅读有关 jKool Client API 的更多信息。

示例

要运行示例项目，请克隆仓库，然后首先从 Example 目录运行 pod install

作者

jKool LLC

许可

请参阅 LICENSE 文件。

开始

通过以下方式在您的 Podfile 中包含此 API

pod 'jkool-client-objc-tracking'

为 Swift 创建桥接头

如果您希望此 CocoaPod 在 Swift 应用程序中工作，您只需创建一个 Bridge.m 文件并包含以下头文件。当创建 Bridge.m 时，选择“创建桥接头”的选项。本 ReadMe 中的代码示例在 Swift 和 Objective-c 中都有。

#import "jKoolTracking.h"
#import "jKoolData.h"

添加到AppDelegate

要使追踪功能正常运行，请将以下代码添加到您的AppDelegate中。请注意，当您注册jKool时，您将获得'token-your'。

要为applicationDidBecomeActive和applicationWillEnterForeground添加

Obj-c

[jKoolTracking createjKoolActivity];

Swift

jKoolTracking.createjKoolActivity();

要添加到applicationDidEnterBackground

Obj-c

[jKoolTracking streamjKoolActivity];

Swift

jKoolTracking.streamjKoolActivity();

要添加到didFinishLaunchingWithOptions

Obj-c

[jKoolTracking initializeTracking:@"your-token" enableErrors:<YES/NO> enableActions:<YES/NO> onlyIfWifi:<YES/NO>];

Swift

jKoolTracking.initializeTracking("your-token", enableErrors:<true/false>, enableActions:<true/false>, onlyIfWifi:<true/false>, tagToViewName:nil]; // see below how to use a tagToViewName parameter.

其中

• enableErrors - 将启用或禁用未捕获异常的流式传输
• enableActions - 将启用或禁用操作的流式传输
• onlyIfWifi - 根据Wi-Fi是否可用来启用或禁用流式传输
• tagToViewName - 指定您希望跟踪的触摸（请参阅下文“跟踪用户点击”）

流式传输崩溃（可选）

如果您希望流式传输未捕获的错误异常，可以通过将以下代码添加到AppDelegate的未捕获异常处理程序（即使您还没有一个，这里提供了一个完整的处理程序）轻松完成：

Obj-c

void onUnCaughtException (NSException *exception)
{
    [jKoolTracking jKoolExceptionHandler:exception];
    // Sleeping is necessary to give it time to streaam.
    [NSThread sleepForTimeInterval:5.0f];
}... 

在didFinishLaunchWithOptions中包含以下内容

NSSetUncaughtExceptionHandler(&onUncaughtException);

Swift

在didFinishLaunchWithOptions中包含以下内容

NSSetUncaughtExceptionHandler
        {
            exception in
            jKoolTracking.jKoolExceptionHandler(exception);
            // Sleeping is necessary to give it time to stream.
            sleep(5);
        }

自定义字段（可选）

某些通常具有默认值的字段可以用您自己的自定义数据覆盖。要设置这些字段，请将以下方法调用添加到didFinishLaunchingWithOptions

Obj-c

[jKoolTracking setCustomApplicationName:@"<your-application-name>" andDataCenter:@"<your-data-center>" andResource:@"<your-activity-resource>" andSsn:<your-source> andCorrelators:[NSArray arrayWithObjects:@"<your-custom-correlator>",@"<your-custom-correlator>",..., nil] andActivityName:@"<your-activity-name>"];

Swift

let corrs : Array = ["<your-custom-correlator>","<your-custom-correlator>","<your-custom-correlator> ..."];
jKoolTracking.setCustomApplicationName("<your-application-name>", andDataCenter:"<your-data-center>", andResource:"<your-activity-resource>", andSsn:<your-source>, andCorrelators:corrs,@"<your-custom-correlator>",..., nil], andActivityName:"<your-activity-name>"];

跟踪用户点击

iOS动作和iOS触摸事件都可以作为用户点击进行跟踪。这可能是多余的，因为如果触摸事件关联了动作，则触摸事件会被报告两次，一次作为触摸事件和第二次作为动作。但是，并非所有触摸事件都会被报告，并且所有动作都会被报告。大多数触摸事件都与动作关联，因此默认情况下不会报告。此外，为了获取有关触摸事件的直观信息，开发者必须帮助API确定确切接触了什么。这是因为iOS并不提供直观命名的触摸事件。因此，为了解决触摸事件直观命名的问题，也为了解决当触摸事件也作为动作报告时的重复报告问题，API只报告在字典中指定的触摸事件。所以，如果您想报告触摸事件，请在AppDelegate didFinishLaunchingWithOptions中做以下操作：

• 在storyboard中，将每个要报告的触摸对象标记为唯一的标签号码。
• 创建一个NSDictionary（Objective-c）Dictionary（Swift），其键等于唯一标签，值是触摸对象的直观名称。
• 在initializeTracking方法中，将NSDictionary指定为tagToViewName参数。这样做将自动导致API报告您标记的对象的触摸事件。

查看结果

这个pod中有一个示例应用程序。它包含一个完整的工作应用程序，其中包含上述所有提到的代码。只需将“token-your”替换为您在注册jKool时分配的token。为了感受此跟踪API，我们建议您进行以下操作：

• 运行应用程序。
• 点击所有三个按钮。
• 导航到第二个屏幕。
• 点击第二个屏幕上的某些按钮。
• 退出应用程序。请注意，退出非常重要。只有当您的应用程序退出或推送到后台时，您的数据才会进入jKool仓库。
• 登录到您的jKool仓库查看流式传输的数据。只需使用“get events fields all”查看三个点击事件，用“get activites fields all”查看流式传输的活动。
• 运行应用并点击第二个屏幕上的“Crash Me”按钮，您可以看到错误正在输出。此按钮会导致未捕获的数组越界异常。

理解结果

以下列出了事件和活动字段以及存储在其中的数据。我们只列出对您跟踪感兴趣的字段。您可能还会注意到其他字段，如果您正在流您自己的自定义数据，则这些字段可能也会对您感兴趣。有关这些附加字段以及如何流自定义数据的信息，请参阅jKool客户端API和jKool模型指南。

事件字段

• EventId - 流出事件的唯一标识符。
• ParentId - 事件相关联的活动唯一标识符。
• EventName - 事件名称。这将是不具有触发名称的视图控制器名称。
• StartTime - 动作发生的时间。
• Tag - 执行动作的ViewController名称。
• 属性 - Event中的属性包含有关事件发生位置的详细信息。它将包含：城市名称、国家、州、时区、纬度和经度。
• GeoLocaton - 事件发生位置的GPS坐标。

活动字段

• 属性 - 描述位置信息（如事件属性）以及有关设备（如可用内存、iOS版本、电话运营商等）的信息。
• GeoLocaton - 事件发生位置的GPS坐标。
• EventId - 在活动期间发生的事件列表。
• StartTime - 活动开始的时间。这将是应用启动或出现在前台的时间。
• EndTime - 活动结束的时间。这将是应用被发送到后台的时间。

有关属性的特别说明

在正常通过jKool客户端API进行流式传输时，自定义用户字段存储在jKool '属性'中。这种跟踪API正在使用'属性'来存储描述性位置信息和存储有关用户设备的信息。有关查询属性的特殊语法，请参阅JKQL查询语言。

支持

如果您有任何问题或疑虑，请通过电子邮件联系我们 [email protected]。我们会尽快回复您。