開始使用 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.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 和當機新增至應用程式：

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

如果您偏好使用 yarnnpm，請使用下列命令來安裝 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 自動整合 SDK React Native 0.60

您可以透過下列兩種方式使用App Center SDK搭配 React Native：設定 AppCenter-Config.plist iOS和適用於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.json 的新 android/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 自動整合 SDK，以 React Native 低於 0.60

注意

如果您的 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] 手動整合 SDK 以進行 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. 下載 App Center SDK for React Native 架構，以 zip 檔案的形式提供，並將其解壓縮。

2. 您會看到名為 AppCenterReactNativeShared 的資料夾，其中包含 iOS 網橋所需 React Native 的單一架構。

3. 下載作為 zip 檔案提供的對應 App Center SDK for iOS 架構，並將其解壓縮。

4. 您會看到名為 AppCenter-SDK-Apple/iOS 的資料夾，其中包含每個 App Center 服務的不同架構。 專案中需要呼叫 AppCenter 的架構，因為它包含不同模組之間共用的程序代碼。

5. [選擇性]建立第三方連結庫的子目錄。

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

6. 開啟 [尋找器]，並將先前解壓縮的 AppCenter-SDK-Apple/iOS 和 AppCenterReactNativeShared 資料夾複製到您要放置位置的項目資料夾中。

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

   • 請確定項目導覽器可見 (⌘+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] 手動整合 SDK，React Native 低於 0.60，而不需回應原生連結

沒有命令的 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.json 的新 android/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

提示

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

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

react-native run-android

提示

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

4.2 從 Xcode 或 Android Studio 建置並執行您的應用程式

針對 iOS，在 Xcode 中開啟專案的 ios/{appname}.xcworkspace 或 ios/{appname}.xcodeproj 檔案，然後從該處建置。

注意

如果您透過步驟 3.1) 自動透過 react-native link (連結 App Center，您應該在 Xcode 中開啟項目的 ios/{appname}.xcworkspace 檔案。 因為 App Center CocoaPods 相依性只適用於 xcworkspace ， xcodeproj所以 ios/{appname}.xcodeproj 檔案不會連結 App Center CocoaPods 相依性。

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

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