SDK do cliente 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 a migração.

Saiba mais sobre linhas do tempo e alternativas de suporte.

Esse plug-in fornece integração do lado do cliente para o serviço CodePush, permitindo que você adicione facilmente uma experiência de atualização dinâmica aos seus aplicativos Cordova.

Observação

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

Como ele funciona?

Um aplicativo Cordova é composto por arquivos HTML, CSS e JavaScript e quaisquer imagens que acompanham, que são agrupadas pela CLI cordova e distribuídas como parte de um binário específico da plataforma (ou seja, um arquivo .ipa ou .apk). Depois que o aplicativo for lançado, atualizar o código ou os ativos de imagem exigirá que você recompile e redistribua todo o binário. Esse processo inclui tempo de revisão para os repositórios nos quais você está publicando.

O plug-in CodePush ajuda a obter melhorias no produto na frente dos usuários finais instantaneamente, mantendo seu código e imagens sincronizados com as atualizações lançadas no servidor CodePush. Dessa forma, seu aplicativo obtém os benefícios de uma experiência móvel offline, bem como a agilidade "semelhante à Web" de atualizações de sideload assim que elas estiverem disponíveis. Isso é vantajoso para todos!

Para garantir que os usuários finais sempre tenham uma versão funcional do aplicativo, o plug-in CodePush mantém uma cópia da atualização anterior, para que, caso você envie acidentalmente uma atualização que inclua uma falha, ela possa reverter automaticamente. Dessa forma, você pode ter certeza de que sua nova agilidade de versão não fará com que os usuários fiquem bloqueados antes que você tenha a chance de reverter no servidor. É um ganha-ganha-ganha!

Observação

Quaisquer alterações de produto que toquem no código nativo (por exemplo, atualizar versões do Cordova, adicionar um novo plug-in) não podem ser distribuídas por meio do CodePush e, portanto, devem ser atualizadas por meio dos repositórios apropriados.

Plataformas Cordova com suporte

O Cordova 5.0.0+ tem suporte total, juntamente com as seguintes plataformas associadas:

Para marcar as versões de cada plataforma Cordova que você está usando no momento, execute o seguinte comando e inspecione a Installed platforms lista:

    cordova platform ls

Se você estiver executando uma plataforma Android ou iOS mais antiga do que o mencionado acima e estiver aberto à atualização, poderá fazer isso facilmente executando os seguintes comandos (omitindo uma plataforma se não for necessário):

    cordova platform update android
    cordova platform update ios

Introdução

Observação

Este artigo contém referências ao termo lista de permissões, um termo que a Microsoft não usa mais. Quando o termo for removido do software, também o removeremos deste artigo.

Depois de seguir as instruções de "introdução" de uso geral para configurar sua conta do CodePush, você poderá iniciar a codificação do aplicativo Cordova executando o seguinte comando no diretório raiz do aplicativo:

cordova plugin add cordova-plugin-code-push@latest

Com o plug-in CodePush instalado, configure seu aplicativo para usá-lo por meio das seguintes etapas:

  1. Adicione suas chaves de implantação ao arquivo config.xml , certificando-se de incluir a chave certa para cada plataforma cordova:
    <platform name="android">
        <preference name="CodePushDeploymentKey" value="YOUR-ANDROID-DEPLOYMENT-KEY" />
    </platform>
    <platform name="ios">
        <preference name="CodePushDeploymentKey" value="YOUR-IOS-DEPLOYMENT-KEY" />
    </platform>

Como lembrete, essas chaves são geradas para você quando você criou seu aplicativo CodePush por meio da CLI. Se você precisar recuperá-los, poderá executar appcenter codepush deployment list -a <ownerName>/<appName> --displayKeyse pegar a chave para a implantação específica que deseja usar (por exemplo Staging, , Production).

Importante

É recomendável criar um aplicativo CodePush separado para iOS e Android, razão pela qual o exemplo acima declara chaves separadas para Android e iOS. Se você estiver desenvolvendo apenas para uma única plataforma, só precisará especificar a chave de implantação para Android ou iOS, portanto, não será necessário adicionar o elemento adicional <platform> , conforme ilustrado acima.

A partir da versão 1.10.0 , você pode assinar seus pacotes de atualização (para obter mais informações sobre assinatura de código, consulte a seção de documentação relevante). Para habilitar a assinatura de código para um aplicativo Cordova, você deve configurar uma chave pública para verificar a assinatura do pacote, fornecendo a preference seguinte configuração em config.xml:

    <platform name="android">
        ...
        <preference name="CodePushPublicKey" value="YOUR-PUBLIC-KEY" />
    </platform>
    <platform name="ios">
        ...
        <preference name="CodePushPublicKey" value="YOUR-PUBLIC-KEY" />
    </platform>

Você pode usar o mesmo par de chaves públicas/privadas para cada plataforma.

  1. Se você estiver usando um <access origin="*" /> elemento em seu arquivo config.xml , seu aplicativo já tem permissão para se comunicar com os servidores CodePush e você pode ignorar essa etapa com segurança. Caso contrário, adicione os seguintes elementos adicionais <access /> :
    <access origin="https://codepush.appcenter.ms" />
    <access origin="https://codepush.blob.core.windows.net" />
    <access origin="https://codepushupdates.azureedge.net" />
  1. Para garantir que seu aplicativo possa acessar o servidor CodePush em plataformas compatíveis com CSP, adicione https://codepush.appcenter.ms à Content-Security-Policymeta marca em seu index.html arquivo:
    <meta http-equiv="Content-Security-Policy" content="default-src https://codepush.appcenter.ms 'self' data: gap: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *" />
  1. Por fim, marcar duas vezes que você já tem o plug-in instalado (a cordova-plugin-whitelist maioria dos aplicativos o fará). Para marcar isso, execute o seguinte comando:
    cordova plugin ls

Se cordova-plugin-whitelist estiver na lista, você estará pronto para ir. Caso contrário, execute o seguinte comando para adicioná-lo:

    cordova plugin add cordova-plugin-whitelist

Agora você está pronto para usar o plug-in no código do aplicativo. Consulte os aplicativos de exemplo para obter exemplos e a documentação da API para obter mais detalhes.

Uso do plug-in

Com o plug-in CodePush instalado e configurado, a única coisa que resta é adicionar o código necessário ao seu aplicativo para controlar as seguintes políticas:

  1. Quando (e com que frequência) marcar para uma atualização? (e.g. app iniciar, em resposta ao clique em um botão em uma página de configurações, periodicamente em algum intervalo fixo)
  2. Quando uma atualização está disponível, como apresentá-la ao usuário final? A maneira mais simples de fazer isso é executar o seguinte no manipulador de eventos do deviceready aplicativo:
codePush.sync();

Se uma atualização estiver disponível, ela será baixada silenciosamente e instalada na próxima vez que o aplicativo for reiniciado (explicitamente pelo usuário final ou pelo sistema operacional), o que garante a experiência menos invasiva para os usuários finais. Se uma atualização disponível for obrigatória, ela será instalada imediatamente, garantindo que o usuário final a receba o mais rápido possível.

Se você quiser que seu aplicativo descubra atualizações mais rapidamente, também poderá optar por chamar sync sempre que o aplicativo for retomado em segundo plano, adicionando o código a seguir (ou algo equivalente) como parte do comportamento de inicialização do aplicativo. Você pode chamar sync com a frequência que quiser, portanto, quando e onde você chama isso depende de sua preferência pessoal.

document.addEventListener("resume", function () {
    codePush.sync();
});

Além disso, se você quiser exibir uma caixa de diálogo de confirmação de atualização (uma "instalação ativa"), configure quando uma atualização disponível estiver instalada (por exemplo, forçar uma reinicialização imediata) ou personalizar a experiência de atualização de qualquer maneira, consulte a sync referência de API do método para obter informações sobre como ajustar esse comportamento padrão.

Importante

Embora o contrato de desenvolvedor da Apple permita totalmente atualizações over-the-air de JavaScript e ativos (que é o que permite o CodePush!), é contra sua política para um aplicativo exibir um prompt de atualização. Por isso, recomendamos que App Store aplicativos distribuídos não habilitem a opção updateDialog ao chamar sync, enquanto o Google Play e aplicativos distribuídos internamente (por exemplo, Enterprise, Fabric, HockeyApp) podem optar por habilitá-lo/personalizá-lo.

Liberando Atualizações

Depois que o aplicativo tiver sido configurado e distribuído aos usuários e você tiver feito algumas alterações de código ou ativo, é hora de liberá-los instantaneamente! A maneira mais simples (e recomendada) de fazer isso é usar o release-cordova comando na CLI do CodePush, que lida com a preparação e liberação da atualização para o servidor CodePush.

Observação

Antes de começar a liberar atualizações, faça logon no App Center executando o appcenter login comando

Em sua forma mais básica, esse comando requer apenas um parâmetro: seu nome de proprietário + "/" + nome do aplicativo.

appcenter codepush release-cordova -a <ownerName>/<appName>
appcenter codepush release-cordova -a <ownerName>/MyApp-ios
appcenter codepush release-cordova -a <ownerName>/MyApp-android

Dica

Usando a função CLI set-current do App Center, você não precisa usar o sinalizador -a para especificar o aplicativo no qual um comando é direcionado.

Dica

Ao liberar atualizações para o CodePush, você não precisa aumentar a versão do aplicativo no arquivo config.xml , pois não está modificando a versão binária. Você só precisa aumentar essa versão ao atualizar o Cordova ou um de seus plug-ins, nesse ponto, você precisa liberar uma atualização para os repositórios nativos. O CodePush gerará automaticamente um "rótulo" para cada versão que você fizer (por exemplo v3, ) para ajudar a identificá-lo no histórico de lançamentos.

O release-cordova comando habilita um fluxo de trabalho tão simples porque entende o layout padrão de um aplicativo Cordova e, portanto, pode gerar sua atualização e saber exatamente quais arquivos carregar. Além disso, para dar suporte a estratégias de versão flexíveis, o release-cordova comando expõe vários parâmetros opcionais que permitem personalizar como a atualização deve ser distribuída aos usuários finais (por exemplo, quais versões binárias são compatíveis com ela? A versão deve ser exibida como obrigatória?).

# Release a mandatory update with a changelog
appcenter codepush release-cordova -a <ownerName>/MyApp-ios -m --description "Modified the header color"

# Release a dev Android build to 1/4 of your end users
appcenter codepush release-cordova -a <ownerName>/MyApp-android --rollout 25

# Release an update that targets users running any 1.1.* binary, as opposed to
# limiting the update to exact version name in the config.xml file
appcenter codepush release-cordova -a <ownerName>/MyApp-android --target-binary-version "~1.1.0"

# Release the update now but mark it as disabled
# so that no users can download it yet
appcenter codepush release-cordova -a <ownerName>/MyApp-ios -x

O cliente CodePush dá suporte a atualizações diferenciais, portanto, mesmo que você esteja liberando o código do aplicativo em cada atualização, os usuários finais só baixarão os arquivos necessários. O serviço lida com isso automaticamente para que você possa se concentrar na criação de aplicativos incríveis e podemos nos preocupar em otimizar os downloads do usuário final.

Para obter mais detalhes sobre como o release-cordova comando funciona, bem como os vários parâmetros que ele expõe, consulte os documentos da CLI. Além disso, se você preferir manipular a execução do cordova prepare comando por conta própria e, portanto, quiser uma solução ainda mais flexível do que release-cordova, consulte o release comando para obter mais detalhes.

Se você tiver problemas ou tiver dúvidas/comentários/comentários, poderá nos enviar um email ou abrir um novo problema neste repositório e responderemos o mais rápido possível! Consulte também ajuda e comentários.

Referência de API

A API CodePush é exposta ao seu aplicativo por meio do objeto global codePush , que está disponível após o deviceready evento ser acionado. Essa API expõe os seguintes métodos de nível superior:

  • checkForUpdate: pergunta ao serviço CodePush se a implantação de aplicativo configurada tem uma atualização disponível.
  • getCurrentPackage: recupera os metadados sobre a atualização instalada no momento (por exemplo, descrição, tempo de instalação, tamanho).
  • getPendingPackage: recupera os metadados de uma atualização (se houver uma) que foi baixada e instalada, mas ainda não foi aplicada por meio de uma reinicialização.
  • notifyApplicationReady: notifica o runtime do CodePush de que uma atualização instalada é considerada bem-sucedida. Se você estiver verificando manualmente e instalando atualizações (ou seja, não usando o método de sincronização para lidar com tudo isso para você), esse método DEVE ser chamado; caso contrário, o CodePush tratará a atualização como com falha e reverterá para a versão anterior quando o aplicativo for reiniciado.
  • restartApplication: reinicia imediatamente o aplicativo. Se houver uma atualização pendente, ela será exibida imediatamente para o usuário final.
  • sincronização: permite verificar uma atualização, baixá-la e instalá-la, tudo com uma única chamada. A menos que você precise de interface do usuário ou comportamento personalizado, recomendamos que a maioria dos desenvolvedores use esse método ao integrar o CodePush em seus aplicativos.

Além disso, os seguintes objetos e enumerações também são expostos globalmente como parte da API CodePush:

  • InstallMode: define os modos de instalação disponíveis para atualizações.
  • LocalPackage: contém informações sobre um pacote instalado localmente.
  • RemotePackage: contém informações sobre um pacote de atualização disponível para download.
  • SyncStatus: define os possíveis status intermediário e de resultado da operação de sincronização .

codePush.checkForUpdate

codePush.checkForUpdate(onSuccess, onError?, deploymentKey?: String);

Consulta o serviço CodePush para ver se a implantação do aplicativo configurado tem uma atualização disponível. Por padrão, ele usará a chave de implantação configurada em seu arquivo config.xml , mas você pode substituí-la especificando um valor por meio do parâmetro opcional deploymentKey . Isso pode ser útil quando você deseja "redirecionar" dinamicamente um usuário para uma implantação específica, como permitir "Acesso antecipado" por meio de um easter egg ou uma opção de configuração do usuário.

Quando a atualização marcar for concluída, ela disparará o onUpdateCheck retorno de chamada com um dos dois valores possíveis:

  1. null se não houver nenhuma atualização disponível. Isso ocorre nos seguintes cenários:
    • A implantação configurada não contém nenhuma versão, portanto, não há nada a ser atualizado.
    • A versão mais recente na implantação configurada tem como destino uma versão binária diferente da que você está executando no momento (mais antiga ou mais recente).
    • O aplicativo em execução no momento já tem a versão mais recente da implantação configurada, portanto, ele não precisa da versão novamente.
  2. Uma RemotePackage instância que representa uma atualização disponível que pode ser inspecionada e baixada posteriormente.

Parâmetros:

  • onSuccess: retorno de chamada invocado ao receber uma resposta bem-sucedida do servidor. O retorno de chamada recebe um único parâmetro, que é descrito acima.
  • onError: retorno de chamada opcional que é invocado no caso de um erro. O retorno de chamada usa um parâmetro de erro, contendo os detalhes do erro.
  • deploymentKey: chave de implantação opcional que substitui a configuração deconfig.xml .

Exemplo de uso:

codePush.checkForUpdate(function (update) {
    if (!update) {
        console.log("The app is up to date.");
    } else {
        console.log("An update is available! Should we download it?");
    }
});

codePush.getCurrentPackage

codePush.getCurrentPackage(onSuccess, onError?);

Recupera os metadados sobre o "pacote" atualmente instalado (por exemplo, descrição, hora da instalação). Isso pode ser útil para cenários como exibir uma caixa de diálogo "novidades?" depois que uma atualização foi aplicada ou verificar se há uma atualização pendente que está aguardando para ser aplicada por meio de um currículo ou reinicialização.

Quando a recuperação de atualização for concluída, ela disparará o onSuccess retorno de chamada com um dos dois valores possíveis:

  1. null se o aplicativo estiver executando atualmente a página inicial html do binário e não uma atualização codePush. Isso ocorre nos seguintes cenários:
    • O usuário final instalou o binário do aplicativo e ainda não instalou uma atualização do CodePush
    • O usuário final instalou uma atualização do binário (por exemplo, do repositório), que limpou as atualizações antigas do CodePush e deu precedência de volta ao binário.
  2. Uma LocalPackage instância que representa os metadados para a atualização CodePush em execução no momento.

Parâmetros:

  • onSuccess: retorno de chamada invocado ao receber os metadados sobre a atualização em execução no momento. O retorno de chamada recebe um único parâmetro, que é descrito acima.
  • onError: retorno de chamada opcional que é invocado no caso de um erro. O retorno de chamada usa um parâmetro de erro, contendo os detalhes do erro.

Uso de exemplo:

codePush.getCurrentPackage(function (update) {
    if (!update) {
        console.log("No updates have been installed");
        return;
    }

    // If the current app "session" represents the first time
    // this update has run, and it had a description provided
    // with it upon release, let's show it to the end user
    if (update.isFirstRun && update.description) {
        // Display a "what's new?" modal
    }
});

codePush.getPendingPackage

codePush.getPendingPackage(onSuccess, onError?);

Obtém os metadados para a atualização pendente no momento (se houver). Uma atualização será considerada "pendente" se tiver sido baixada e instalada, mas ainda não tiver sido aplicada por meio de uma reinicialização do aplicativo. Uma atualização só poderá estar nesse estado se InstallMode.ON_NEXT_RESTART ou InstallMode.ON_NEXT_RESUME tiver sido especificada ao chamar sync ou LocalPackage.installe o aplicativo ainda não tiver sido reiniciado ou retomado (respectivamente). Esse método pode ser útil se você quiser determinar se há uma atualização pendente e, em seguida, solicitar ao usuário se ele deseja reiniciar imediatamente (via codePush.restartApplication) para aplicá-la.

Quando a recuperação de atualização for concluída, ela disparará o onSuccess retorno de chamada com um dos dois valores possíveis:

  1. null se o aplicativo não tiver atualmente uma atualização pendente (por exemplo, o aplicativo já está executando a versão mais recente disponível).
  2. Uma LocalPackage instância que representa os metadados para a atualização codePush atualmente pendente.

Parâmetros:

  • onSuccess: retorno de chamada invocado ao receber os metadados sobre a atualização atualmente pendente. O retorno de chamada recebe um único parâmetro, que é descrito acima.
  • onError: retorno de chamada opcional que é invocado no caso de um erro. O retorno de chamada usa um parâmetro de erro, contendo os detalhes do erro.

Uso de exemplo:

codePush.getPendingPackage(function (update) {
    if (update) {
        // An update is currently pending, ask the
        // user if they want to restart
    }
});

codePush.notifyApplicationReady

codePush.notifyApplicationReady(notifySucceeded?, notifyFailed?);

Notifica o runtime do CodePush de que uma atualização recém-instalada deve ser considerada bem-sucedida, portanto, uma reversão automática do lado do cliente não é necessária. É obrigatório chamar essa função em algum lugar no código do pacote atualizado. Caso contrário, quando o aplicativo for reiniciado, o runtime do CodePush assumirá que a atualização instalada falhou e reverterá para a versão anterior. Esse comportamento existe para ajudar a garantir que os usuários finais não sejam bloqueados por uma atualização interrompida.

Se você estiver usando a sync função e fazendo a atualização marcar no início do aplicativo, não será necessário chamar notifyApplicationReadysync manualmente, pois a chamará para você. Esse comportamento existe devido à suposição de que quando sync é chamado em seu aplicativo representa uma boa aproximação de uma inicialização bem-sucedida.

Parâmetros:

  • notifySucceeded: retorno de chamada opcional invocado se o plug-in foi notificado com êxito.
  • notifyFailed: retorno de chamada opcional invocado se houver um erro notificando o plug-in.

codePush.restartApplication

codePush.restartApplication();

Reinicia imediatamente o aplicativo. Esse método é para cenários avançados e é útil principalmente quando as seguintes condições são verdadeiras:

  1. Seu aplicativo está especificando um valor de modo de instalação de ON_NEXT_RESTART ou ON_NEXT_RESUME ao chamar os sync métodos ou LocalPackage.install . Isso não aplica a atualização até que o aplicativo seja reiniciado (pelo usuário final ou pelo sistema operacional) ou seja retomado, portanto, a atualização não será exibida imediatamente para o usuário final.
  2. Você tem um evento de usuário específico do aplicativo (por exemplo, o usuário final navegou de volta para a rota inicial do aplicativo) que permite aplicar a atualização de maneira discreta e, potencialmente, obtém a atualização na frente do usuário final mais cedo do que esperar até a próxima reinicialização ou retomada.

codePush.sync

codePush.sync(syncCallback?, syncOptions?, downloadProgress?, syncErrback?);

Sincroniza o código e as imagens do aplicativo com a versão mais recente para a implantação configurada. Ao contrário do checkForUpdate método , que verifica a presença de uma atualização e permite controlar o que fazer em seguida, sync lida com a atualização marcar, a experiência de download e instalação para você.

Esse método fornece suporte para dois "modos" diferentes (mas personalizáveis) para habilitar facilmente aplicativos com requisitos diferentes:

  1. Modo silencioso(o comportamento padrão), que baixa automaticamente as atualizações disponíveis e as aplica na próxima vez que o aplicativo for reiniciado (por exemplo, o sistema operacional ou o usuário final o matou ou o dispositivo foi reiniciado). Dessa forma, toda a experiência de atualização é "silenciosa" para o usuário final, pois ele não vê nenhuma solicitação de atualização ou reinicializações do aplicativo "sintético".
  2. O modo ativo, que quando uma atualização está disponível, solicita permissão ao usuário final antes de baixá-la e, em seguida, aplica imediatamente a atualização. Se uma atualização fosse lançada usando o sinalizador obrigatório, o usuário final ainda seria notificado sobre a atualização, mas não teria a opção de ignorá-la.

Uso de exemplo:

// Fully silent update that keeps the app in
// sync with the server, without ever
// interrupting the end user
codePush.sync();

// Active update that lets the end user know
// about each update, and displays it to them
// immediately after downloading it
codePush.sync(null, { updateDialog: true, installMode: InstallMode.IMMEDIATE });

Dica

Se você quiser decidir se marcar ou baixar uma atualização disponível com base no nível da bateria do dispositivo do usuário final, nas condições de rede etc. em seguida, encapsule a chamada para sincronizar em uma condição que garanta que você a chame apenas quando desejado.

Embora o método de sincronização tente facilitar a execução de atualizações silenciosas e ativas com pouca configuração, ele aceita os seguintes parâmetros opcionais que permitem personalizar vários aspectos do comportamento padrão mencionado acima:

  • syncCallback: chamado quando o processo de sincronização passa de um estágio para outro no processo geral de atualização. O método é chamado com um código status que representa o estado atual e pode ser qualquer um dos SyncStatus valores.
  • syncOptions: parâmetro opcional SyncOptions que configura o comportamento da operação de sincronização.
  • downloadProgress: chamado periodicamente quando uma atualização disponível está sendo baixada do servidor CodePush. O método é chamado com um DownloadProgress objeto , que contém as duas propriedades a seguir:
    • totalBytes(Number) – o número total de bytes esperados para esta atualização (ou seja, o tamanho do conjunto de arquivos que foi alterado da versão anterior).
    • receivedBytes(Number) – o número de bytes baixados até agora, que pode ser usado para acompanhar o progresso do download.
  • syncErrback: chamado quando há um erro em qualquer uma das etapas internas de sincronização. O método é chamado com um objeto javascript Error padrão como primeiro argumento.

SyncOptions

Embora o sync método tente facilitar a execução de atualizações silenciosas e ativas com pouca configuração, ele aceita um objeto "options" que permite personalizar vários aspectos do comportamento padrão mencionado acima:

  • deploymentKey(String) – especifica a chave de implantação na qual você deseja consultar uma atualização. Por padrão, esse valor é derivado do arquivo config.xml , mas essa opção permite substituí-lo do lado do script se você precisar usar dinamicamente uma implantação diferente para uma chamada específica para sync.
  • installMode(InstallMode) – especifica quando você deseja instalar atualizações opcionais (ou seja, aquelas que não estão marcadas como obrigatórias). Assume o padrão de InstallMode.ON_NEXT_RESTART. Consulte a referência de InstallMode enumeração para obter uma descrição das opções disponíveis e o que elas fazem.
  • mandatoryInstallMode(InstallMode) – especifica quando você deseja instalar atualizações marcadas como obrigatórias. Assume o padrão de InstallMode.IMMEDIATE. Consulte a referência de InstallMode enumeração para obter uma descrição das opções disponíveis e o que elas fazem.
  • minimumBackgroundDuration(Number) – especifica o número mínimo de segundos para o aplicativo estar em segundo plano antes de reiniciar o aplicativo. Essa propriedade só se aplica a atualizações instaladas usando InstallMode.ON_NEXT_RESUMEo e pode ser útil para obter sua atualização na frente dos usuários finais mais cedo, sem ser muito obtrusiva. O padrão é 0, que aplica a atualização imediatamente após um currículo, por mais tempo que tenha estado em segundo plano.
  • ignoreFailedUpdates(Boolean) – especifica se uma atualização disponível deve ser ignorada se ela tiver sido instalada anteriormente e revertida no cliente (porque notifyApplicationReady não foi chamada com êxito). Assume o padrão de true.
  • updateDialog(UpdateDialogOptions) – Um objeto de "opções" usado para determinar se uma caixa de diálogo de confirmação deve ser exibida para o usuário final quando uma atualização estiver disponível e, em caso afirmativo, quais cadeias de caracteres usar. O padrão é , que desabilita nulla caixa de diálogo. Definir isso como qualquer true valor habilitará a caixa de diálogo com as cadeias de caracteres padrão e passar um objeto para esse parâmetro permite habilitar a caixa de diálogo, bem como substituir uma ou mais das cadeias de caracteres padrão.

A lista a seguir representa as opções disponíveis e seus padrões:

  • appendReleaseDescription(Boolean) – Indica se você deseja acrescentar a descrição de uma versão disponível à mensagem de notificação exibida ao usuário final. Assume o padrão de false.
  • descriptionPrefix(String) – indica a cadeia de caracteres com a qual você deseja prefixar a descrição da versão, se houver, ao exibir a notificação de atualização para o usuário final. Assume o padrão de " Description: ".
  • mandatoryContinueButtonLabel(String): o texto a ser usado para o botão que o usuário final deve pressionar para instalar uma atualização obrigatória. Assume o padrão de "Continue".
  • mandatoryUpdateMessage(String) – o texto usado como o corpo de uma notificação de atualização, quando a atualização é especificada como obrigatória. Assume o padrão de "An update is available that must be installed.".
  • optionalIgnoreButtonLabel(String) – o texto a ser usado para o botão que o usuário final pode pressionar para ignorar uma atualização opcional disponível. Assume o padrão de "Ignore".
  • optionalInstallButtonLabel(String) – o texto a ser usado para o botão que o usuário final pode pressionar para instalar uma atualização opcional. Assume o padrão de "Install".
  • optionalUpdateMessage(String) – o texto usado como o corpo de uma notificação de atualização, quando a atualização é opcional. Assume o padrão de "An update is available. Would you like to install it?". *- updateTitle(String) – o texto usado como o cabeçalho de uma notificação de atualização exibida para o usuário final. Assume o padrão de "Update available".

Uso de exemplo:

// Download the update silently, but install it on
// the next resume, as long as at least 5 minutes
// has passed since the app was put into the background.
codePush.sync(null, { installMode: InstallMode.ON_NEXT_RESUME, minimumBackgroundDuration: 60 * 5 });

// Download the update silently, and install optional updates
// on the next restart, but install mandatory updates on the next resume.
codePush.sync(null, { mandatoryInstallMode: InstallMode.ON_NEXT_RESUME });

// Changing the title displayed in the
// confirmation dialog of an "active" update
codePush.sync(null, { updateDialog: { title: "An update is available!" } });

// Displaying an update prompt that includes the
// description for the CodePush release
codePush.sync(null, {
   updateDialog: {
    appendReleaseDescription: true,
    descriptionPrefix: "\n\nChange log:\n"
   },
   installMode: InstallMode.IMMEDIATE
});

// Silently check for the update, but
// display a custom downloading UI
// via the SyncStatus and DownloadProgress callbacks
codePush.sync(syncStatus, null, downloadProgress);

function syncStatus(status) {
    switch (status) {
        case SyncStatus.DOWNLOADING_PACKAGE:
            // Show "downloading" modal
            break;
        case SyncStatus.INSTALLING_UPDATE:
            // Hide "downloading" modal
            break;
    }
}

function downloadProgress(downloadProgress) {
    if (downloadProgress) {
    	// Update "downloading" modal with current download %
        //console.log("Downloading " + downloadProgress.receivedBytes + " of " + downloadProgress.totalBytes);
    }
}

O sync método pode ser chamado em qualquer lugar que você queira marcar para uma atualização. Isso pode estar no deviceready manipulador de eventos, no click evento de um botão, no retorno de chamada de um temporizador periódico ou qualquer outra coisa que faça sentido para suas necessidades. Assim como o checkForUpdate método , ele executará a solicitação de rede para marcar para uma atualização em segundo plano, portanto, ela não afetará a capacidade de resposta do thread da interface do usuário ou do thread JavaScript.

Objetos de pacote

Os checkForUpdate métodos e getCurrentPackage invocam retornos de chamada bem-sucedidos, que, quando disparados, fornecem acesso a objetos "package". O pacote representa a atualização de código, bem como os metadados extras (por exemplo, descrição, obrigatório?). A API CodePush tem a distinção entre os seguintes tipos de pacotes:

  1. LocalPackage: representa uma atualização baixada que já está em execução ou foi instalada e está pendente de uma reinicialização do aplicativo.
  2. RemotePackage: representa uma atualização disponível no servidor CodePush que ainda não foi baixada.

LocalPackage

Contém detalhes sobre uma atualização que foi baixada localmente ou já instalada. Você pode obter uma referência a uma instância desse objeto chamando o codePush.getCurrentPackage método ou como o valor fornecido para o retorno de chamada de êxito do RemotePackage.download método .

Propriedades
  • appVersion: a versão nativa do aplicativo para a qual esta atualização de pacote se destina. (Cadeia de caracteres)
  • deploymentKey: chave de implantação do pacote. (Cadeia de caracteres)
  • descrição: a descrição da atualização. Esse é o mesmo valor que você especificou na CLI quando lançou a atualização. (Cadeia de caracteres)
  • failedInstall: indica se essa atualização foi instalada anteriormente, mas foi revertida. O sync método ignorará automaticamente as atualizações que falharam anteriormente, portanto, você só precisará se preocupar com essa propriedade se estiver usando checkForUpdate. (Boolean)
  • isFirstRun: sinalizador que indica se a execução do aplicativo atual é a primeira após a aplicação do pacote. (Boolean)
  • isMandatory: indica se a atualização é considerada obrigatória. Esse é o valor especificado na CLI quando a atualização foi lançada. (Boolean)
  • label: o rótulo interno automaticamente dado à atualização pelo servidor CodePush, como v5. Esse valor identifica exclusivamente a atualização em sua implantação. (Cadeia de caracteres)
  • packageHash: o valor de hash SHA da atualização. (Cadeia de caracteres)
  • packageSize: o tamanho do código contido na atualização, em bytes. (Número)
Métodos
  • install(installSuccess, installError, installOptions): instala esse pacote no aplicativo. O comportamento de instalação depende do fornecido installOptions. Por padrão, o pacote de atualização é instalado silenciosamente e o aplicativo é recarregado com o novo conteúdo na próxima inicialização do aplicativo. Na primeira execução após a atualização, o aplicativo aguardará uma codePush.notifyApplicationReady() chamada. Depois que essa chamada é feita, a operação de instalação é considerada um sucesso. Caso contrário, a operação de instalação será marcada como com falha e o aplicativo será revertido para sua versão anterior na próxima execução.
InstallOptions

Interface que define várias opções para personalizar o comportamento da operação de instalação.

  • installMode: usado para especificar o InstallMode usado para a operação de instalação. Assume o padrão de InstallMode.ON_NEXT_RESTART.
  • mandatoryInstallMode: usado para especificar o InstallMode usado para a operação de instalação se o pacote for obrigatório. Assume o padrão de InstallMode.IMMEDIATE.
  • minimumBackgroundDuration: se installMode for InstallMode.ON_NEXT_RESUME, usado para especificar a quantidade de tempo que o aplicativo deve estar em segundo plano antes que a atualização seja instalada quando for retomada. Assume o padrão de 0.

Uso de exemplo:

// App version 1 (current version)

var onError = function (error) {
    console.log("An error occurred. " + error);
};

var onInstallSuccess = function () {
    console.log("Installation succeeded.");
};

var onPackageDownloaded = function (localPackage) {
    // Install regular updates after someone navigates away from the app for more than 2 minutes
    // Install mandatory updates after someone restarts the app
    localPackage.install(onInstallSuccess, onError, { installMode: InstallMode.ON_NEXT_RESUME, minimumBackgroundDuration: 120, mandatoryInstallMode: InstallMode.ON_NEXT_RESTART });
};

var onUpdateCheck = function (remotePackage) {
    if (!remotePackage) {
        console.log("The application is up to date.");
    } else {
        // The hash of each previously reverted package is stored for later use.
        // This way, we avoid going into an infinite bad update/revert loop.
        if (!remotePackage.failedInstall) {
            console.log("A CodePush update is available. Package hash: " + remotePackage.packageHash);
            remotePackage.download(onPackageDownloaded, onError);
        } else {
            console.log("The available update was attempted before and failed.");
        }
    }
};

window.codePush.checkForUpdate(onUpdateCheck, onError);

//------------------------------------------------
// App version 2 (updated version)
var app = {
    onDeviceReady: function () {
        // Calling this function is required during the first application run after an update.
        // If not called, the application will be reverted to the previous version.
        window.codePush.notifyApplicationReady();
        // ...
    }
}

Para obter um exemplo de como você está protegido contra uma atualização incorreta, consulte a documentação notifyApplicationReady().

RemotePackage

Contém detalhes sobre uma atualização disponível para download no servidor CodePush. Você obtém uma referência a uma instância desse objeto chamando o codePush.checkForUpdate método quando uma atualização está disponível. Se você estiver usando a API de sincronização, não precisará se preocupar com o RemotePackage, pois ele manipulará o processo de download e instalação automaticamente para você.

Propriedades

O RemotePackage herda todas as mesmas propriedades que o LocalPackage, mas inclui outra:

  • downloadUrl: a URL em que o pacote está disponível para download. Essa propriedade só é necessária para uso avançado, pois o download método manipulará automaticamente a aquisição de atualizações para você. (Cadeia de caracteres)
Métodos
  • abortDownload(abortSuccess, abortError): anula a sessão de download atual, se houver.
  • download(downloadSuccess, downloadError, downloadProgress): baixa a atualização do pacote do serviço CodePush. O downloadSuccess retorno de chamada é invocado com um argumento LocalPackage , representando o pacote baixado. O retorno de chamada opcional downloadProgress é invocado várias vezes durante o progresso do download com um DownloadProgress parâmetro.
DownloadProgress

Define o formato do objeto DownloadProgress, usado para enviar notificações de atualização periódicas sobre o andamento do download da atualização.

Propriedades
  • totalBytes: o tamanho do pacote de atualização de download, em bytes. (Número)
  • receivedBytes: o número de bytes já baixados. (Número)

Uso de exemplo:

var onError = function (error) {
    console.log("An error occurred. " + error);
};

var onPackageDownloaded = function (localPackage) {
    console.log("Package downloaded at: " + localPackage.localPath);
    // you can now update your application to the downloaded version by calling localPackage.install()
};

var onProgress = function (downloadProgress) {
    console.log("Downloading " + downloadProgress.receivedBytes + " of " + downloadProgress.totalBytes + " bytes.");
};

var onUpdateCheck = function (remotePackage) {
    if (!remotePackage) {
        console.log("The application is up to date.");
    } else {
        console.log("A CodePush update is available. Package hash: " + remotePackage.packageHash);
        remotePackage.download(onPackageDownloaded, onError, onProgress);
    }
};

window.codePush.checkForUpdate(onUpdateCheck, onError);

Enumerações

A API CodePush inclui os seguintes objetos "enum" que podem ser usados para personalizar a experiência de atualização e estão disponíveis globalmente fora do window objeto:

InstallMode

Essa enumeração especificada quando você deseja que uma atualização instalada seja realmente aplicada e pode ser passada para os sync métodos ou LocalPackage.install . Ele inclui os seguintes valores:

  • IMMEDIATE: a atualização será aplicada ao aplicativo em execução imediatamente. O aplicativo será recarregado com o novo conteúdo imediatamente.
  • ON_NEXT_RESTART: indica que você deseja instalar a atualização, mas não reiniciar o aplicativo à força. Quando o aplicativo for reiniciado "naturalmente" (devido ao sistema operacional ou ao usuário final que o está matando), a atualização será selecionada perfeitamente. Esse valor é apropriado ao fazer atualizações silenciosas, pois provavelmente seria disruptivo para o usuário final se o aplicativo fosse reiniciado repentinamente do nada, pois eles não teriam percebido que uma atualização foi baixada. Esse é o modo padrão usado para os sync métodos e LocalPackage.install .

Para obter um exemplo de como você está protegido contra uma atualização incorreta, consulte a documentação notifyApplicationReady().

RemotePackage

Contém detalhes sobre uma atualização disponível para download no servidor CodePush. Você obtém uma referência a uma instância desse objeto chamando o codePush.checkForUpdate método quando uma atualização está disponível. Se você estiver usando a API de sincronização, não precisará se preocupar com o RemotePackage, pois ele manipulará o processo de download e instalação automaticamente para você.

Propriedades

O RemotePackage herda todas as mesmas propriedades que o LocalPackage, mas inclui outra:

  • downloadUrl: a URL em que o pacote está disponível para download. Essa propriedade só é necessária para uso avançado, pois o download método manipulará automaticamente a aquisição de atualizações para você. (Cadeia de caracteres)
Métodos
  • abortDownload(abortSuccess, abortError): anula a sessão de download atual, se houver.
  • download(downloadSuccess, downloadError, downloadProgress): baixa a atualização do pacote do serviço CodePush. O downloadSuccess retorno de chamada é invocado com um argumento LocalPackage , representando o pacote baixado. O retorno de chamada opcional downloadProgress é invocado várias vezes durante o progresso do download com um DownloadProgress parâmetro.
DownloadProgress

Define o formato do objeto DownloadProgress, usado para enviar notificações de atualização periódicas sobre o andamento do download da atualização.

# Propriedades
  • totalBytes: o tamanho do pacote de atualização de download, em bytes. (Número)
  • receivedBytes: o número de bytes já baixados. (Número)

Uso de exemplo:

var onError = function (error) {
    console.log("An error occurred. " + error);
};

var onPackageDownloaded = function (localPackage) {
    console.log("Package downloaded at: " + localPackage.localPath);
    // you can now update your application to the downloaded version by calling localPackage.install()
};

var onProgress = function (downloadProgress) {
    console.log("Downloading " + downloadProgress.receivedBytes + " of " + downloadProgress.totalBytes + " bytes.");
};

var onUpdateCheck = function (remotePackage) {
    if (!remotePackage) {
        console.log("The application is up to date.");
    } else {
        console.log("A CodePush update is available. Package hash: " + remotePackage.packageHash);
        remotePackage.download(onPackageDownloaded, onError, onProgress);
    }
};

window.codePush.checkForUpdate(onUpdateCheck, onError);

Enumerações

A API CodePush inclui os seguintes objetos "enum" que podem ser usados para personalizar a experiência de atualização e estão disponíveis globalmente fora do window objeto:

InstallMode

Essa enumeração especificada quando você deseja que uma atualização instalada seja realmente aplicada e pode ser passada para os sync métodos ou LocalPackage.install . Ele inclui os seguintes valores:

  • IMMEDIATE: a atualização será aplicada ao aplicativo em execução imediatamente. O aplicativo será recarregado com o novo conteúdo imediatamente.
  • ON_NEXT_RESTART: indica que você deseja instalar a atualização, mas não reiniciar o aplicativo à força. Quando o aplicativo for reiniciado "naturalmente" (devido ao sistema operacional ou ao usuário final que o está matando), a atualização será selecionada perfeitamente. Esse valor é apropriado ao fazer atualizações silenciosas, pois provavelmente seria disruptivo para o usuário final se o aplicativo fosse reiniciado repentinamente do nada, pois eles não teriam percebido que uma atualização foi baixada. Esse é o modo padrão usado para os sync métodos e LocalPackage.install .
  • ON_NEXT_RESUME: indica que você deseja instalar a atualização, mas não deseja reiniciar o aplicativo até a próxima vez que o usuário final retomá-lo em segundo plano. Dessa forma, você não interrompe a sessão atual, mas pode obter a atualização na frente delas mais cedo do que ter que esperar pela próxima reinicialização natural. Esse valor é apropriado para instalações silenciosas que podem ser aplicadas no currículo de maneira não invasiva.

Syncstatus

Define os possíveis status da operação de sincronização . Há duas categorias de status: intermediário e resultado (final). Os status intermediários representam status de progresso da operação de sincronização e não são finais. Os status de resultado representam os status finais da operação de sincronização. Cada operação de sincronização termina com apenas um resultado status, mas pode ter zero ou mais status intermediários.

  • UP_TO_DATE: o aplicativo está totalmente atualizado com a implantação configurada.
  • UPDATE_INSTALLED: uma atualização disponível foi instalada e será executada imediatamente após o retorno da função de retorno de chamada ou da próxima vez que o aplicativo for retomado/reiniciado, dependendo do InstallMode especificado em SyncOptions.
  • UPDATE_IGNORED: o aplicativo tem uma atualização opcional, que o usuário final optou por ignorar. (Isso só é aplicável quando o updateDialog é usado)
  • ERRO: ocorreu um erro durante a sync operação. Isso pode ser um erro ao se comunicar com o servidor, baixando ou descompactando a atualização. Os logs do console devem conter mais informações sobre o que aconteceu. Nenhuma atualização foi aplicada neste caso.
  • IN_PROGRESS: outra sincronização já está em execução, portanto, essa tentativa de sincronização foi anulada.
  • CHECKING_FOR_UPDATE: o servidor CodePush está sendo consultado para obter uma atualização.
  • AWAITING_USER_ACTION: uma atualização está disponível e uma caixa de diálogo de confirmação foi mostrada ao usuário final. (Isso só é aplicável quando o updateDialog é usado)
  • DOWNLOADING_PACKAGE: uma atualização disponível está sendo baixada do servidor CodePush.
  • INSTALLING_UPDATE: uma atualização disponível foi baixada e está prestes a ser instalada.

Compilação PhoneGap

Esse plug-in é compatível com o PhoneGap Build e dá suporte à criação de builds do Android e do iOS prontos para uso. No entanto, para que o CodePush calcule o hash do seu conteúdo binário no Android, o PhoneGap Build precisa usar o Gradle para criar seu aplicativo, que não é seu comportamento padrão (ele usa Ant). Para resolve isso, adicione o seguinte elemento ao arquivo config.xml do projeto, como um filho do <platform name="android"> elemento:

<preference name="android-build-tool" value="gradle" />

Aplicativos de exemplo

A comunidade cordova criou graciosamente alguns aplicativos de código aberto incríveis que podem servir como exemplos para desenvolvedores que estão começando. A lista a seguir é de aplicativos OSS Cordova que também estão usando CodePush e podem ser usados para ver como outras pessoas estão usando o serviço:

Observação

Se você desenvolveu um aplicativo Cordova usando CodePush, isso é software livre, informe-nos. Adoraríamos adicioná-lo a esta lista!