Integrar os recursos de localização

  • Artigo

Você pode integrar os recursos de localização em seu aplicativo 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 de dispositivo nativo do usuário. O recurso de localização está disponível para o cliente Web do Teams, a área de trabalho e o celular.

Você pode usar a biblioteca de clientes JavaScript do Microsoft Teams (TeamsJS), que fornece as ferramentas necessárias para que seu aplicativo acesse os recursos de 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 em seu aplicativo.

Observação

Este tópico reflete a versão 2.0.x da biblioteca de clientes 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 do Teams, na área de trabalho e no celular usando a biblioteca de clientes JavaScript do Microsoft Teams. Os seguintes cenários mostram as vantagens dos recursos de localização:

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

  • Compartilhe dados de integridade autênticos de torres celulares 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 pede que a equipe de suporte compartilhe sua localização atual, que o gerenciamento pode usar para alocar o tíquete de TI para a pessoa de suporte mais próxima depois de verificar seu perfil.

  • Informe o local após concluir um trabalho no campo. O aplicativo de processamento de trabalho pede permissão para localizar 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 pino para o local de conclusão do trabalho pelo mapa.

  • Capture o atendimento por meio de selfies dentro da loja de varejo. O gerente da loja pode acompanhar o atendimento 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 da 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 peça 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 o local 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 desses dois parâmetros de entrada:
- (true, true): um mapa é iniciado e o usuário pode escolher qualquer local nele.
- (true, false): um mapa é iniciado e o usuário pode escolher qualquer local nele.
- (false, true): um mapa é iniciado. O usuário só pode enviar o local atual.
- (false, false): o mapa não é iniciado. O local atual do usuário é buscado.
showLocation Mostra a localização no mapa. Ele usa um único local de parâmetro de entrada, que contém as coordenadas do local a serem mostradas no mapa.

Observação

Para getLocation API:

  • Se allowChooseLocation for definido como true, será showMap ignorado.
  • showMap= não há suporte para false na Web ou na área de trabalho do Teams.

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

Importante

Quando seu aplicativo ou serviços acessa uma API da Microsoft que fornece um local usando o Bing Mapas, você entende e concorda que qualquer conteúdo fornecido por meio de Bing Mapas, incluindo geocódigos, só pode ser usado na API da Microsoft por meio da qual o conteúdo é fornecido. O uso de Bing Mapas é regido pelos termos de uso do usuário final Bing Mapas disponíveis em go.microsoft.com e na Instrução de Privacidade da Microsoft.
Além disso, você deve fornecer um link de hipertexto para Bing Mapas TOU, que está localizado aqui, na parte inferior de cada página em seu Aplicativo, onde os serviços podem ser acessados ou exibidos ou dentro dos termos de uso do aplicativo. Você é responsável por notificar os usuários finais de alterações no BING MAPAS TOU e cumprirá as instruções razoáveis da Microsoft para fazê-lo. Você não incentivará ou exigirá que qualquer usuário final viole os termos do BING MAPAS TOU. No caso de um usuário final violar o BING MAPAS TOU, a Microsoft poderá encerrar imediatamente esse contrato.

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 como os usuários podem marcar no local atual e exibir todos os marcar de localização anteriores usando bot. View View Exibir

Confira também