使用 Apache Cordova 入門

App Center SDK 使用模組化架構,因此您可以輕鬆地在 Apache Cordova 應用程式中使用一個、數個或所有的 App Center 服務。

在本文中,您將瞭解如何將 App Center SDK 新增至您的 Apache Cordova 應用程式,然後在應用程式中設定 App Center 分析和 App Center 損毀功能。

1.Prerequisites

開始之前,請確定您的 Apache Cordova 應用程式專案符合下列最低需求:

  • Cordova CLI 6.4.0 或更新版本
  • cordova-android 引擎5.0.0 或更新版本
  • cordova-ios 引擎4.3.0 或更新版本

若要判斷您的 Cordova CLI 版本,請開啟終端機視窗或 Windows 命令提示字元,然後執行下列命令:

cordova -v

若要判斷 cordova-androidcordova-ios 版本,請開啟專案的 config.xml 檔案,您會在下列元素中找到定義的平臺引擎 engine

<engine name="android" spec="~6.2.3" />
<engine name="ios" spec="~4.4.0" />

您也必須安裝 CocoaPods 。 針對此,執行 sudo gem install cocoapods pod setup

2. 取得 App Center 應用程式秘密

為了讓 App Center SDK 與 App Center 中的應用程式專案連線,SDK 需要您的 App Center 專案的應用程式 秘密。 您稍後將瞭解如何使用此值設定 App Center Apache Cordova SDK,但現在,讓我們看看哪裡可以找到它。

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

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

  1. 註冊 App Center 帳戶,或登入現有的 App Center 帳戶 https://appcenter.ms
  2. 在 [App Center 儀表板] 中,按一下頁面右上角 的 [新增 ] 下拉式清單。 從功能表選取 [ 新增應用程式 ]。
  3. 輸入應用程式專案的名稱,並視需要新增選擇性的描述。
  4. 為您的應用程式專案選取適當的作業系統,僅 (Android 或 iOS) ,然後選取 [ Cordova 平臺] 選項。
  5. 按一下頁面右下角的 [ 新增應用程式 ] 按鈕。
  6. 在應用程式專案的 設定 頁面上尋找應用程式秘密。 存取頁面右上角的功能表,然後選取 [ 複製應用程式密碼 ] 專案,將應用程式密碼複製到剪貼簿。

3. 將 App Center SDK 新增至專案

安裝 SDK

針對 Apache Cordova 專案,SDK 會透過標準 Apache Cordova 外掛程式散發。 使用本節提供的指示,將 App Center SDK 新增至 Cordova 專案。 首先,開啟終端機視窗或 Windows 命令提示字元,然後流覽至 Cordova 專案的根資料夾。

若要在您的專案中新增對 App Center 分析 的支援,請執行下列命令:

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 外掛程式-appcenter-分析cordova-外掛程式-appcenter- 損毀大部分使用 app Center 的應用程式;它們提供適用于開發人員的實用資訊,而不需要任何額外的設定或編碼。

設定外掛程式

應用程式祕密

您必須使用您的 App Center project app secret 來設定專案,才能在 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 值為之屬性的專案 APP_SECRET ,以及 value 包含範例中所顯示之值的屬性。 此處所 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 分析,則需要執行一些額外的設定步驟。 在編輯器中開啟 Apache Cordova 專案的 config.xml 檔案,然後將下列一或多個元素新增 preferences 至檔案:

  • APPCENTER_ANALYTICS_ENABLE_IN_JS - (選擇性,預設值為 false) 控制是否要自動啟用分析。 當 false 為時,預設會啟用分析。 true若為,應用程式必須 AppCenter.Analytics.setEnabled(true) 在其 JavaScript 程式碼) 中呼叫 (,才能在將資料傳送至 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 屬性新增至 <application> AndroidManifest.xml 檔案內的元素,請將下列幾行新增至應用程式的 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 可以進行的作業。