Suspensão do aplicativo para seu aplicativo de guia

Quando um usuário sai de um aplicativo, ele pode ser suspenso ou encerrado. A suspensão significa que o aplicativo está em segundo plano e não está visível para o usuário. O encerramento significa que o aplicativo está completamente fechado e removido da memória. A suspensão de um aplicativo melhora o tempo de inicialização subsequente dos aplicativos no Teams ou em outros produtos do Microsoft 365, permitindo que você mantenha alguns recursos e ativos na memória que podem ser usados ao reidratar o aplicativo.

Anteriormente, a suspensão do aplicativo era chamada de aplicativo em cache e tinha suporte apenas no Teams, mas agora tem suporte para aplicativos do Teams estendidos para serem executados em outros aplicativos do Microsoft 365 também.

No Teams, há suporte para a suspensão do aplicativo para os seguintes escopos e clientes:

Habilitar suspensão do aplicativo

Para habilitar a suspensão do aplicativo, siga as etapas:

1. Chame as APIs app.lifeCycle.registerBeforeSuspendOrTerminate e app.lifeCycle.registerOnResumeHandler . Esses manipuladores são necessários para habilitar a suspensão do aplicativo. Para obter mais informações, consulte o módulo de ciclo de vida disponível na referência do TeamsJS.

   O app.lifecycle.registerBeforeSuspendOrTerminate manipulador oferece a oportunidade de executar algumas tarefas antes que seu aplicativo seja suspenso ou encerrado, enquanto o app.lifecycle.registerOnResumeHandler é chamado quando um usuário navega de volta para seu aplicativo.

   O registro de ambos os manipuladores permite que um aplicativo seja suspenso do aplicativo, mas é importante entender que estar registrado não garante que o aplicativo não seja encerrado em segundo plano. O encerramento de um aplicativo depende de outros fatores, como a memória disponível.

   Observação

   Anteriormente teamsCore.registerBeforeUnloadHandler e teamsCore.registerOnLoadHandler foram usados para habilitar o cache de aplicativos, mas agora estão preteridos.

2. Use contentUrl e entityId passado para o manipulador de currículos para rotear para a página correta em seu aplicativo e invocar notifySuccess ou notifyFailure notificar o host de que o fluxo de inicialização do aplicativo foi concluído.

   • contentUrl: adiciona a URL da página de conteúdo.
   • entityId: adiciona um identificador exclusivo.

3. Disponha os recursos e execute qualquer beforeSuspendOrTerminate limpeza necessária no manipulador.

O diagrama de fluxo a seguir mostra a primeira inicialização de um aplicativo que deseja optar pela suspensão do aplicativo (registre os resume manipuladores OR beforeSuspensionOrTerminate na primeira inicialização do aplicativo):

O diagrama de fluxo a seguir mostra a inicialização de aplicativos suspensos:

Quando você opta pela suspensão do aplicativo, o iframe ou o modo de exibição da Web usado para hospedar o aplicativo inserido é reutilizado à medida que os usuários navegam para diferentes instâncias do aplicativo em uma janela. O iframe ou webview usado para hospedar o aplicativo fica oculto quando os usuários saem do aplicativo e mostrado quando os usuários retornam ao aplicativo.

Há vários motivos para um aplicativo não ser suspenso ou para que um aplicativo seja removido do cache. Alguns motivos gerais nos aplicativos do Microsoft 365 são:

• A carga total de memória é alta.
• O número total de aplicativos suspensos excede o tamanho máximo do cache. Nessa circunstância, o aplicativo suspenso mais antigo é removido.
• O aplicativo será encerrado se a memória disponível do computador estiver baixa.
• O aplicativo fica suspenso por um longo tempo sem ser retomado.
• O aplicativo falha ao carregar e é encerrado.

No aplicativo Teams, alguns dos motivos são (os números aqui estão sujeitos a alterações):

• Se a carga de memória do sistema for alta, o aplicativo será removido do cache.
• O aplicativo será encerrado se o Teams não receber o readyToUnload sinal do TeamsJS dentro de 30 segundos após o envio da beforeUnload notificação.
• A suspensão do aplicativo será desabilitada se a memória do sistema for inferior a 4 GB ou se a memória disponível for inferior a 1 GB no Windows ou 512 MB no Mac.
• O painel lateral é o único frameContext com suporte para suspensão do aplicativo em reuniões.
• A suspensão do aplicativo não é compatível com reuniões em que a contagem de usuários convidados é maior que 20.
• No iOS, quando o aplicativo Teams é encerrado, o aplicativo é removido do cache.

Exemplo de código

O trecho de código a seguir é um exemplo de app.lifecycle.registerOnResumeHandler e app.lifecycle.registerBeforeSuspendOrTerminateHandler APIs:

MicrosoftTeams.app.lifecycle.registerOnResumeHandler((data) => {  

   console.log("got resume call" , data.contentUrl, data.entityId);  

   // use contentUrl to route to correct page  
   // invoke notifySuccess when ready  

   app.notifySuccess();  

}); 

MicrosoftTeams.app.lifecycle.registerBeforeSuspendOrTerminateHandler(() => {  

   // dispose resources and resolve promise 

}); 

Ferramenta de depuração para aplicativos armazenados em cache

Você pode habilitar o Gerenciador de Tarefas Proto no Teams, uma ferramenta de depuração que mostra o status de seus aplicativos armazenados em cache. No cliente do Teams, selecione as teclas Control+Shift+Alt+8 no Windows ou Command+Shift+Option+8 no Mac para abrir o Gerenciador de Tarefas Proto.

A guia AppCaching contém os seguintes detalhes:

• state: mostra o estado em cache e não armazenado em cache do aplicativo.
• isActive: mostra o status ativo ou inativo do aplicativo armazenado em cache.
• timeElapsed: mostra o tempo decorrido desde que o aplicativo foi armazenado em cache.
• supportsLoad: mostra se o aplicativo registrou o manipulador se o Load cache do aplicativo estiver habilitado.
• supportsBeforeUnload: mostra se o aplicativo registrou o manipulador se o BeforeUnload cache de aplicativo estiver habilitado.
• totalFrameMemory: mostra o uso da memória do aplicativo.
• totalFrameCommitMemory: mostra o uso da CPU do aplicativo.

Armazenar em cache aplicativos de guia

Embora o cache reduza os tempos de carregamento subsequentes de um aplicativo, o pré-cache otimiza o tempo de carregamento inicial de um aplicativo, permitindo que o Teams pré-carregue o aplicativo. O Teams pré-carrega aplicativos em segundo plano após o lançamento ou quando estão ociosos, com base nos padrões de uso de aplicativos recentes dos usuários e no histórico de cache dos aplicativos. Os aplicativos pré-carregados permanecem armazenados em cache até que o usuário abra o aplicativo, resultando em um tempo de carregamento mais rápido.

Se você habilitar o pré-cache, seu aplicativo utilizará recursos e os dados de telemetria serão rastreados enquanto estiver no estado pré-armazenado em cache. Para saber como otimizar seu aplicativo para pré-cache, consulte as práticas recomendadas.

Habilitar o pré-cache para aplicativos de guia

Para habilitar o pré-cache para seu aplicativo de guia, siga estas etapas:

1. Habilite o cache do aplicativo.

2. Atualize o manifesto do aplicativo da seguinte maneira:

   1. Defina o valor de showLoadingIndicator para true. Essa ação garante que o Teams aguarde até que seu aplicativo seja enviado notifySuccess para concluir a sequência de carregamento do aplicativo durante o pré-cache. Para obter mais informações, consulte showLoadingIndicator.

   2. Adicione o backgroundLoadConfiguration objeto e defina o contentUrlarquivo .

      {
      "backgroundLoadConfiguration": {
          "tabConfiguration": {
              "contentUrl": "https://www.contoso.com/content?host=msteams&isBackgroundLoad=true"
              }
          }
      }
      

      Observação

      • O não pode conter parâmetros específicos do contexto, como a URL do site de equipe ou a ID do thread, pois o contentUrl Teams carrega aplicativos sem contexto anterior durante a inicialização.
      • O contentUrl deve ser genérico o suficiente para ser carregado em segundo plano sem nenhuma interação do usuário.

      Para obter mais informações, consulte backgroundLoadConfiguration.

Monitorar o carregamento em segundo plano

Você pode identificar se o Teams carregou o aplicativo em segundo plano sem interação do usuário se você monitorar a isBackgroundLoad propriedade. Se o estado da propriedade for true, isso indica que o Teams carregou o aplicativo em segundo plano e não consegue interagir com o usuário. Portanto, o aplicativo não precisa renderizar elementos da interface do usuário, como prompts de entrada.

Monitore a isBackgroundLoad propriedade no contexto do aplicativo para otimizar o aplicativo para carregamento e renderização de pré-cache eficazes. Para obter mais informações, consulte isBackgroundLoad.

Práticas recomendadas

Veja a seguir as práticas recomendadas para suspensão e pré-cache do aplicativo:

• Recomendamos que você implemente recursos de trabalho de serviço ou armazenamento na Web para armazenar os dados ou o modo de exibição da Web localmente. Essa estratégia ajuda a carregar o aplicativo mais rapidamente em inicializações subsequentes.

• Registre os manipuladores de suspensão do aplicativo no início da sequência de inicialização, como logo após a chamada app.initialize e antes que o aplicativo envie notifySuccess. Se o cliente do Teams não vir esses registros antes que o usuário saia do aplicativo, o aplicativo não será armazenado em cache.

• Tente reduzir o volume de memória quando o app.lifecycle.onBeforeSuspendOrTerminateHandler manipulador for chamado e o aplicativo estiver prestes a ser suspenso. Por exemplo, referências de versão, remover eventListeners, pausar chamadas de sincronização ou interromper solicitações de rede.

• O pré-cache aumenta o tráfego para seu aplicativo, além das solicitações iniciadas pelo usuário. Verifique se o ponto de extremidade fornecido como o contentUrl pode lidar com solicitações em segundo plano várias vezes para cada usuário em um dia. Certifique-se de fazer os ajustes de telemetria necessários para acomodar o carregamento em segundo plano do aplicativo.

• Verifique se o aplicativo usa menos ou igual a 130 MB de memória no estado pré-armazenado em cache.

Limitações gerais

Estas são as limitações gerais para a suspensão do aplicativo:

• Não há garantias de que um aplicativo será suspenso. Há motivos que podem levar ao encerramento do aplicativo, mesmo que um aplicativo tenha registrado os manipuladores necessários.

• Um aplicativo é suspenso somente quando o usuário sai do aplicativo. Se um aplicativo tiver várias guias estáticas, quando o usuário alternar entre as guias, a guia não será suspensa. O manipulador, app.lifecycle.onBeforeSuspendOrTerminate, ainda será chamado.

• O aplicativo suspenso pode ser usado na mesma janela. O aplicativo suspenso em uma janela pop-out não pode ser reutilizado na janela principal.

• Quando um aplicativo é suspenso, todos os manipuladores registrados são excluídos. Quando o aplicativo é retomado, todos os manipuladores, como themeChange ou focusEnter, precisam ser registrados novamente. Nenhuma notificação é enviada ao aplicativo quando ele está suspenso. Se o aplicativo exigir notificações mesmo quando suspenso, a suspensão pode não ser a solução certa.

• Somente aplicativos de página única que usam roteamento do lado do cliente para navegação na página podem se beneficiar da suspensão e retomada do aplicativo. É recomendável que o mesmo domínio seja usado em todos os contextos do lançamento do aplicativo.

• Espera-se que um aplicativo entre em suspensão quando suspenso. Nenhuma solicitação do SDK é permitida quando o aplicativo é suspenso.

• O aplicativo host invoca o resume manipulador somente depois que a suspendOrTerminate sequência do aplicativo é concluída. Por exemplo, se um usuário iniciar a guia A do aplicativo e, em seguida, iniciar a guia B do mesmo aplicativo, a guia B não receberá o resume sinal até que o suspendOrTerminate manipulador na guia A termine de executar.

• Os aplicativos são armazenados em cache por janela. O cache de aplicativos acontece por aplicativo (não por guia) dentro da mesma janela.

• A tabela na seção introdutória, Suspensão do aplicativo para seu aplicativo de guia, fornece informações sobre o que frameContext o Teams dá suporte para armazenamento em cache. Para hubs que não são do Teams, FrameContext.Task somente FrameContext.Content o cache é feito, o que significa que não há suporte para o that's insideDialog.

• Registre somente o beforeSuspendOrTerminate manipulador se o aplicativo não exigir suspensão do aplicativo, mas precisar de tempo para salvar o estado com segurança (pois sair do aplicativo pode fazer com que o conteúdo do aplicativo seja removido abruptamente do DOM (Modelo de Objeto do Documento)). Se o aplicativo não tiver se registrado para o resume evento, ele será removido do DOM após a suspendOrTerminate conclusão do fluxo.

Limitações do Microsoft Teams

A seguir estão as limitações para a suspensão do aplicativo no aplicativo Teams:

• O cliente do Teams invoca o resume manipulador somente depois que a suspendOrTerminate sequência do aplicativo é concluída. Por exemplo, se um usuário iniciar a guia A do seu aplicativo e, em seguida, iniciar a guia B do mesmo aplicativo, a guia B não receberá o resume sinal até que o suspendOrTerminate manipulador na guia A termine de executar.

• A suspensão do aplicativo não tem suporte para contextos de estágio ou diálogo da reunião (referido como módulo de tarefa no TeamsJS v1.x), porque eles podem ser abertos na parte superior da guia e o mesmo iframe ou exibição da Web não pode ser usado para renderizar o conteúdo na guia e na caixa de diálogo.

• Siga as diretrizes nesta seção para integrar seu aplicativo à suspensão do aplicativo na reunião do Teams. Para suporte à suspensão do aplicativo somente em reuniões, registre os resume manipuladores ou beforeSuspendOrTerminate se o contexto for sidePanel.

Solução de problemas

Os aplicativos não estão sendo suspensos? Por que o manipulador de currículos não é invocado na navegação subsequente?

• Verifique se as restrições de sistema e memória disponível são atendidas.

• Reduza o volume de memória quando armazenado em cache. Use o beforeSuspendOrTerminate manipulador para descartar recursos, por exemplo, referências de versão e remover ouvintes de eventos que podem não ser necessários quando armazenados em cache.

Exemplo de código

Confira também

• Criar uma guia pessoal
• Criar uma guia de canal ou guia de grupo
• Criar guias para reuniões