Apache Cordova 入门

重要

Visual Studio App Center 计划于 2025 年 3 月 31 日停用。 虽然可以继续使用 Visual Studio App Center，直到它完全停用，但你可以考虑迁移到几个建议的替代方法。

详细了解支持时间线和替代方法。

• Android
• iOS
• iOS 扩展
• React Native
• MAUI/Xamarin
• UWP
• WPF/WinForms
• Unity
• macOS
• macOS 扩展
• tvOS
• Cordova

注意

对 Cordova Apps 的支持已于 2022 年 4 月结束。 有关详细信息，请参阅 App Center 博客。

App Center SDK 使用模块化体系结构，因此你可以在 Apache Cordova 应用程序中轻松使用一个、多个或所有 App Center 服务。

本文介绍如何将 App Center SDK 添加到 Apache Cordova 应用程序，然后在应用程序中配置 App Center Analytics 和 App Center 崩溃功能。

1.先决条件

在开始之前，请确保 Apache Cordova 应用程序项目满足以下最低要求：

• Cordova CLI 6.4.0 或更高版本
• cordova-android engine 5.0.0 或更高版本
• cordova-ios engine 4.3.0 或更高版本

若要确定 Cordova CLI 版本，请打开终端窗口或 Windows 命令提示符并执行以下命令：

cordova -v

若要确定 cordova-android 和 cordova-ios 版本，请打开项目的 config.xml 文件，你将找到在如下所示的元素中 engine 定义的平台引擎：

<engine name="android" spec="~6.2.3" />
<engine name="ios" spec="~4.4.0" />

还必须安装 CocoaPods 。 为此，请运行 sudo gem install cocoapodspod setup

2.获取 App Center 应用机密

为了使 App Center SDK 与 App Center 中的应用程序项目连接，SDK 需要 App Center 项目 的应用机密。 稍后你将了解如何使用此值配置 App Center Apache Cordova SDK，但现在，让我们看看在何处查找它。

如果你有现有的 App Center 应用程序项目，则访问 App Center 仪表板并打开项目。 还可以在应用程序项目的 “设置” 页上获取应用机密。 访问页面右上角的菜单，然后选择“ 复制应用机密 ”，将应用机密复制到剪贴板。

如果没有在 App Center 仪表板中创建应用程序，请完成以下步骤。

1. 注册 App Center 帐户，或在 处登录到现有的 App Center 帐户 https://appcenter.ms。
2. 在 App Center 仪表板中，单击页面右上角的 “添加新 项”下拉列表。 从菜单中选择 “添加新应用 ”。
3. 输入应用程序项目的名称，根据需要添加可选说明。
4. 为应用程序项目选择适当的 OS (Android 或 iOS 仅) ，然后选择 Cordova 平台选项。
5. 单击页面右下角的 “添加新应用 ”按钮。
6. 在应用程序项目的 “设置” 页上找到应用机密。 访问页面右上角的菜单，然后选择“ 复制应用机密 ”项，将应用机密复制到剪贴板。

3. 将 App Center SDK 添加到项目

安装 SDK

对于 Apache Cordova 项目，SDK 通过标准 Apache Cordova 插件分发。 按照本部分中提供的说明将 App Center SDK 添加到 Cordova 项目。 首先打开终端窗口或 Windows 命令提示符，然后导航到 Cordova 项目的根文件夹。

若要向项目添加对 App Center Analytics 的支持 ，请执行以下命令：

cordova plugin add cordova-plugin-appcenter-analytics

若要向项目添加对 App Center 崩溃 的支持，请执行以下命令：

cordova plugin add cordova-plugin-appcenter-crashes

若要使用一个命令向项目添加所有 App Center 功能的插件，请执行以下命令：

cordova plugin add cordova-plugin-appcenter-analytics cordova-plugin-appcenter-crashes

注意

应添加 cordova-plugin-appcenter-analytics 和 cordova-plugin-appcenter-crashes ，大多数使用 App Center 的应用;它们为开发人员提供了有用的信息，无需任何其他设置或编码。

配置插件

应用程序密码

必须先使用 App Center 项目应用机密配置项目，然后才能在 Apache Cordova 项目中使用 App Center SDK。

打开 Apache Cordova 项目的 config.xml 文件;对于 Apache Cordova 项目的每个目标 platform 元素，目前仅 (Android 和 iOS) ，请添加采用以下格式的子 preference 元素：

<preference name="APP_SECRET" value="0000-0000-0000-0000-000000000000" />

在此示例中，你将添加一个 name 元素，该元素具有 值为 的属性 APP_SECRET，以及一个 value 具有示例中所示值的 属性。 此处， 0000-0000-0000-0000-000000000000 示例中显示的 是 App Center 项目应用机密的任意表示形式。 将示例中所示的应用机密替换为 App Center 项目的实际应用机密。

作为一个完整的示例，对于同时支持 Android 和 iOS 目标的 Apache Cordova 项目，你将在 App Center 中具有单独的应用项目定义，因此，每个目标平台都有不同的应用机密值。 项目 config.xml 文件的相关部分如下所示：

<platform name="android">
   <preference name="APP_SECRET" value="0000-0000-0000-0000-000000000001" />
</platform>
<platform name="ios">
   <preference name="APP_SECRET" value="0000-0000-0000-0000-000000000002" />
</platform>

注意

该示例不显示实际的应用机密值;这些只是模型，你需要获取 App Center 项目的应用机密并在此处使用它们。 应用机密不同，因为在 App Center 中，Android 和 iOS 应用程序项目具有唯一的机密。

分析首选项

如果在应用中使用 App Center Analytics，则需要执行一些其他配置步骤。 在编辑器中打开 Apache Cordova 项目的 config.xml 文件，并将以下 preferences 一个或多个元素添加到该文件：

• APPCENTER_ANALYTICS_ENABLE_IN_JS - (可选，默认值为 false) 控制是否自动启用 Analytics。 如果 false为 ，则默认启用 Analytics。 当为 时 true，应用程序必须在其 JavaScript 代码) 调用 AppCenter.Analytics.setEnabled(true) (，以在将数据发送到 App Center 之前启用 Analytics。 如果要询问用户在应用程序中启用分析信息之前是否要共享分析信息，则此首选项非常有用。 详细了解如何手动发送用户事件。

  例如：

  <preference name="APPCENTER_ANALYTICS_ENABLE_IN_JS" value="true" />
  

• APPCENTER_CRASHES_ALWAYS_SEND - (可选，默认值为 true) 指定在应用崩溃时是否自动将崩溃报告发送到 App Center。 自动发送故障报告时，将报告每次故障，这可能会使工程和支持团队不知所措。 手动发送故障报告 (设置为 APPCENTER_CRASHES_ALWAYS_SENDfalse) 时，应用程序中的代码可以对崩溃进行会审，并决定何时将崩溃报告发送到 App Center、报告中包含哪些数据等。 这意味着开发人员需要做更多的工作，但它也提供了对用户隐私的更大控制，并允许你附加带有故障报告的消息。 详细了解如何在 JS 中处理崩溃报告。

  例如：

  <preference name="APPCENTER_CRASHES_ALWAYS_SEND" value="false" />
  

  如果使用自动备份来避免获取有关设备的错误信息，请遵循后续步骤：

注意

面向 Android 6.0 (API 级别 23) 或更高版本的应用会自动启用自动备份。 

注意

如果已有包含备份规则的自定义文件，请切换到第三步。

a. 在 res/xml 文件夹中创建 appcenter_backup_rule.xml 文件。

<resource-file src="appcenter_backup_rule.xml" target="res/xml/appcenter_backup_rule.xml" />

b. 若要将 android:fullBackupContent 属性添加到 <application>AndroidManifest.xml 文件中的 元素，请将以下行添加到应用的 config.xml 文件中：

<edit-config file="app/src/main/AndroidManifest.xml" mode="merge" target="/manifest/application">
     <application android:fullBackupContent="@xml/appcenter_backup_rule" />
</edit-config>
 ```

c. Add the following backup rules to the **appcenter_backup_rule.xml** file:

```xml
<full-backup-content xmlns:tools="http://schemas.android.com/tools">
   <exclude domain="sharedpref" path="AppCenter.xml"/>
   <exclude domain="database" path="com.microsoft.appcenter.persistence"/>
   <exclude domain="database" path="com.microsoft.appcenter.persistence-journal"/>
   <exclude domain="file" path="error" tools:ignore="FullBackupContent"/>
   <exclude domain="file" path="appcenter" tools:ignore="FullBackupContent"/>
</full-backup-content>

4. 下一步要去哪里？

很好，你都可以在门户中可视化 SDK 自动收集的分析和崩溃数据。 不需要任何其他设置。 查看 API 指南和演练的分析和崩溃部分，了解 App Center 可以执行的操作。