開始使用 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.Prerequisites

開始之前，請確定您的 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 秘密。 您稍後會瞭解如何使用此值來設定 App Center Apache Cordova SDK，但目前，讓我們來查看找到它的位置。

如果您有現有的 App Center 應用程式專案，請存取 App Center 儀錶板，然後開啟您的專案。 您也可以在應用程式專案的 [ 設定 ] 頁面上使用應用程式秘密。 存取頁面右上角的功能表，然後選取 [ 複製應用程式密碼] 將應用程式密碼 複製到剪貼簿。

如果您沒有在 App Center 儀錶板中建立應用程式，請完成下列步驟。

1. 註冊 App Center 帳戶，或登入位於 https://appcenter.ms的現有 App Center 帳戶。
2. 在 App Center 儀錶板中，按下頁面右上角的 [ 新增] 下拉式清單。 從功能表中選取[ 新增應用程式 ]。
3. 輸入應用程式項目的名稱，視需要新增選擇性描述。
4. (Android 或 iOS) 選取應用程式項目的適當 OS，然後選取 [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 值為 之屬性的專案，以及value具有範例中所顯示值APP_SECRET的屬性。 在此， 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，預設會啟用分析。 當 為 時 true，應用程式必須在其 JavaScript 程式) 代碼中呼叫 AppCenter.Analytics.setEnabled(true) (，才能啟用 Analytics，才能將數據傳送至 App Center。 當您想要詢問使用者是否要在應用程式內啟用分析資訊之前共用分析資訊，此喜好設定非常有用。 深入瞭解手動傳送使用者事件。

  範例：

  <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將 屬性新增至 AndroidManifest.xml 檔案內的 元素，請將下列幾行新增至<application>應用程式的 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 可以執行的動作。