開始使用 React Native

這很重要

Visual Studio App Center 於 2025 年 3 月 31 日淘汰，但分析和診斷功能除外，這些功能將持續支援到 2026 年 6 月 30 日。 瞭解更多資訊。

• 安卓
• iOS
• iOS 擴充功能
• React Native
• MAUI/Xamarin
• UWP
• WPF/WinForms
• 統一
• macOS
• macOS 擴充功能
• tvOS

App Center SDK 使用模組化架構，因此您可以使用任何或所有服務。

讓我們開始在應用程式中設定 App Center React Native SDK，以使用 App Center 分析與 App Center 當機。

1.Prerequisites

開始之前，請確定您已符合下列必要條件：

• 您使用的是執行 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 和 Crashes 新增至應用程式：

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

搭配 React Native 使用 App Center SDK 可以透過兩種方式來完成：為 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

使用下列內容建立名為 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：在程式代碼中設定

在應用程式的主要活動類別 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

備註

如果您的 React 模組在您的 Podfile 中通過相對路徑連接，但未在專案中引用，那麼連結腳本會失敗，因為它使用靜態 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，並以 App Center 專案的應用密鑰取代 YOUR_APP_SECRET 佔位符。

3. 編輯項目的 ios/{YourAppName}/AppCenter-Config.plist 檔案，以 App Center 專案的應用密鑰取代 YOUR_APP_SECRET 佔位符值。 如果 AppCenter-Config.plist 已經存在，但不是 Xcode 專案的一部分，您必須手動將它新增至 Xcode 專案（以滑鼠右鍵按兩下 XCode 中的應用程式，然後按兩下 [ 將檔案新增至 <應用程式名稱>...]。

3.3 [僅限 iOS] 手動整合適用於 React Native 的 SDK，而不使用 react-native link 或 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 檔案的形式提供的 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. [選擇性]建立第三方連結庫的子目錄。

   • 最佳做法是，第三方連結庫通常位於子目錄內（通常稱為 Vendor），因此，如果您沒有使用連結庫的子目錄來組織專案，請立即建立 Vendor 子目錄（位於專案的 ios 目錄下）。
   • 在 Xcode 專案中建立名為 Vendor 的群組，以模擬磁碟上的檔案結構。

6. 開啟 [尋找工具]，並將先前解壓縮的 AppCenter-SDK-Apple/iOS 和 AppCenterReactNativeShared 資料夾複製到您專案所在的位置資料夾中。

7. 將 SDK 架構新增至 Xcode 中的專案：

   • 請確定 [項目導覽器] 為可見的 （⌘+1）。
   • 將 AppCenter.framework、 AppCenterAnalytics.framework、 AppCenterCrashes.framework 和 AppCenterReactNativeShared.framework 檔案從 Finder 拖放到 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>
    

備註

接下來的兩個步驟僅適用於使用 React Native 0.60 和更新版本的應用程式。

13. 停用自動鏈結功能於 React Native 0.60 及以上版本：

    • 在每個 App Center 套件的 node_modules 資料夾中開啟 react-native.config.js ，並將 設定 dependency.platforms.ios 為 null：

    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] 手動整合低於 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')
   

備註

由於 jCenter 支援終止 ，所有元件都已移至 Maven Central 存放庫。 請遵循 本指南 ，瞭解如何從 jCenter 移轉至 Maven Central。

2. 開啟專案的 app 層級 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） 或更新版本為目標的應用程式會自動啟用自動備份。 

備註

如果您已經有具有備份規則的自定義檔案，請切換至第三個步驟。

一。 在 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"

丙. 將下列備份規則新增至 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

小提示

您可以在 中指定 iOS 裝置名稱，在 iOS 模擬器或 react-native run-ios --device "myDeviceName"上啟動它。

您可以透過下列命令來建置並啟動 Android 應用程式：

react-native run-android

小提示

您可以在 Android 模擬器或 Android 裝置上啟動它，方法是指定 react-native run-android --deviceId "myDeviceId" 命令中的 deviceId（adb devices）裝置識別碼。

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 而非 xcodeproj，因此 ios/{appname}.xcodeproj 檔案不會連結 App Center CocoaPods 相依性。

針對Android，請在Android Studio中匯入 Android 專案，並從該處建置。

您全都設定為在 SDK 自動收集的入口網站上視覺化分析和當機數據。 不需要額外的設定。 如需 API 指南和逐步解說，請參閱 分析 與 當機 一節，以瞭解 App Center 可以執行的動作。