Telerik Analytics for NativeScript 插件

入门指南
API 参考
故障排除

入门指南

获取 AppId

在 Telerik 平台中创建一个新应用，通过选择原生应用类型来创建新应用。
启用分析

从左侧导航菜单中选择分析，然后点击 启用分析。
创建一个新的 NativeScript 应用
```
 tns create MyApp
```
或使用现有的一个。
将分析插件（从 npm）添加到应用中。这将将在项目根目录下的 node_modules 中安装 nativescript-telerik-analytics 插件。在添加新平台（或使用现有平台）时，该插件也将被添加到那里。转到应用文件夹并添加分析插件
```
 tns plugin add nativescript-telerik-analytics
```
转到应用文件夹并将 Android（或 iOS）平台添加到应用中
```
 tns platform add android
```

在 onLaunch 事件（app.js）中初始化插件并开始一个新会话

var application = require('application');
application.mainModule = 'main-page';
application.cssFile = './app.css';

application.on(application.launchEvent, function(context) {
    var Analytics = require('nativescript-telerik-analytics');
    Analytics.init({ appId: 'oamq6lixk0rak4dl' });
    Analytics.start();
});

application.start();

跟踪应用中的某些事件

var Analytics = require('nativescript-telerik-analytics'),
    timer = require('timer');

Analytics.trackEvent('MyCategory.MyEvent');

Analytics.trackValue('myvalue', 245);

var timingScope = Analytics.trackTimingStart('mytiming');
timer.setTimeout(function() {
    timingScope.stop(); // or timingScope.cancel(); if you want to ignore the timing
}, 3500);

Analytics.trackTimingRaw('myrawtiming', 1300); // track timing of 1300 ms

try {
    throw new Error('error message');
} catch (e) {
    Analytics.trackException(e, 'some error context');
}

将手机连接到电脑，确保 adb devices 命令列出它，并在手机上运行应用
```
 tns run android
```

API

要使用分析插件，您需要引入 nativescript-telerik-analytics 模块

var Analytics = require('nativescript-telerik-analytics');

然后调用它上的任何可用方法

init(settings) - 用于使用不同的配置选项初始化插件。在开始新会话或跟踪事件之前必须调用此方法。这是需要调用的第一个方法。

var settings = {
    appId: 'oamq6lixk0rak4dl', // Required identifier of the application obtained in Telerik Platform
    productVersion: '1.2.3.4', // Optional - the version of the monitored application
    location: { // optionally associate some geo location coordinates with the user 
        latitude: 40.719618,
        longitude: -74.010282
    },
    clientIP: '193.42.34.123', // optionally override the IP of the user
    isInternalData: false, // Optional flag allowing to enable test mode for this session. This will mark all events tracked in this particular session as "Internal"
    autoTrackUnhandledExceptions: false, // Optionally turn off automatic exception handling. The default value is true. The plugin subscribes to the "application.uncaughtErrorEvent" and automatically tracks the exception
    logger: new MyLogger() // Optionally specify a custom logger. This should be an instance of a class with info(message, obj) and error(message, obj) functions.
};
Analytics.init(settings);

start() - 开始新的分析会话。在调用此方法之前，需要使用 init 方法初始化 SDK。
```
Analytics.start();
```
trackEvent(name) - 注册功能使用。建议使用简单的点表示法对相关功能进行分组，例如将打印与 pdf 和文件打印分别命名为 "print.pdf" 和 "print.file"。
```
Analytics.trackEvent('Printing.PDF');
```
trackValue(name, value) - 在特定功能上注册一个值。虽然对 trackEvent 的调用会增加会话中功能的使用次数，但对此方法的调用将一个给定的值与一个命名的功能相关联。例如，使用此方法跟踪导入的文件大小分布或注册的结果数量。跨所有应用使用情况跟踪此分布将提供有关您的应用程序处理哪些场景的见解。值参数必须是一个有效的整数。
```
Analytics.trackValue('FilesProcessed', 152);
```
trackException(e, context) - 调用以跟踪应用程序中发生的异常。可以与异常关联一个可选的上下文字符串。
```
try {
    throw new Error('error message');
} catch (e) {
    Analytics.trackException(e, 'some optional context');
}
```

trackTimingStart(name) - 开始一个名为计时器，用于测量操作经过的时间，并返回一个范围，可用于停止或取消计时操作。

var timer = require('timer'),
    timingScope = Analytics.trackTimingStart('MyTiming');
timer.setTimeout(function() {
    timingScope.stop(); // at this stage the timer will be stopped and the elapsed time submitted to Analytics in milliseconds. You can abort the timing operation by calling timingScope.cancel();  
}, 1450);

trackTimingRaw(name, durationInMilliseconds) - 使用其他方法测量的经过时间进行注册。
```
Analytics.trackTimingRaw('MyTiming', 563);
```

故障排除

如果应用不符合预期，以下是一些您可以验证的事项

对于 Android，确保位于 platforms\android 的 AndroindManifest.xml 包含以下权限
```
<uses-permission android:name="android.permission.INTERNET"/>
```

启用日志记录以查看是否有信息或错误消息被记录。您可以通过编写以下模块（mylogger.js）来启用日志记录：

(function(global) {
    var MyLogger = function() {
    };

    exports = module.exports = MyLogger;

    MyLogger.prototype.info = function(message, obj) {
        console.log('INFO: ' + message + (obj ? ' : ' + JSON.stringify(obj) : ''));
    };

    MyLogger.prototype.error = function(message, obj) {
        if (obj instanceof Error) {
            console.log('ERROR: ' + message + (obj ? ' : ' + obj.message : ''));
        } else {
            console.log('ERROR: ' + message + (obj ? ' : ' + JSON.stringify(obj) : ''));
        }
    };
}(this || global));

并在初始化插件时设置此记录器

var Analytics = require('nativescript-telerik-analytics'),
    MyLogger  = require('./mylogger');

Analytics.init({
    appId : 'oamq6lixk0rak4dl',
    logger: new MyLogger()
});