Начало работы с Apache Cordova

Важно!

Прекращение поддержки Центра приложений Visual Studio запланировано на 31 марта 2025 г. Хотя вы можете продолжать использовать Центр приложений Visual Studio, пока он не будет полностью выведен из эксплуатации, существует несколько рекомендуемых вариантов, на которые вы можете рассмотреть возможность миграции.

Узнайте больше о сроках поддержки и альтернативных вариантах.

• Android
• iOS
• Расширения iOS
• React Native
• MAUI/Xamarin
• UWP
• WPF/WinForms
• Unity
• macOS
• Расширения macOS
• tvOS
• Cordova

Примечание

Поддержка Cordova Apps прекращена в апреле 2022 г. Дополнительные сведения см. в блоге Центра приложений.

Пакет SDK центра приложений использует модульную архитектуру, поэтому вы можете легко использовать одну, несколько или все службы Центра приложений в приложении Apache Cordova.

Из этой статьи вы узнаете, как добавить пакет SDK центра приложений в приложения Apache Cordova, а затем настроить возможности аналитики Центра приложений и аварийного завершения работы центра приложений в приложении.

1. Предварительные требования

Прежде чем начать, убедитесь, что проект приложения 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. Получение секрета приложения Центра приложений

Чтобы пакет SDK центра приложений подключалось к проекту приложения в Центре приложений, пакету SDK требуется секрет приложения вашего проекта Центра приложений. Позже вы узнаете, как настроить пакет SDK Apache Cordova для Центра приложений с этим значением, но пока вы узнаете, где его найти.

Если у вас есть существующий проект приложения Центра приложений, перейдите на панель мониторинга Центра приложений и откройте проект. Секрет приложения также можно получить на странице параметров проекта приложения. Откройте меню в правом верхнем углу страницы, а затем выберите Копировать секрет приложения , чтобы скопировать секрет приложения в буфер обмена.

Если на панели мониторинга Центра приложений не создано приложение, выполните следующие действия.

1. Зарегистрируйтесь для получения учетной записи Центра приложений или войдите в существующую учетную запись Центра приложений по адресу https://appcenter.ms.
2. На панели мониторинга Центра приложений щелкните раскрывающийся список Добавить новый в правом верхнем углу страницы. В меню выберите Добавить новое приложение .
3. Введите имя проекта приложения, добавив необязательное описание.
4. Выберите соответствующую ОС для проекта приложения (только для Android или iOS), а затем выберите вариант платформы Cordova .
5. Нажмите кнопку Добавить новое приложение в правом нижнем углу страницы.
6. Найдите секрет приложения на странице параметров проекта приложения. Откройте меню в правом верхнем углу страницы, а затем выберите элемент Копировать секрет приложения , чтобы скопировать секрет приложения в буфер обмена.

3. Добавление пакета SDK центра приложений в проект

Установка пакета SDK

Для проектов Apache Cordova пакет SDK распространяется через стандартные подключаемые модули Apache Cordova. Добавьте пакет SDK Центра приложений в проект Cordova, следуя инструкциям, приведенным в этом разделе. Начните с открытия окна терминала или командной строки Windows, а затем перейдите в корневую папку проекта Cordova.

Чтобы добавить поддержку аналитики Центра приложений в проект, выполните следующую команду:

cordova plugin add cordova-plugin-appcenter-analytics

Чтобы добавить в проект поддержку сбоев Центра приложений , выполните следующую команду:

cordova plugin add cordova-plugin-appcenter-crashes

Чтобы добавить подключаемые модули для всех возможностей Центра приложений в проект с помощью одной команды, выполните следующую команду:

cordova plugin add cordova-plugin-appcenter-analytics cordova-plugin-appcenter-crashes

Примечание

Следует добавлять cordova-plugin-appcenter-analytics и cordova-plugin-appcenter-crashes большинство всех приложений, использующих Центр приложений; они предоставляют полезную информацию для разработчиков без дополнительной настройки или написания кода.

Настройка подключаемых модулей

Секрет приложения

Прежде чем использовать пакет SDK центра приложений в проекте Apache Cordova, необходимо настроить проект с помощью секрета приложения центра приложений.

Откройте файл config.xml проекта Apache Cordova; Для каждого из целевых platform элементов проекта Apache Cordova (только для Android и iOS) добавьте дочерний preference элемент в следующем формате:

<preference name="APP_SECRET" value="0000-0000-0000-0000-000000000000" />

В этом примере вы добавляете элемент с атрибутом name со значением APP_SECRET, и value атрибут со значением, показанным в примере. Здесь показанное 0000-0000-0000-0000-000000000000 в примере является произвольным представлением секрета приложения проекта Центра приложений. Замените секрет приложения, показанный в примере, фактическим секретом приложения для проекта Центра приложений.

В качестве полного примера для проекта Apache Cordova, поддерживающего целевые объекты Android и iOS, вы будете иметь отдельные определения проектов приложений в Центре приложений и, таким образом, разные значения секретов приложений для каждой целевой платформы. Соответствующий раздел файла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>

Примечание

В примере не отображаются фактические значения секрета приложения; Это всего лишь макеты. Вам потребуется захватить секреты приложения центра приложений и использовать их здесь. Секреты приложения отличаются, так как у вас будут уникальные секреты для проектов приложений Android и iOS в Центре приложений.

Параметры аналитики

Если вы используете аналитику Центра приложений в приложении, необходимо выполнить некоторые дополнительные действия по настройке. Откройте файл config.xml проекта Apache Cordova в редакторе и добавьте в файл один или несколько следующих preferences элементов:

• APPCENTER_ANALYTICS_ENABLE_IN_JS - (необязательно, по умолчанию — false) Определяет, включается ли аналитика автоматически. Если falseзадано значение , аналитика включена по умолчанию. Если trueзадано значение , приложение должно вызвать AppCenter.Analytics.setEnabled(true) (в коде JavaScript), чтобы включить аналитику перед отправкой данных в Центр приложений. Этот параметр полезен, если вы хотите спросить пользователей, хотите ли они предоставлять доступ к аналитическим сведениям, прежде чем включать их в приложении. Узнайте больше об отправке событий пользователей вручную.

  Пример

  <preference name="APPCENTER_ANALYTICS_ENABLE_IN_JS" value="true" />
  

• APPCENTER_CRASHES_ALWAYS_SEND - (необязательно, значение по умолчанию — true) Указывает, будут ли отчеты о сбоях автоматически отправляться в Центр приложений при сбое приложения. При автоматической отправке отчетов о сбоях сообщается о каждом сбое, что может привести к перегрузке команд инженеров и поддержки. При отправке отчетов о сбоях вручную (для параметра задано значение APPCENTER_CRASHES_ALWAYS_SENDfalse), код в приложении может рассматривать сбои и решать, когда отчеты о сбоях отправляются в Центр приложений, какие данные включаются в отчеты и т. д. Это означает больше работы для разработчика, но также обеспечивает больший контроль над конфиденциальностью пользователей и позволяет вложить сообщение с отчетом о сбоях. Узнайте больше об обработке отчетов о сбоях в JS.

  Пример

  <preference name="APPCENTER_CRASHES_ALWAYS_SEND" value="false" />
  

  Если вы используете автоматическое резервное копирование, чтобы избежать получения неверных сведений об устройствах, выполните следующие действия.

Примечание

Для приложений, предназначенных для Android 6.0 (уровень API 23) или выше, автоматически включено автоматическое резервное копирование. 

Примечание

Если у вас уже есть пользовательский файл с правилом резервного копирования, перейдите к третьему шагу.

а. Создайте appcenter_backup_rule.xml файл в папке res/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 и пошаговым руководствами, чтобы узнать, что может делать Центр приложений.