Integrar os recursos de localização

Você pode integrar os recursos de localização ao seu aplicativo do Teams usando o SDK do cliente JavaScript do Microsoft Teams, que fornece APIs bem definidas e as ferramentas necessárias para que seu aplicativo acesse os recursos do dispositivo nativo do usuário. A funcionalidade de localização está disponível para o cliente Web, área de trabalho e celular do Teams.

Você pode usar a biblioteca de cliente JavaScript do Microsoft Teams (TeamsJS), que fornece as ferramentas necessárias para que seu aplicativo acesse os recursos do dispositivo nativo do usuário. Use as APIs de localização, como getLocation e showLocation, para integrar os recursos em seu aplicativo.

Vantagens

Você pode usar as APIs de localização, como getLocation e showLocation, para integrar os recursos ao seu aplicativo.

Observação

Este tópico reflete a versão 2.0.x da biblioteca de cliente JavaScript do Microsoft Teams (TeamsJS). Se você estiver usando uma versão anterior, consulte a visão geral da biblioteca do TeamsJS para obter diretrizes sobre as diferenças entre o TeamsJS mais recente e as versões anteriores.

A vantagem de integrar recursos de localização em seus aplicativos do Teams é utilizar a funcionalidade de localização no cliente Web, na área de trabalho e no celular do Teams usando a biblioteca de cliente JavaScript do Microsoft Teams. Os cenários a seguir mostram as vantagens dos recursos de localização:

A principal vantagem de integrar recursos de localização em seus aplicativos do Teams é que ela permite que os desenvolvedores de aplicativos Web na plataforma Teams utilizem a funcionalidade de localização com a biblioteca de cliente JavaScript do Microsoft Teams.

  • Compartilhe dados de saúde autênticos de torres de celular com o gerenciamento. O gerenciamento pode comparar qualquer incompatibilidade entre as informações de localização capturadas e os dados enviados pela equipe de manutenção.

  • Localize a equipe de suporte técnico em uma área especificada. O aplicativo solicita que a equipe de suporte compartilhe sua localização atual, que a gerência pode usar para alocar tíquete de TI para a pessoa de suporte mais próxima depois de verificar seu perfil.

  • Relate o local após concluir um trabalho no campo. O aplicativo de processamento de trabalho pede permissão para encontrar o local. Depois que o usuário concede permissão, o aplicativo detecta o local exato. O usuário também pode selecionar um local arrastando um marcador para o local de conclusão do trabalho no mapa.

  • Capture o público por meio de selfies dentro da loja. O gerente da loja pode acompanhar a presença dos trabalhadores pedindo que eles compartilhem uma selfie por meio de um aplicativo de atendimento. Os dados de localização são capturados e enviados junto com a imagem. Esse cenário é aplicável principalmente aos trabalhadores de linha de frente.

A imagem a seguir mostra a experiência do aplicativo Web da API getLocation:

A ilustração mostra o seletor de localização.

Para integrar os recursos de localização, você deve:

Atualizar manifesto

Atualize seu aplicativo do Teams do arquivo manifest.json do adicionando a devicePermissions propriedade e especificando geolocation. Ele permite que seu aplicativo solicite as permissões necessárias dos usuários antes que eles comecem a usar os recursos de localização. A atualização para o manifesto do aplicativo é a seguinte:

"devicePermissions": [
    "geolocation",
],

Observação

APIs de Localização

A tabela a seguir lista o conjunto de APIs para habilitar os recursos de localização do dispositivo:

API Descrição Configuração de entrada
getLocation Fornece a localização atual do dispositivo do usuário ou abre o seletor de localização nativo e retorna o local escolhido pelo usuário. A getLocation API usa os dois parâmetros de entrada a seguir como parte da interface LocationProps : allowChooseLocation, showMap:
A experiência é derivada da combinação destes dois parâmetros de entrada:
- (verdadeiro, verdadeiro): Um mapa é iniciado e o usuário pode escolher qualquer local nele.
- (verdadeiro, falso): Um mapa é iniciado e o usuário pode escolher qualquer local nele.
- (falso, verdadeiro): Um mapa é lançado. O usuário só pode enviar o local atual.
- (falso, falso): O mapa não é iniciado. A localização atual do usuário é buscada.
showLocation Mostra a localização no mapa. Ele usa uma única localização de parâmetro de entrada, que contém as coordenadas do local a ser mostrado no mapa.

Observação

Para getLocation API:

  • Se allowChooseLocation for definido como verdadeiro, então showMap será ignorado.
  • showMap= false não é compatível com o Teams na Web ou na Área de Trabalho.

Para obter mais informações sobre getLocation e showLocation, consulte LocationProps.

Importante

Quando seu aplicativo ou serviços acessam uma API da Microsoft que fornece uma localização usando o Bing Mapas, você entende e concorda que qualquer conteúdo fornecido por meio do Bing Mapas, incluindo códigos geográficos, só pode ser usado dentro da API da Microsoft por meio da qual o conteúdo é fornecido. O uso que você faz do Bing Mapas é regido pelos Termos de Uso do Usuário Final do Bing Mapas disponíveis em go.microsoft.com e pela Política de Privacidade da Microsoft.
Além disso, você deve fornecer um link de hipertexto para os TOU do Bing Mapas, que está localizado aqui, na parte inferior de cada página do seu Aplicativo, onde os serviços podem ser acessados ou visualizados, ou dentro dos termos de uso do seu aplicativo. Você é responsável por notificar os usuários finais sobre alterações nos TOU do Bing Mapas e cumpre as instruções razoáveis da Microsoft ao fazer isso. Você não incentivará nem exigirá que nenhum usuário final viole os termos dos Termos de Serviço do Bing Mapas. Caso um usuário final viole os Termos de Serviço do Bing Mapas, a Microsoft poderá rescindir este contrato imediatamente.

Trechos de código

  • Chame getLocation a API para recuperar o local:

    import {location} from "@microsoft/teams-js"

let locationProps = {"allowChooseLocation":true,"showMap":true};
if(location.isSupported()) {
  microsoftTeams.location.getLocation(locationProps, (error, location) => {
    // If there's any error, an alert shows the error message/code
     if (error) {
       if (error.message) {
      alert(" ErrorCode: " + error.errorCode + error.message);
    } else {
      alert(" ErrorCode: " + error.errorCode);
   }
}
console.log(JSON.stringify(location));
})
}
else {/*Handle case where capability isn't supported */}

  • Chame showLocation a API para exibir o local:

    import {location} from "@microsoft/teams-js"

let location = {"latitude":17,"longitude":17};
if(location.isSupported()) {
  microsoftTeams.location.showLocation(location, (error, result) => {
   if (error) {
       if (error.message) {
         alert(" ErrorCode: " + error.errorCode + error.message);
       } else {
        alert(" ErrorCode: " + error.errorCode);
    }
  }
});
}
else {/*Handle case where capability isn't supported */}

Tratamento de erros

Você deve garantir que lide com esses erros adequadamente em seu aplicativo do Teams. A tabela a seguir lista os códigos de erro e as condições sob quais os erros são gerados:

Código de erro Nome do erro Condição
100 NÃO_SUPORTADO_NA_PLATAFORMA A API não é compatível com a plataforma atual.
500 INTERNAL_ERROR Erro interno encontrado durante a execução da operação necessária.
1.000 PERMISSION_DENIED O usuário negou permissões de localização para o aplicativo do Teams ou o aplicativo Web.
4000 ARGUMENTOS_INVÁLIDOS A API foi invocada com argumentos obrigatórios incorretos ou insuficientes.
8000 ABORTAR_USUÁRIO O usuário cancelou a operação.
9000 ANTIGA_PLATAFORMA O usuário está na build da plataforma antiga onde a implementação da API está ausente. A atualização do build deve resolver o problema.

Exemplo de código

Nome do exemplo Descrição .NET Node.js Manifesto
Localização atual do check-in do aplicativo Este exemplo mostra um bot do Microsoft Teams que permite aos usuários fazer o marcar em seu local atual e exibir todos os marcar-ins anteriores sem problemas. View View Exibir

Confira também

  • Last updated on