Partilhar via

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

Saiba mais sobre cronogramas 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 do Cordova.

Observação

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

Como funciona?

Um aplicativo Cordova é composto por arquivos HTML, CSS e JavaScript e quaisquer imagens que o acompanham, que são agrupados pela CLI do Cordova e distribuídos como parte de um binário específico da plataforma (ou seja, um arquivo .ipa ou .apk). Depois que o aplicativo é lançado, a atualização do código ou dos ativos de imagem exige que você recompile e redistribua todo o binário. Esse processo inclui o tempo de revisão das lojas nas quais você está publicando.

O plug-in CodePush ajuda a colocar melhorias no produto para seus 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 estão disponíveis. Isso é vantajoso para todos!

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

Observação

Quaisquer alterações de produto que afetem o código nativo (por exemplo, atualizar versões do Cordova, adicionar um novo plug-in) não podem ser distribuídas via CodePush e, portanto, devem ser atualizadas por meio da(s) loja(s) apropriada(s).

Plataformas Cordova suportadas

O Cordova 5.0.0+ é totalmente compatível, juntamente com as seguintes plataformas associadas:

Para verificar as versões de cada plataforma Cordova que você está usando no momento, você pode executar o seguinte comando e inspecionar a Installed platforms lista:

    cordova platform ls

Se você estiver executando uma plataforma Android ou iOS mais antiga do que a mencionada acima e estiver aberto a atualizações, poderá fazê-lo 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ê pode iniciar o CodePush em seu 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> --displayKeyso e 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, e é por isso que o exemplo acima declara chaves separadas para Android e iOS. Se você estiver desenvolvendo apenas para uma única plataforma, precisará apenas 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 privada/pública para cada plataforma.

  1. Se você estiver usando um <access origin="*" /> elemento em seu arquivo config.xml , seu aplicativo já terá permissão para se comunicar com os servidores CodePush e você poderá ignorar esta 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-Policy meta 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, verifique se você já tem o plug-in instalado (a maioria dos cordova-plugin-whitelist aplicativos terá). Para verificar isso, execute o seguinte comando:
    cordova plugin ls

Se cordova-plugin-whitelist estiver na lista, então você está 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 do 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) verificar se há uma atualização? (e.g. app início, 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 deviceready eventos do seu 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 seus 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 ligar sync com a frequência que quiser, então quando e onde você liga 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"), configurar quando uma atualização disponível é instalada (por exemplo, forçar uma reinicialização imediata) ou personalizar a experiência de atualização de qualquer forma, consulte a referência de API do sync 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 a política deles que um aplicativo exiba um prompt de atualização. Por isso, recomendamos que os aplicativos distribuídos pela App Store não ativem a opção ao chamar sync, enquanto o Google Play e os updateDialog aplicativos distribuídos internamente (por exemplo, Enterprise, Fabric, HockeyApp) podem optar por ativá-la/personalizá-la.

Lançamento de atualizações

Depois que seu aplicativo for configurado e distribuído para seus usuários e você fizer algumas alterações de código ou ativo, é hora de liberá-las 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 a liberação da atualização para o servidor CodePush.

Observação

Antes de começar a lançar 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 para o qual um comando é direcionado.

Dica

Ao lançar 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 esta versão ao atualizar o Cordova ou um de seus plug-ins, momento em que você precisa lançar uma atualização para a(s) loja(s) nativa(s). O CodePush gerará automaticamente um "rótulo" para cada lançamento que você fizer (por exemplo, v3) para ajudar a identificá-lo em seu histórico de lançamentos.

O release-cordova comando permite 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 oferecer suporte a estratégias de lançamento 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 liberação deve ser vista 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 executar o 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 algum problema ou tiver dúvidas/comentários/feedback, você pode nos enviar um e-mail 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 da API

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

  • checkForUpdate: pergunta ao serviço CodePush se a implantação do aplicativo configurada tem uma atualização disponível.
  • getCurrentPackage: Recupera os metadados sobre a atualização atualmente instalada (por exemplo, descrição, tempo de instalação, tamanho).
  • getPendingPackage: recupera os metadados de uma atualização (se houver) 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 e instalando atualizações manualmente (ou seja, não usando o método de sincronização para lidar com tudo para você), esse método DEVERÁ ser chamado; caso contrário, o CodePush tratará a atualização como falha e reverterá para a versão anterior na próxima reinicialização do aplicativo.
  • restartApplication: reinicia imediatamente o aplicativo. Se houver uma atualização pendente, ela será exibida imediatamente para o usuário final.
  • sincronização: Permite verificar se há 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:

codePush.checkForUpdate

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

Consulta o serviço CodePush para ver se a implantação do aplicativo configurada tem uma atualização disponível. Por padrão, ele usará a chave de implantação configurada no 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 o "Acesso antecipado" por meio de um easter egg ou uma opção de configuração do usuário.

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

  1. null se não houver 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 dentro da implantação configurada está direcionada a uma versão binária diferente da que você está executando atualmente (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 em caso de 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 config.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, tempo de instalação). Isso pode ser útil para cenários como exibir uma caixa de diálogo "o que há de novo?" depois que uma atualização foi aplicada ou verificar se há uma atualização pendente que está aguardando para ser aplicada por meio de uma retomada ou reinicialização.

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

  1. null se o aplicativo estiver executando a página inicial HTML do binário e não uma atualização do 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, da loja), 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 da atualização do 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 em caso de erro. O retorno de chamada usa um parâmetro de erro, contendo os detalhes do erro.

Exemplo de uso:

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 da atualização pendente no momento (se houver). Uma atualização é 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ó pode estar nesse estado se InstallMode.ON_NEXT_RESTART ou InstallMode.ON_NEXT_RESUME for especificado ao chamar sync ou LocalPackage.install, e 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 da atualização for concluída, ela acionará o onSuccess retorno de chamada com um dos dois valores possíveis:

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

Parâmetros:

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

Exemplo de uso:

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, na próxima vez que 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 sua verificação de atualização na inicialização do aplicativo, não precisará chamá-la notifyApplicationReady manualmente, pois sync a chamará para você. Esse comportamento existe devido à suposição de que when 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 or LocalPackage.install . Isso não se aplica à 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, coloca a atualização na frente do usuário final antes de 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 verificação de atualização, download e experiência de 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 eliminou 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ê nenhum prompt de atualização ou reinicialização de 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.

Exemplo de uso:

// 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 deseja verificar ou baixar uma atualização disponível com base no nível de bateria do dispositivo do usuário final, nas condições da rede etc., 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 realizaçã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 de atualização geral. O método é chamado com um código de 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 que se espera que sejam recebidos para esta atualização (ou seja, o tamanho do conjunto de arquivos que foram alterados em relação à versão anterior).
    • receivedBytes (Number) - O número de bytes baixados até o momento, que podem ser usados 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.

Opções de sincronização

Embora o sync método tente facilitar a realizaçã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 que você deseja consultar para uma atualização. Por padrão, esse valor é derivado do arquivo config.xml , mas essa opção permite substituí-lo no 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 ficar em segundo plano antes de reiniciá-lo. Essa propriedade se aplica apenas a atualizações instaladas usando InstallMode.ON_NEXT_RESUMEo e pode ser útil para colocar sua atualização na frente dos usuários finais mais cedo, sem ser muito intrusiva. O padrão é 0, que aplica a atualização imediatamente após uma retomada, independentemente do tempo em que ela ficou em segundo plano.
  • ignoreFailedUpdates (booleano) - Especifica se uma atualização disponível deve ser ignorada se 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 "options" 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 é null, o que desativa a 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 (booleano) – indica se você deseja acrescentar a descrição de uma versão disponível à mensagem de notificação exibida para o usuário final. Assume o padrão de false.
  • descriptionPrefix (String) - Indica a string 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 cabeçalho de uma notificação de atualização exibida para o usuário final. Assume o padrão de "Update available".

Exemplo de uso:

// 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 verificar se há 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 em qualquer outra coisa que faça sentido para suas necessidades. Assim como o checkForUpdate método, ele executará a solicitação de rede para verificar se há uma atualização em segundo plano, para que não afete a capacidade de resposta do thread da interface do usuário ou do thread JavaScript.

Objetos de pacote

Os checkForUpdate métodos and getCurrentPackage invocam retornos de chamada de sucesso que, quando acionados, fornecem acesso a objetos "package". O pacote representa sua atualização de código, bem como quaisquer 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á aguardando a 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 o qual esta atualização de pacote se destina. (Cadeia de caracteres)
  • deploymentKey: chave de implantação do pacote. (Cadeia de caracteres)
  • description: 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 esta atualização foi instalada anteriormente, mas foi revertida. O sync método ignorará automaticamente as atualizações que falharam anteriormente, portanto, você só precisa se preocupar com essa propriedade se estiver usando checkForUpdate. (Booleano)
  • isFirstRun: sinalizador que indica se a execução atual do aplicativo é a primeira após a aplicação do pacote. (Booleano)
  • isMandatory: indica se a atualização é considerada obrigatória. Esse é o valor especificado na CLI quando a atualização foi lançada. (Booleano)
  • label: o rótulo interno fornecido automaticamente à 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 este pacote no aplicativo. O comportamento de instalação depende do .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 falha e o aplicativo será revertido para sua versão anterior na próxima execução.
Opções de instalação

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 ficar em segundo plano antes que a atualização seja instalada quando ela for retomada. Assume o padrão de 0.

Exemplo de uso:

// 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 ver um exemplo de como você está protegido contra uma atualização incorreta, consulte a documentação notifyApplicationReady().

Pacote Remoto

Contém detalhes sobre uma atualização que está 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 precisa se preocupar com o RemotePackage, pois ele cuidará do processo de download e instalação automaticamente para você.

Propriedades

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

  • 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): Aborta 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 periódicas de atualização sobre o progresso 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)

Exemplo de uso:

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 do CodePush inclui os seguintes objetos de "enumeração" 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 or LocalPackage.install . Ele inclui os seguintes valores:

  • IMEDIATO: 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 forçar a reinicialização do aplicativo. Quando o aplicativo for reiniciado "naturalmente" (por causa do sistema operacional ou do usuário final que o matou), a atualização será escolhida sem problemas. Esse valor é apropriado ao fazer atualizações silenciosas, pois provavelmente seria prejudicial para o usuário final se o aplicativo fosse reiniciado repentinamente do nada, já que ele não teria percebido que uma atualização foi baixada. Esse é o modo padrão usado para os sync métodos e LocalPackage.install .

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

Pacote Remoto

Contém detalhes sobre uma atualização que está 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 precisa se preocupar com o RemotePackage, pois ele cuidará do processo de download e instalação automaticamente para você.

Propriedades

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

  • 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): Aborta 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 periódicas de atualização sobre o progresso 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)

Exemplo de uso:

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 do CodePush inclui os seguintes objetos de "enumeração" 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 or LocalPackage.install . Ele inclui os seguintes valores:

  • IMEDIATO: 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 forçar a reinicialização do aplicativo. Quando o aplicativo for reiniciado "naturalmente" (por causa do sistema operacional ou do usuário final que o matou), a atualização será escolhida sem problemas. Esse valor é apropriado ao fazer atualizações silenciosas, pois provavelmente seria prejudicial para o usuário final se o aplicativo fosse reiniciado repentinamente do nada, já que ele não teria 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 o retomar em segundo plano. Dessa forma, você não interrompe a sessão atual, mas pode obter a atualização na frente deles antes de ter que esperar pela próxima reinicialização natural. Esse valor é apropriado para instalações silenciosas que podem ser aplicadas na retomada de forma não invasiva.

Status de sincronização

Define os possíveis status da operação de sincronização . Existem 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 status de resultado, 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 na 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, baixar ou descompactar 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 abortada.
  • CHECKING_FOR_UPDATE: o servidor CodePush está sendo consultado para 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.

Construção do PhoneGap

Este plug-in é compatível com o PhoneGap Build e suporta a criação de compilações Android e iOS prontas 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 resolver isso, adicione o seguinte elemento ao arquivo config.xml do projeto, como 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 de exemplo para os desenvolvedores que estão começando. A lista a seguir é de aplicativos OSS Cordova que também estão usando o CodePush e pode ser usada para ver como outras pessoas estão usando o serviço:

Observação

Se você desenvolveu um aplicativo Cordova usando CodePush, que é de código aberto, informe-nos. Adoraríamos adicioná-lo a esta lista!