Introdução ao Apache Cordova

  • Artigo

Importante

O Visual Studio App Center está programado para ser desativado em 31 de março de 2025. Embora você possa continuar a usar o Visual Studio App Center até que ele seja totalmente desativado, há várias alternativas recomendadas para as quais você pode considerar migrar.

Saiba mais sobre linhas do tempo e alternativas de suporte.

Observação

O suporte para o Cordova Apps terminou em abril de 2022. Encontre mais informações no blog do App Center.

O SDK do App Center usa uma arquitetura modular para que você possa usar facilmente um, vários ou todos os serviços do App Center em seu aplicativo Apache Cordova.

Neste artigo, você aprenderá a adicionar o SDK do App Center aos seus aplicativos Apache Cordova e, em seguida, configurar os recursos de Análise do App Center e Falhas do App Center em um aplicativo.

1. Pré-requisitos

Antes de começar, verifique se o projeto de aplicativo Apache Cordova atende aos seguintes requisitos mínimos:

  • Cordova CLI 6.4.0 ou posterior
  • cordova-android engine 5.0.0 ou posterior
  • cordova-ios engine 4.3.0 ou posterior

Para determinar a versão da CLI do Cordova, abra uma janela do terminal ou um prompt de comando do Windows e execute o seguinte comando:

cordova -v

Para determinar as cordova-android versões e cordova-ios , abra o arquivo config.xml do projeto, você encontrará os mecanismos de plataforma definidos nos engine elementos mostrados abaixo:

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

Você também deve ter o CocoaPods instalado. Para isso, execute sudo gem install cocoapodspod setup

2. Obtendo o segredo do aplicativo do App Center

Para que o SDK do App Center se conecte ao seu projeto de aplicativo no App Center, o SDK precisa do Segredo do Aplicativo do projeto do App Center. Você aprenderá posteriormente como configurar o SDK do Apache Cordova do App Center com esse valor, mas, por enquanto, vamos ver onde encontrá-lo.

Se você tiver um projeto de aplicativo existente do App Center, acesse o Painel do App Center e abra o projeto. Você também pode o segredo do aplicativo na página Configurações do projeto de aplicativo. Acesse o menu no canto superior direito da página e selecione Copiar segredo do aplicativo para copiar o segredo do aplicativo para a área de transferência.

Se você não tiver um aplicativo criado no Painel do App Center, conclua as etapas a seguir.

  1. Registre-se em uma conta do App Center ou faça logon em uma conta existente do App Center em https://appcenter.ms.
  2. No Painel do App Center, clique na lista suspensa Adicionar novo no canto superior direito da página. Selecione Adicionar novo aplicativo no menu.
  3. Insira um nome para seu projeto de aplicativo, adicionando uma descrição opcional conforme necessário.
  4. Selecione o sistema operacional apropriado para seu projeto de aplicativo (somente Android ou iOS) e, em seguida, selecione a opção plataforma Cordova .
  5. Clique no botão Adicionar novo aplicativo no canto inferior direito da página.
  6. Localize o segredo do aplicativo na página Configurações do projeto de aplicativo. Acesse o menu no canto superior direito da página e selecione o item Copiar segredo do aplicativo para copiar o segredo do aplicativo para a área de transferência.

3. Adicionar o SDK do App Center ao projeto

Instalando o SDK

Para projetos do Apache Cordova, o SDK é distribuído por meio de plug-ins apache cordova padrão. Adicione o SDK do App Center ao projeto Cordova usando as instruções fornecidas nesta seção. Comece abrindo uma janela do Terminal ou um prompt de comando do Windows e navegue até a pasta raiz do projeto Cordova.

Para adicionar suporte para Análise do App Center ao seu projeto, execute o seguinte comando:

cordova plugin add cordova-plugin-appcenter-analytics

Para adicionar suporte para falhas do App Center ao seu projeto, execute o seguinte comando:

cordova plugin add cordova-plugin-appcenter-crashes

Para adicionar plug-ins para todos os recursos do App Center ao seu projeto com um comando, execute o seguinte comando:

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

Observação

Você deve adicionar cordova-plugin-appcenter-analytics e cordova-plugin-appcenter-crashes na maioria dos aplicativos que usam o App Center; eles fornecem informações úteis para desenvolvedores sem nenhuma configuração ou codificação adicional.

Configurando os plug-ins

Segredo de Aplicativo

Você deve configurar o projeto com o segredo do aplicativo de projeto do App Center antes de poder usar o SDK do App Center em seu projeto do Apache Cordova.

Abra o arquivo deconfig.xml do projeto Apache Cordova; para cada um dos elementos de destino platform do projeto Apache Cordova (somente Android e iOS hoje), adicione um elemento filho preference no seguinte formato:

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

Neste exemplo, você está adicionando um elemento com um name atributo com um valor de APP_SECRETe um value atributo com o valor mostrado no exemplo. Aqui, o 0000-0000-0000-0000-000000000000 mostrado no exemplo é uma representação arbitrária de um segredo do aplicativo de projeto do App Center. Substitua o segredo do aplicativo mostrado no exemplo pelo segredo real do aplicativo para o projeto do App Center.

Como exemplo completo, para um projeto do Apache Cordova que dá suporte a destinos android e iOS, você terá definições de projeto de aplicativo separadas no App Center e, portanto, valores de segredo de aplicativo diferentes para cada plataforma de destino. A seção relevante do arquivo config.xml do projeto terá a seguinte aparência:

<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>

Observação

O exemplo não mostra valores reais de segredo do aplicativo; são meramente simulações, você precisará pegar os segredos do aplicativo do projeto do App Center e usá-los aqui. Os segredos do aplicativo são diferentes porque você terá segredos exclusivos para seus projetos de aplicativo Android e iOS no App Center.

Preferências de análise

Se você estiver usando a Análise do App Center em seu aplicativo, haverá algumas etapas de configuração adicionais a serem executadas. Abra o arquivo config.xml do projeto Apache Cordova em um editor e adicione um ou mais dos seguintes preferences elementos ao arquivo:

  • APPCENTER_ANALYTICS_ENABLE_IN_JS - (opcional, o padrão é false) Controla se o Analytics está habilitado automaticamente. Quando false, o Analytics é habilitado por padrão. Quando true, o aplicativo deve chamar AppCenter.Analytics.setEnabled(true) (em seu código JavaScript) para habilitar a Análise antes de enviar dados para o App Center. Essa preferência é útil quando você deseja perguntar aos usuários se eles desejam compartilhar informações de análise antes de habilitá-la no aplicativo. Saiba mais sobre como enviar eventos de usuário manualmente.

    Exemplo:

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

  • APPCENTER_CRASHES_ALWAYS_SEND - (opcional, o padrão é true) Especifica se os relatórios de falha são enviados automaticamente para o App Center quando o aplicativo falha. Ao enviar relatórios de falha automaticamente, cada falha é relatada, potencialmente sobrecarregando as equipes de engenharia e suporte. Ao enviar relatórios de falha manualmente (configurando APPCENTER_CRASHES_ALWAYS_SEND como false), o código em seu aplicativo pode fazer a triagem de falhas e decidir quando os relatórios de falha são enviados para o App Center, quais dados estão incluídos nos relatórios e assim por diante. Isso significa mais trabalho para o desenvolvedor, mas também fornece maior controle sobre a privacidade do usuário e permite que você anexe uma mensagem com o relatório de falhas. Saiba mais sobre o processamento em relatórios de falha no JS.

    Exemplo:

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

    Se você usar o backup automático para evitar obter informações incorretas sobre dispositivos, siga as próximas etapas:

Observação

Os aplicativos destinados ao Android 6.0 (nível de API 23) ou superior têm o Backup Automático habilitado automaticamente. 

Observação

Se você já tiver um arquivo personalizado com regra de backup, alterne para a terceira etapa.

a. Crie appcenter_backup_rule.xml arquivo na pasta res/xml .

<resource-file src="appcenter_backup_rule.xml" target="res/xml/appcenter_backup_rule.xml" />

b. Para android:fullBackupContent que o atributo seja adicionado ao elemento dentro de <application>AndroidManifest.xmlarquivo, adicione as seguintes linhas ao arquivo config.xml do aplicativo:

<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. Para onde ir a seguir?

Ótimo, você está pronto para visualizar dados de Análise e Falhas coletados automaticamente pelo SDK no portal. Não há nenhuma configuração adicional necessária. Examine as seções Análise e Falhas para obter guias de APIs e instruções passo a passo para saber o que o App Center pode fazer.