Visão Geral

Como desenvolvedor, você cria um aplicativo para milhões de usuários do Microsoft Teams para atingir metas específicas de negócios ou clientes. Para esse fim, você o distribui usando uma ou mais das muitas opções de distribuição disponíveis para você. Depois que o aplicativo for publicado, você desejará medir o desempenho dele no mundo real.

Você também estará interessado em monitorar muitos pontos de dados, como:

• Quem tem interesse no seu aplicativo?
• Quais usuários e organizações estão usando seu aplicativo?
• Como os usuários estão interagindo com seu aplicativo?
• Quais usuários desistiram depois de usar seu aplicativo por algum tempo?

Essas informações ajudam você a analisar os dados em relação às suas metas de negócios e a tomar medidas corretivas corrigindo problemas. Ele também ajuda você a intervir na jornada do usuário ou tomar decisões informadas sobre investimentos em recursos, aprimoramentos e adoção do aplicativo.

Mas o relatório de uso do aplicativo do Teams deve ser suficiente, não é?

Como desenvolvedor do aplicativo, você pode acompanhar o uso do aplicativo no relatório de uso do aplicativo do Teams no Partner Center dentro de uma semana após a publicação do aplicativo na Microsoft Teams Store. Os desenvolvedores de aplicativos personalizados podem encontrar análises de uso para seus aplicativos personalizados no Portal do Desenvolvedor do Teams. O relatório de uso do Partner Center fornece métricas padrão que permitem acompanhar a demanda do usuário, a rotatividade de usuários e a frequência de uso do seu aplicativo. Esses relatórios estão disponíveis em um nível agregado, como:

• Usuários ativos mensais, diários e semanais.
• Gráficos de retenção e intensidade.
• Usuários que usaram seu aplicativo mais de cinco dias no último mês.
• Plataforma, sistema operacional e divisão geográfica de usuários para seu aplicativo e assim por diante.

Os relatórios de uso prontos para uso disponíveis no Partner Center ou no Portal do Desenvolvedor do Teams não podem fornecer análises detalhadas do que acontece dentro de seu aplicativo e análises específicas no nível do usuário. Essas análises incluem a jornada de um usuário em seu aplicativo ou o envolvimento de um usuário com recursos específicos e a medição de conclusões de cenários.

Seu aplicativo no Teams é essencialmente um serviço baseado na Web hospedado em outro lugar, por exemplo, na nuvem do Azure. Ele é inserido e colocado na superfície do shell do Microsoft Teams, onde os usuários podem usar seu aplicativo. Isso se aplica ao seu aplicativo independentemente dos recursos da plataforma usados, como guias, bots, extensões de mensagem, extensões de reunião, cartões, caixas de diálogo (chamados de módulos de tarefa no TeamsJS v1.x) e assim por diante. Todos esses recursos são um meio de exibir experiências baseadas na Web dentro do Teams.

Planeje a análise para o aplicativo Teams da mesma forma que você faz para um produto SaaS executado no navegador da Web.

Planeje antecipadamente para análise

Planeje a análise para seu aplicativo do Teams no estágio de desenvolvimento, design e arquitetura da solução. Examine quais das práticas e instrumentação de dados existentes para seu aplicativo Web SaaS principal serão acumuladas em construções de tela hospedadas, como guias, caixas de diálogo, aplicativos de reunião e assim por diante no Teams que você está otimizando ou criando do zero para aparecer dentro do Teams. Para recursos específicos do Teams, como construções de conversa como bots, extensões de mensagem e assim por diante, você precisará planejar e implementar a instrumentação de análise, capturar eventos relevantes e contexto dos métodos do SDK do zero.

No momento em que seu aplicativo de produção do Teams estiver ativo no Repositório do Teams e os clientes começarem a usá-lo, sua infraestrutura de análise e dados deverá estar totalmente operacional. Isso garante que você não perca o rastreamento:

• Marcadores de instrumentação sendo disparados.
• Eventos específicos do Teams e as informações contextuais relevantes contidas nesses eventos, alguns dos quais são disparados para você capturar em seu back-end de SaaS para uso posterior.

Por exemplo, a ID do usuário do Microsoft Entra para um usuário do Teams deve ser capturada quando um evento de bot específico é acionado quando um usuário instala o aplicativo de bot. Essa ID de usuário pode ser mapeada para a identidade de perfil real do usuário, como endereço de email. Ele permite que você envie notificações proativas ao usuário posteriormente por meio do bot.

Instrumentando seu aplicativo para análise

Instrumentar seu código com marcadores de análise (também conhecidos como marcadores de instrumentação) é uma prática padrão de desenvolvimento de aplicativos Web. A instrumentação robusta em seu código é fundamental para o sucesso a longo prazo. Ele ajuda você a medir métricas agregadas e específicas do usuário.

O aplicativo Teams é outra superfície para expor sua solução ao usuário final, outra janela para o cenário de SaaS. À medida que sua solução é dimensionada em várias plataformas (Web, plataformas móveis e Teams), é importante exibir sua instrumentação em camadas:

Existem dois tipos de instrumentação de dados relevantes para sua solução:

• Instrumentação de dados para seu produto ou aplicativo SaaS principal

• Instrumentação de dados em seu aplicativo específica para o Teams

Instrumentação de dados para seu produto ou aplicativo SaaS principal

Essa é a instrumentação que você fará para seu aplicativo SaaS baseado em navegador, independentemente de estar ou não integrando ao Teams. Se você tiver um aplicativo SaaS baseado em navegador, com toda a probabilidade, você já terá essa instrumentação feita em seu código. É assim que você pode ver a análise de cliques e a análise do ciclo de vida do cliente. Você também pode ver métricas de análise de conversão, como taxa de rejeição, visualizações de página, contagem de visitantes únicos, contagens de sessões, tempo de engajamento, taxa de cliques e muito mais para seu aplicativo da web.

Instrumentação de dados em seu aplicativo específica para o Teams

Essa instrumentação deve ser feita adicionalmente em seu aplicativo SaaS porque agora ela está aparecendo dentro do cliente do Teams. Em um nível de apresentação, seu aplicativo é acessado pelo usuário final em diferentes modalidades. Cada modalidade tem seus próprios pontos de interação com o usuário exclusivos, metadados que facilitam a captura de instrumentação exclusiva para essa modalidade. Por exemplo, a exibição de um produto pode ser rastreada por meio da exibição de página em um aplicativo da web versus rastreamento de tela em um aplicativo móvel. Da mesma forma, seu aplicativo Teams pode ter usado um ou mais dos recursos de plataforma disponíveis apenas dentro do Teams, como bots, extensões de mensagem e assim por diante. ou você criou experiências para lidar com casos de uso exclusivos do Teams, como extensões de reunião, cenários inteligentes com reconhecimento do M365 usando o Microsoft Graph, desdobramento de link e assim por diante. A captura da instrumentação dessas experiências exclusivas do aplicativo do Teams é abordada com mais detalhes no restante deste documento.

Instrumentação para análises específicas de aplicativos do Teams

Esta seção inclui diretrizes e indicações sobre o que procurar, quais eventos capturar, como usar marcadores de instrumentação e onde buscar informações relevantes do Teams que ajudarão você a planejar e implementar análises para seu aplicativo. Seus aplicativos do Teams podem ser guias, bots, extensões de mensagem, cartões, Stageviews e assim por diante ou qualquer combinação desses recursos e construções de interface do usuário em escopos pessoais ou compartilhados. É melhor entender, planejar e implementar sua instrumentação em torno de cada um desses recursos.

Você pode classificar os recursos da plataforma do Teams em duas construções:

• Construções de tela da Web hospedadas
• Construções conversacionais

Construções de tela da Web hospedadas

Os recursos orientados para tela visual são páginas da Web compatíveis com o Teams incorporadas no Microsoft Teams, como guias, aplicativos pessoais, caixas de diálogo (exibindo um iframe incorporado), exibições de palco, guias de reunião, estágio de reunião compartilhado e caixas de diálogo na reunião. Eles são hospedados na nuvem com o restante do seu aplicativo SaaS que é executado no navegador da Web.

Essas páginas da Web geralmente têm a instrumentação feita para as principais necessidades do aplicativo Web SaaS. Você só precisa capturar eventos específicos do Teams e manipulá-los para instrumentação específica do Teams em seu código. É útil para suas necessidades de análise que as guias sejam páginas da Web "compatíveis com o Teams".

Ao criar uma guia seguindo os pré-requisitos definidos aqui, adicione o SDK do cliente JavaScript do Teams à página de conteúdo ou configuração da sua guia. Isso garante que sua página possa acessar informações ou contexto específicos do Teams. Use essas informações para obter informações úteis específicas do usuário, como:

• ID de locatário do Microsoft 365 (locatário do Microsoft Entra) para o usuário atual (tid). No Microsoft 365 ou Microsoft Entra ID, um locatário é o representante de uma organização, ou seja, a empresa do usuário. A ID de locatário do Microsoft 365 é útil para descobrir e registrar em log a qual locatário do Microsoft 365 o usuário pertence. Depois de saber a ID do locatário, você poderá descobrir o domínio do locatário da organização, que geralmente revela o nome da organização, usando essa API do Graph. Certifique-se de invocar essa API em seu locatário do Microsoft 365 Developer, pois você poderá consentir com a permissão de administrador necessária.
• Tipo de licença atribuído ao usuário e o SKU para o locatário do usuário atual. Os valores possíveis são os planos empresariais F1, E1, E3 e E5 para (licenseType) e enterprise, free, edu e unknown for (tenantSKU).
• O contexto em que a URL da guia é carregada. Alguns valores possíveis podem ser página de conteúdo, caixa de diálogo, caixa de diálogo de configurações de guia, caixa de diálogo de remoção de guia, sidePanel de reunião e assim por diante. (frameContext).
• Tipo de cliente host em que a guia é carregada. Os valores possíveis são Android, IoS, web, desktop, surfaceHub e assim por diante. (hostClientType). Você pode dividir seus dados de análise.
• Reconhecimento de localidade para que o usuário indique o idioma, por exemplo, en-us, fr-fr, ja-jp e assim por diante. (locale).
• Nome Principal do Usuário ou dica de logon (loginHint) do usuário atual no locatário atual (geralmente o endereço de email do usuário).
• Nome da equipe e nome do canal em que a guia do canal é adicionada (teamName, channelName).
• ID exclusiva da sessão de aplicativo atual dentro de uma guia usada para correlacionar dados de instrumentação (appSessionId).
• A ID da reunião é usada por uma guia em execução no contexto da reunião e é adicionada para o conteúdo de resposta (meetingId).
• Microsoft Entra ID do usuário atual.

Depois de extrair as informações específicas do Teams do contexto da guia, algumas maneiras possíveis de usá-las são mostradas nos exemplos a seguir:

Construções conversacionais

Os recursos orientados a conversa ou chat incluem bots, extensões de mensagem, cartões e caixas de diálogo (exibindo um Cartão Adaptável) criados para usuários do Teams. Conceitualmente, essas experiências são criadas e estão disponíveis somente para usuários especificamente dentro do Teams. Você precisará capturar eventos específicos do Teams e manipulá-los para instrumentação específica do Teams em seu código para essas construções do zero. Um bot pode acessar dados de contexto adicionais sobre uma equipe, chat, reunião, chamada 1:1 ou chamada de grupo onde ele está instalado.

Use essas informações para enriquecer a funcionalidade do bot e a experiência do usuário:

• Consulte o bot para obter a lista de membros e seus perfis de usuário básicos, incluindo IDs de usuário do Teams e informações do Microsoft Entra, como nome e ID de usuário ou objeto do Microsoft Entra.

• Use a ID de usuário ou objeto do Microsoft Entra do usuário para encontrar o nome, sobrenome, endereço de email, ID de locatário e função do usuário na equipe. Aproveite esses detalhes conforme descrito para construções de tela da Web hospedadas.

• Se o bot estiver instalado em uma equipe, consulte-o para obter metadados sobre essa equipe, incluindo a ID do grupo do Microsoft Entra e o nome da equipe. Ele também pode consultar a lista de canais da equipe, que retorna IDs e nomes de canal. Aproveite essas informações para configuração, instalação e personalização.

• Usando a API de detalhes da reunião, obtenha os metadados estáticos de uma reunião ou chamada, como o tipo de reunião (por exemplo, GroupCall, , OneToOneCall, BroadcastRecurringScheduledAdhocMeetNow, ou Unknown), tipo de conversa, ID do locatário do organizador e assim por diante.

Cada atividade enviada pelo Teams para seu bot conterá o turnContext objeto do qual todos esses campos relevantes podem ser recuperados. Você pode aproveitá-los de maneira semelhante, conforme descrito para construções de tela da Web hospedadas.

Como as extensões de mensagem são baseadas no canal de bot, a maioria dos itens acima também se aplica às extensões de mensagem.

Insights agregados e específicos do usuário

Além das métricas óbvias no mundo SaaS, como usuários ativos diários, semanais, mensais e tempo gasto em seu aplicativo, a implementação cuidadosa de análises para seu aplicativo Teams de acordo com as diretrizes acima permitirá que você obtenha insights como:

• Métricas agregadas

  • Quais recursos de plataforma, áreas de superfície (por exemplo, guias, bots, extensões de mensagem) e construções de interface do usuário (cartões, caixas de diálogo, Stageviews) aproveitados em seu aplicativo Teams encontraram mais uso por seus usuários?
  • Qual escopo ou ponto de entrada da interface do usuário (como aplicativo pessoal, canal, chat em grupo) é o mais usado pelos usuários para invocar seu aplicativo e iniciar uma nova sessão de aplicativo dentro do Teams?
  • Quantos dias, em média, os usuários usam seu aplicativo na primeira semana após a instalação do aplicativo?
  • Qual é a análise de coorte de retenção de novos usuários semana a semana ou mês a mês para seu aplicativo ou recursos específicos (como bot ou aplicativo pessoal) em seu aplicativo?
  • Quantos usuários usam seu aplicativo somente em clientes móveis do Teams?
  • Quantos usuários usaram o recurso de dispositivo de câmera em seu aplicativo?
  • O que a análise do funil revela para o seu aplicativo em todas as fases, desde a instalação do aplicativo até a ativação, o engajamento, a retenção e, finalmente, a monetização? Onde estão acontecendo as desistências?
  • Quantos usuários instalaram seu aplicativo na última semana?
  • Quantos usuários abandonaram seu aplicativo nos últimos três meses? Qual é a taxa de rotatividade trimestral resultante?
  • Qual organização viu o número máximo de instalações de seu aplicativo nos últimos 30 dias?
  • A quais organizações pertencem os usuários que instalaram seu aplicativo nos últimos 14 dias?
  • Qual organização viu o número máximo de inscrições de avaliação para seu aplicativo nos últimos sete dias?
  • Em que tipos de reuniões (GroupCall, OneToOneCall, Adhoc, MeetNowBroadcastRecurring , , ou Scheduled) seu aplicativo é usado?

• Métricas específicas do usuário

  • Quais usuários ainda não experimentaram o recurso de guias de canal que você implementou em seu aplicativo na última atualização do aplicativo?
  • Quais usuários não concluíram a integração no aplicativo pessoal?
  • Entre os usuários que instalaram o aplicativo na última semana, quais usuários não retornaram ao aplicativo nem uma vez para engajamento após a instalação?
  • Quais usuários instalaram o aplicativo, mas ainda não entraram no aplicativo?
  • Quantas vezes um usuário específico usou seu aplicativo Teams nos últimos 30 dias?
  • Quantos dias um usuário específico usou ativamente seu aplicativo nos últimos sete dias?
  • Quando foi a última vez que um usuário específico usou seu aplicativo no Teams?
  • Qual tem sido a jornada de um usuário de aplicativo específico dentro do Teams?
  • Quais usuários abandonaram seu aplicativo nos últimos três meses?
  • Algum usuário específico usou seu aplicativo em uma reunião do Teams?

Em seguida, veja como você deve elaborar metodicamente sua estratégia de instrumentação de dados e decida o que medir com base em quais insights específicos você deseja obter do uso do aplicativo do Teams.

Próxima etapa