React Native入门

重要

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

App Center SDK 使用模块化体系结构，因此你可以使用任何或所有服务。

让我们开始在应用中设置 App Center React Native SDK，以使用 App Center Analytics 和 App Center 崩溃。

1.先决条件

在开始之前，请确保满足以下先决条件：

• 你使用的是运行 React Native 0.34 或更高版本的 React Native 项目。
• 你的目标是在 Android 版本 5.0/API 级别 21 或更高版本或 iOS 版本 9.0 或更高版本上运行的设备。
• 你未使用在 iOS 上提供崩溃报告功能的任何其他库。
• 对于 iOS，使用 SDK 的默认方式需要 CocoaPods。 (如果尚未安装 CocoaPods，请按照 CocoaPods 入门) 执行此操作。 不过，也可以手动链接 SDK。

2.在 App Center 门户中创建应用以获取应用机密

如果已在 App Center 门户中创建了应用，则可以跳过此步骤。

1. 前往 appcenter.ms。
2. 注册或登录，点击门户右上角显示 “新增” 的蓝色按钮，然后从下拉菜单中选择“ 添加新应用 ”。
3. 输入应用的名称和可选说明。
4. (Android 或 iOS) 选择合适的 OS，然后选择“React Native”作为平台。
5. 点击右下角显示 “添加新应用”的按钮。

创建应用后，可以在 App Center 门户的“设置”页上获取其应用机密。 在 “设置” 页面的右上角，单击 三个垂直点 ，然后选择 Copy app secret 获取应用机密。

3.添加 App Center SDK 模块

SDK 的默认集成使用适用于 iOS 的 CocoaPods。 如果未在应用中使用 CocoaPods，则需要为 iOS 应用手动集成 React Native SDK。

打开终端并导航到 React Native 项目的根目录，然后输入以下行以将 App Center Analytics 和崩溃添加到应用：

npm install appcenter appcenter-analytics appcenter-crashes --save-exact

如果首选 yarn 而不是 npm，请使用以下命令安装 App Center：

yarn add appcenter appcenter-analytics appcenter-crashes --exact

App Center SDK 使用模块化方法，只需添加要使用的 App Center 服务的模块。 将 appcenter-analytics 和 appcenter-crashes 添加到几乎每个应用是有意义的，因为它们无需额外设置即可提供价值。 appcenter 提供常规用途的 App Center API，可用于多个服务。

3.1 为 React Native 0.60 自动集成 SDK

可通过两种方式将 App Center SDK 与 React Native配合使用：为 iOS 配置 ，为 Android 配置 AppCenter-Config.plistappcenter-config.json，或者调用接受 appSecret 作为参数的本机启动函数。

3.1.1 集成 React Native iOS

从 iOS 目录运行 pod install --repo-update 以安装 CocoaPods 依赖项。

3.1.1.1 设置 AppSecret 选项 1：配置 AppCenter-Config.plist

1. 使用以下内容创建一个名称 AppCenter-Config.plist 为 的新文件，并将 替换为 {APP_SECRET_VALUE} 应用机密值。 不要忘记将此文件添加到 Xcode 项目 (在 Xcode 中右键单击该应用，然后单击“ 将文件添加到 <AppName>...”) 。

   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "https://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
       <dict>
       <key>AppSecret</key>
       <string>{APP_SECRET_VALUE}</string>
       </dict>
   </plist>
   

2. 修改应用的 AppDelegate.m 或 AppDelegate.mm 文件，以包含用于启动 SDK 的代码。

   • 添加以下导入内容：

   #import <AppCenterReactNative.h>
   #import <AppCenterReactNativeAnalytics.h>
   #import <AppCenterReactNativeCrashes.h>
   

   • 将以下行添加到 application:didFinishLaunchingWithOptions: 方法：

   [AppCenterReactNative register];
   [AppCenterReactNativeAnalytics registerWithInitiallyEnabled:true];
   [AppCenterReactNativeCrashes registerWithAutomaticProcessing];
   

3.1.1.2 设置 AppSecret 选项 2：在代码中配置

修改应用的 AppDelegate.m 或 AppDelegate.mm 文件，以包含用于启动 SDK 的代码。

• 添加以下导入内容：

#import <AppCenterReactNativeShared/AppCenterReactNativeShared.h>
#import <AppCenterReactNative.h>
#import <AppCenterReactNativeAnalytics.h>
#import <AppCenterReactNativeCrashes.h>

• 将以下行添加到 application:didFinishLaunchingWithOptions: 方法：

[AppCenterReactNativeShared setStartAutomatically:YES];
[AppCenterReactNativeShared setAppSecret:@"{Your App Secret}"];
[AppCenterReactNative register];
[AppCenterReactNativeAnalytics registerWithInitiallyEnabled:true];
[AppCenterReactNativeCrashes registerWithAutomaticProcessing];

3.1.2 集成 React Native Android

修改应用的 res/values/strings.xml ，以包含以下行：

<string name="appCenterCrashes_whenToSendCrashes" moduleConfig="true" translatable="false">DO_NOT_ASK_JAVASCRIPT</string>
<string name="appCenterAnalytics_whenToEnableAnalytics" moduleConfig="true" translatable="false">ALWAYS_SEND</string>

3.1.2.1 设置 AppSecret 选项 1：配置 appcenter-config.json

使用以下内容创建一个名称 为 appcenter-config.jsonandroid/app/src/main/assets/ 的新文件，并将 替换为 {APP_SECRET_VALUE} 应用机密值。

{
    "app_secret": "{APP_SECRET_VALUE}"
}

注意：如果名为 assets 的文件夹不存在，则应在“project_root/android/app/src/main/assets”下创建。

3.1.2.2 设置 AppSecret 选项 2：在代码中配置

在应用的 main activity 类 onCreate-callback 中添加以下行，以使用 App Center Analytics 和 App Center 崩溃：

AppCenter.start(getApplication(), "{Your App Secret}", Analytics.class, Crashes.class);

AppCenter.start(application, "{Your App Secret}", Analytics::class.java, Crashes::class.java)

3.2 为低于 0.60 的React Native自动集成 SDK

注意

如果使用 Podfile 中的相对路径链接React模块，但在项目中未引用，则链接脚本将失败，因为它使用静态 Pod 版本链接 App Center。 如果已运行链接脚本，则必须按照React Native故障排除部分中的步骤操作，或者自行链接该脚本

1. 使用 react-native link 命令将插件链接到 React Native 应用。

   react-native link appcenter
   react-native link appcenter-analytics
   react-native link appcenter-crashes
   

   对于 iOS，如果看到如下错误，它将尝试从 CocoaPods 下载适用于 iOS 和 macOS 的 App Center SDK：

   Added code to initialize iOS App Center SDK in ios/reactnativesample/AppDelegate.m
   Analyzing dependencies [!] Unable to find a specification for AppCenterReactNativeShared (~> {version}) 
   

   运行以下命令：

   pod repo update
   

   然后重试运行 react-native link。

   注意

   在链接过程中，App Center SDK 不会自动为 App Center 模块设置模拟。 如果在应用程序中使用 Jest 测试框架 ，并在使用 Jest 运行测试时遇到 App Center SDK 导致的错误，请将以下内容添加到 package.json 文件的 jest 部分， (仅包含正在使用) 的模块：

   "setupFiles": [
      "<rootDir>/node_modules/appcenter/test/AppCenterMock.js",
      "<rootDir>/node_modules/appcenter-analytics/test/AppCenterAnalyticsMock.js",
      "<rootDir>/node_modules/appcenter-crashes/test/AppCenterCrashesMock.js",
   ]
   

   注意

   无论崩溃的处理是自动的还是由 Javascript 方法触发的，崩溃始终在应用程序重启后进行处理。 应用程序崩溃时无法处理崩溃。

2. 编辑项目的 android/app/src/main/assets/appcenter-config.json ，并将 YOUR_APP_SECRET 占位符值替换为 App Center 项目的应用程序机密。

3. 编辑项目的 ios/{YourAppName}/AppCenter-Config.plist 文件，并将 YOUR_APP_SECRET 占位符值替换为 App Center 项目的应用程序机密。 如果 AppCenter-Config.plist 已存在但不是 Xcode 项目的一部分，则必须手动将其添加到 Xcode 项目中， (右键单击 XCode 中的应用，然后单击“ 将文件添加到 <应用名称>...”) 。

3.3 [仅限 iOS] 手动集成 SDK 以React Native，无需 react-native 链接或 CocoaPods

如果不想使用 CocoaPods，请执行此集成。 强烈建议通过 CocoaPods 集成 SDK，如上所述。 不过，也可以手动集成 iOS 本机 SDK。

注意

最新的 App Center React Native SDK 不一定依赖于最新的 App Center iOS SDK，因为 iOS SDK 是在React Native之前更新和发布的。

因此，你必须知道React Native SDK 所依赖的 iOS SDK 版本。

1. 下载适用于以 zip 文件提供React Native框架的 App Center SDK 并将其解压缩。

2. 你将看到一个名为 AppCenterReactNativeShared 的文件夹，其中包含所需的 React Native iOS 网桥的单个框架。

3. 下载作为 zip 文件提供的相应 适用于 iOS 的 App Center SDK 框架并将其解压缩。

4. 你将看到一个名为 AppCenter-SDK-Apple/iOS 的文件夹，其中包含每个 App Center 服务的不同框架。 项目中需要调用 AppCenter 的框架，因为它包含在不同模块之间共享的代码。

5. [可选]为第三方库创建子目录。

   • 最佳做法是，第三方库通常位于子目录内， (它通常称为“供应商) ”，因此，如果没有使用库的子目录来组织项目，则现在 (项目) 的 ios 目录下创建一个 Vendor 子目录。
   • 在 Xcode 项目中创建名为 Vendor 的组，以模拟磁盘上的文件结构。

6. 打开 Finder，将以前解压缩的 AppCenter-SDK-Apple/iOS 和 AppCenterReactNativeShared 文件夹复制到项目所在的文件夹中，该文件夹位于所需位置。

7. 在 Xcode 中将 SDK 框架添加到项目中：

   • 确保项目导航器 (⌘+1) 可见。
   • 将 Finder (中的 AppCenter.framework、 AppCenterAnalytics.framework、 AppCenterCrashes.framework 和 AppCenterReactNativeShared.framework 文件拖放到上一步) 到 Xcode 的 Project Navigator 中。 启动 SDK 需要 AppCenter.framework 和 AppCenterReactNativeShared.framework 文件，确保它们已添加到项目中，否则其他模块将不起作用，并且不会编译应用。
   • 将显示一个对话框，确保已选中应用目标，然后单击“ 完成”。

8. 将 AppCenter React Native 插件项目链接到应用的项目：

   • 确保项目导航器 (⌘+1) 可见。

   • 对于每个 AppCenter React Native插件导航到包含源代码的文件夹。 路径分别为

     • /node_modules/appcenter/ios
     • /node_modules/appcenter-analytics/ios
     • /node_modules/appcenter-crashes/ios

   • 将文件从 Finder 拖放 .xcodeproj 到 Xcode 的项目导航器中。 通常位于 “库” 组下。

9. AppCenter React Native插件的链接库。 打开项目设置，在“链接框架和库”部分中的“常规”选项卡下，添加引用上一步添加的目标库的新项：

   • libAppCenterReactNative.a
   • libAppCenterReactNativeAnalytics.a
   • libAppCenterReactNativeCrashes.a

10. 修改标头搜索路径以查找 AppCenter React Native 插件项目中的标头。 打开项目设置，在“标头搜索路径”部分中的“生成设置”选项卡下，为头文件添加新位置：

• $(SRCROOT)/../node_modules/appcenter/ios/AppCenterReactNative
• $(SRCROOT)/../node_modules/appcenter-analytics/ios/AppCenterReactNativeAnalytics
• $(SRCROOT)/../node_modules/appcenter-crashes/ios/AppCenterReactNativeCrashes

11. 修改应用的 AppDelegate.m 或 AppDelegate.mm 文件，以包含用于启动 SDK 的代码：

    • 添加以下导入内容：

    #import <AppCenterReactNative/AppCenterReactNative.h>
    #import <AppCenterReactNativeAnalytics/AppCenterReactNativeAnalytics.h>
    #import <AppCenterReactNativeCrashes/AppCenterReactNativeCrashes.h>
    

    • 将这些行添加到 application:didFinishLaunchingWithOptions: 方法

    [AppCenterReactNative register];
    [AppCenterReactNativeAnalytics registerWithInitiallyEnabled:true];
    [AppCenterReactNativeCrashes registerWithAutomaticProcessing];
    

12. 使用以下内容创建名为 AppCenter-Config.plist 的新文件，并将 替换为 {APP_SECRET_VALUE} 应用机密值。 不要忘记将此文件添加到 XCode 项目， (右键单击 XCode 中的应用，然后单击“ 将文件添加到 <应用名称>...”) 。

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "https://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
        <dict>
        <key>AppSecret</key>
        <string>{APP_SECRET_VALUE}</string>
        </dict>
    </plist>
    

注意

接下来的两个步骤仅适用于使用 React Native 0.60 及更高版本的应用。

13. 禁用React Native 0.60 及更高版本的自动链接：

    • 在每个 App Center 包的 node_modules 文件夹中， 打开react-native.config.js 并设置为 dependency.platforms.iosnull：

    module.exports = {
      dependency: {
        platforms: {
          ios: null,
          ...
        }
      }
    };
    

14. 修改标头搜索路径以查找 App Center React Native 插件项目中的React Native标头：

    • 确保项目导航器 (⌘+1) 可见。
    • 对于在步骤 8 中添加到“库”组的每个 AppCenter React Native插件项目：
      • 选择项目，然后在“标头搜索路径”部分中的“生成设置”选项卡下，使用选项为头文件recursive添加新位置：${SRCROOT}/../../../ios/Pods/Headers

3.4 [仅限 Android] 手动集成 SDK，React Native低于 0.60，没有 react-native 链接

没有 命令的 react-native link 集成步骤。

1. 打开 android/settings.gradle 文件并插入以下行。 在项目中包括所需的依赖项。 在本部分中，每个 SDK 模块都需要添加为单独的依赖项。 如果要使用 App Center Analytics 和崩溃，请添加以下行：

     include ':appcenter-crashes'
     project(':appcenter-crashes').projectDir = new File(rootProject.projectDir, '../node_modules/appcenter-crashes/android')
     include ':appcenter-analytics'
     project(':appcenter-analytics').projectDir = new File(rootProject.projectDir, '../node_modules/appcenter-analytics/android')
     include ':appcenter'
     project(':appcenter').projectDir = new File(rootProject.projectDir, '../node_modules/appcenter/android')
   

注意

由于 jCenter 支持终止， 我们所有的程序集都已移动到 Maven Central 存储库。 请按照 本指南 操作，了解如何从 jCenter 迁移到 Maven Central。

2. 打开项目的应用级别 build.gradle 文件 (android/app/build.gradle) ，并将以下行 dependencies 添加到 节：

   dependencies {
       implementation project(':appcenter-crashes')
       implementation project(':appcenter-analytics')
       implementation project(':appcenter')
       ...
   }
   

3. 修改应用的 MainApplication.java 文件，以包含用于启动 SDK 的代码：

   • 将这些行添加到导入部分

   import com.microsoft.appcenter.reactnative.crashes.AppCenterReactNativeCrashesPackage;
   import com.microsoft.appcenter.reactnative.analytics.AppCenterReactNativeAnalyticsPackage;
   import com.microsoft.appcenter.reactnative.appcenter.AppCenterReactNativePackage;
   

   • 将 AppCenter 包添加到 List<ReactPackage> getPackages() 方法

   @Override
   protected List<ReactPackage> getPackages() {
     return Arrays.<ReactPackage>asList(
         new MainReactPackage(),
           new AppCenterReactNativeCrashesPackage(MainApplication.this, getResources().getString(R.string.appCenterCrashes_whenToSendCrashes)),
           new AppCenterReactNativeAnalyticsPackage(MainApplication.this, getResources().getString(R.string.appCenterAnalytics_whenToEnableAnalytics)),
           new AppCenterReactNativePackage(MainApplication.this)
     );
   }
   

4. ) 打开strings.xml 文件 (android/app/src/main/res/values ，并在标记中添加<resources></resources>以下行：

   <string name="appCenterAnalytics_whenToEnableAnalytics" moduleConfig="true" translatable="false">ALWAYS_SEND</string>
   <string name="appCenterCrashes_whenToSendCrashes" moduleConfig="true" translatable="false">DO_NOT_ASK_JAVASCRIPT</string>
   

5. 使用以下内容创建一个名称 为 appcenter-config.jsonandroid/app/src/main/assets/ 的新文件，并将 替换为 APP_SECRET_VALUE 应用机密值。

   {
       "app_secret": "APP_SECRET_VALUE"
   }
   

警告

不建议在源代码中嵌入应用机密。

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

注意

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

注意

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

a. 在 android/app/src/main/res/xml 文件夹中创建appcenter_backup_rule.xml 文件。

b. 打开项目的 AndroidManifest.xml 文件。 将 android:fullBackupContent 属性添加到 <application> 元素。 它应指向 appcenter_backup_rule.xml 资源文件。

android:fullBackupContent="@xml/appcenter_backup_rule"

c. 将以下备份规则添加到 appcenter_backup_rule.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

现在，可以从命令行或 Xcode/Android Studio 生成和启动应用程序。

4.1 从命令行生成并运行应用程序

可以通过以下命令生成和启动 iOS 应用程序：

react-native run-ios

提示

通过在 中react-native run-ios --device "myDeviceName"指定 iOS 设备名称，可以在 iOS 模拟器或 iOS 设备上启动它。

可以通过以下命令生成并启动 Android 应用程序：

react-native run-android

提示

可以通过从adb devices命令) 在 (deviceId 中react-native run-android --deviceId "myDeviceId"指定设备 ID，在 Android 仿真器或 Android 设备上启动它。

4.2 从 Xcode 或 Android Studio 生成并运行应用程序

对于 iOS，请在 Xcode 中打开项目的 ios/{appname}.xcworkspace 或 ios/{appname}.xcodeproj 文件，并从那里生成。

注意

如果通过 react-native link (自动链接 App Center（如步骤 3.1) ），则应在 Xcode 中打开项目的 ios/{appname}.xcworkspace 文件。 因为 App Center CocoaPods 依赖项只能与 不一起使用xcworkspace，并且ios/{appname}.xcodeproj该文件不会链接 App Center CocoaPods xcodeproj依赖项。

对于 Android，请在 Android Studio 中导入 Android 项目并从中生成。

你已准备好在 SDK 自动收集的门户上可视化分析和崩溃数据。 无需其他设置。 查看 API 指南和演练的分析和崩溃部分，了解 App Center 可以执行的操作。