@nstudio/nativescript-dynatrace

npm install @nstudio/nativescript-dynatrace

使用方法

手动启动 OneAgent

如果您无法通过 dynatrace.config.js 进行自动化启动，您始终可以进行手动启动，并在运行时决定 beaconUrl 和 applicationId 等值。

注意：自动化启动通常为您提供一个应用程序启动生命周期事件。另一方面，手动启动较晚发生，因此您可能会错过包括此应用程序启动事件在内的所有内容，直到启动发生。

手动启动需要以下两个步骤

在 dynatrace.config.js 中禁用自动化启动

module.exports = {
	android: {
		config: 'dynatrace { configurations { defaultConfig { autoStart.enabled false } } }',
	},
	ios: {
		config: '<key>DTXAutoStart</key> <false/>',
	},
};

使用至少 beaconUrl 和 applicationId 进行启动调用：启动调用示例

import { TNSDynatrace, DynatraceStartupConfiguration } from '@nstudio/nativescript-dynatrace';

TNSDynatrace.start(new DynatraceStartupConfiguration({ beaconUrl: 'beaconUrl', applicationId: 'applicationId' }));

有关更多详细信息，请参阅有关启动 API 的部分。

注意：如果您不使用 dynatrace.config.js 文件禁用自动化启动，则 beaconUrl 和 applicationId 的值没有任何影响，并且会被丢弃。

手动仪器化

要使用 NativeScript 插件的 API，请导入 API

import { TNSDynatrace } from '@nstudio/nativescript-dynatrace';

插件启动

通过 start(configuration: ManualStartupConfiguration) 方法手动触发插件的启动。如果您已为手动启动配置了 dynatrace.config.js，则插件在未调用此函数时不会发送任何数据。除了应用程序 id 和 beacon URL 之外，还有几个可选的配置参数，如下表所示

new ManualStartupConfiguration({
	beaconUrl: string,
	applicationId: string,
	reportCrash: boolean,
	logLevel: LogLevel,
	certificateValidation: boolean,
	userOptIn: boolean,
});

注意：使用的参数值是它们的默认值。

注意：请仅在手动启动时使用这些参数。如果您想进行自动化启动，请通过自动启动配置设置属性。您将在此处找到解释所有可用选项对应项的列表。

创建手动操作

要创建名为 "MyButton tapped" 的手动操作，请使用以下代码。leaveAction 重新关闭操作。要在此操作关闭之前报告值，请参阅报告值。

let myAction = TNSDynatrace.enterAction('MyButton tapped');
//Perform the action and whatever else is needed.
myAction.leaveAction();

创建手动子操作

您可以创建单个手动操作以及子操作。MyButton 子操作会自动放置在 MyButton 被点击之下。只要 MyButton 被点击是打开的，它就会收集所有的网页请求。

let myAction = TNSDynatrace.enterAction('MyButton tapped');
let mySubAction = TNSDynatrace.enterAction('MyButton Sub Action');
//Perform the action and whatever else is needed.
mySubAction.leaveAction();
myAction.leaveAction();

报告值

对于任何打开的操作，您可以报告某些值。以下 API 可用于操作

reportValue(valueName, value);
reportError(errorName, errorCode);
reportEvent(eventName);

要报告一个字符串值，请使用以下

let myAction = TNSDynatrace.enterAction('MyButton tapped');
myAction.reportStringValue('ValueName', 'ImportantValue');
myAction.leaveAction();

报告错误堆栈跟踪要手动报告错误堆栈跟踪，请使用以下 API 调用

识别用户

您可以通过以下调用来识别用户并使用名称标记当前会话

TNSDynatrace.identifyUser('User XY');

手动报告错误您可以通过以下 API 调用来手动报告崩溃

reportError(errorName, errorCode);

数据收集

隐私 API 方法允许您根据最终用户的个人偏好动态更改数据收集级别。每个最终用户可以从三个数据隐私级别中选择

export enum DataCollectionLevel {
	Off,
	Performance,
	UserBehavior,
}

• 关闭：本地代理不捕获任何监控数据。
• 性能：本地代理仅捕获匿名性能数据。可以用于识别单个用户的监控数据，如用户标签和自定义值，都不会被捕获。
• 用户行为：本地代理捕获性能和用户数据。在此模式下，本地代理会识别并报告在未来会话中重新访问的用户。获取和设置当前级别的 API 看起来像这样

getUserPrivacyOptions();
applyUserPrivacyOptions(userPrivacyOptions);

要检查设置的当前隐私选项

let privacyOptions = TNSDynatrace.getUserPrivacyOptions();

如果您想创建一个新的 UserPrivacyOptions 对象

let privacyConfig = new UserPrivacyOptions();
privacyConfig.crashReportingOptedIn = true;
privacyConfig.dataCollectionLevel = DataCollectionLevel.UserBehavior;

为此对象设置新值

privacyConfig.crashReportingOptedIn = false;
privacyConfig.dataCollectionLevel = DataCollectionLevel.Performance;

用于设置隐私选项的属性也可以用于获取选项

let level = privacyConfig.dataCollectionLevel;
let crashReporting = privacyConfig.crashReportingOptedIn;

应用对象上设置的价值

TNSDynatrace.applyUserPrivacyOptions(privacyConfig);

报告 GPS 位置

您可以报告纬度和经度，并指定一个可选的平台。

setGPSLocation(latitude, longitude);

设置信标头部

这允许您在每个代理 HTTP 请求上放置一组 HTTP 头部（例如，授权头部等）。它还将触发代理重新连接到带有新头部的信标端点。

注意：要清除之前设置的头部，请调用不带头部参数的方法，或者使用 null 值作为头部参数。

setBeaconHeaders(headers);

dynatrace.config.js 文件的结构

配置按照以下方式结构化

module.exports = {
	android: {
		/* Configuration for Android auto instrumentation*/
	},
	ios: {
		/* Configuration for iOS auto instrumentation */
	},
};

手动启动对应项

以下是可以与手动启动一起使用的所有选项的对应项列表。在对应项表下方，您将找到一个用于 Android 和 iOS 的示例配置块。

Android 块Android 块是 WebUI 中（在移动应用程序设置中）找到的 Android 配置的包装器。将内容复制到以下块中

android : { config : CONTENT_OF_ANDROID_CONFIG } 配置块的内容直接复制到 Gradle 文件中。有关可能的配置选项的更多信息，请参阅我们的 Gradle 插件的 DSL 文档。

iOS 块iOS 块是 WebUI 中（在移动应用程序设置中）找到的 iOS 配置的包装器。将内容复制到以下块中

ios : { config : CONTENT_OF_IOS_CONFIG } 配置块的内容直接复制到 plist 文件中。因此，您可以使用官方移动代理文档中找到的所有可能设置。

在dynatrace.config.js中定义构建阶段。如果您有多个阶段，如调试、QA和生产，您可能希望将它们分开，并让它们在不同的应用程序中报告。这可以通过两种不同的方法来实现。

Android 在Android中，您可以在配置文件中输入所有信息。以下dynatrace {}块必须插入到您的dynatrace.config.js文件中的android配置变量。

module.exports = {
	android: {
		config: `dynatrace {
configurations {
dev { variantFilter "Debug"}
demo {variantFilter "demo"}
prod {variantFilter "Release"}
}
}`,
	},
};

iOS 在iOS中，您可以在dynatrace.config.js文件中定义一些变量。以下属性必须插入到您的dynatrace.config.js文件中的iOS配置变量。

module.exports = {
	ios: {
		config: `
<key>DTXApplicationID</key>
<string>Your ApplicationId</string>
<key>DTXBeaconURL</key>
<string>Your Beacon URL</string>
`,
	},
};

用户选择模式 指定用户是否必须选择加入以被监控。启用时，您必须指定隐私设置。有关更多信息，请参阅API部分。

module.exports = {
	android: {
		config: `
dynatrace { configurations { defaultConfig { autoStart{ ... } userOptIn true } } }
`,
	},
	ios: {
		config: `
<key>DTXUserOptIn</key>
</true>
`,
	},
};

原生OneAgent调试日志 如果您的应用程序启动，但您看不到任何数据，您可能需要进一步挖掘以找出为什么OneAgent没有发送任何数据。提交支持工单是一个好主意，但首先收集日志甚至更好。

Android 将以下配置片段添加到您的dynatrace.config.js中的其他配置下（整个结构都是可见的，因此您知道配置属于何处），然后运行npm run instrumentDynatrace。

module.exports = {
	android: {
		config: `
dynatrace { configurations { defaultConfig { autoStart{ ... } debug.agentLogging true } } }
`,
	},
};

iOS 将以下配置片段添加到您的dynatrace.config.js中的其他配置下（整个结构都是可见的，因此您知道配置属于何处），然后运行npm run instrumentDynatrace。

module.exports = {
	ios: {
		config: `
<key>DTXLogLevel</key>
<string>ALL</string>
`,
	},
};

许可证

Apache许可证版本2.0