React Native 入门

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. 选择相应的 OS（Android 或 iOS），然后选择 React Native 作为平台。
5. 点击右下角的按钮，显示 “添加新应用”。

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

3.添加 App Center SDK 模块

SDK 的默认集成使用 CocoaPods for iOS。 如果未在应用中使用 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 配置 AppCenter-Config.plist 和为 Android 配置 appcenter-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

在 中创建名称为 android/app/src/main/assets/ 的新文件，并使用以下内容，并用您的应用机密值替换 {APP_SECRET_VALUE}。

{
    "app_secret": "{APP_SECRET_VALUE}"
}

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

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

在应用的主活动类 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

1. 使用 react-native 链接命令将插件链接到 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，并用您 App Center 项目的应用程序机密替换 YOUR_APP_SECRET 占位符的值。

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

3.3 [仅限 iOS] 在不使用 react-native link 或 CocoaPods 的情况下手动集成 React Native 的 SDK

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

1. 下载作为 zip 文件提供的 App Center SDK for React Native 框架并将其解压缩。

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

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

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

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

   • 最佳做法是，第三方库通常驻留在子目录中（通常称为供应商），因此，如果没有使用库的子目录组织项目，请立即（在项目的 ios 目录下）创建供应商子目录。
   • 在 Xcode 项目中创建一个名为 Vendor 的组，以模拟磁盘上的文件结构。

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

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

   • 确保项目导航器可见（⌘+1）。
   • 将 Finder（在上一步的位置）中的 AppCenter.framework、 AppCenterAnalytics.framework、 AppCenterCrashes.framework 和 AppCenterReactNativeShared.framework 文件拖放到 Xcode 的项目导航器中。 启动 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

   • .xcodeproj将文件从 Finder 拖放到 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>
    

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 中添加到 Libraries 组的每个 AppCenter React Native 插件项目：
      • 选择项目，然后在“标头搜索路径”部分中的“生成设置”选项卡下，添加标题文件的新位置，其中包含一个选项recursive：${SRCROOT}/../../../ios/Pods/Headers

3.4 [仅限 Android] 为低于 0.60 的 React Native 手动集成 SDK，而无需使用 react-native link

在没有 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')
   

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. 在 中创建名称为 android/app/src/main/assets/ 的新文件，并使用以下内容，并用您的应用机密值替换 APP_SECRET_VALUE。

   {
       "app_secret": "APP_SECRET_VALUE"
   }
   

3.5 如果使用自动备份来避免获取有关设备的错误信息，请执行以下步骤：

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

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

react-native run-android

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

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

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

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