Partilhar via

Integrar os recursos de localização

  • Artigo

Pode integrar as capacidades de localização na sua aplicação Teams com o SDK de cliente JavaScript do Microsoft Teams, que fornece APIs bem definidas e as ferramentas necessárias para a sua aplicação aceder às capacidades de dispositivo nativo do utilizador. A capacidade de localização está disponível para o cliente Web do Teams, ambiente de trabalho e dispositivos móveis.

Pode utilizar a biblioteca de cliente JavaScript (TeamsJS) do Microsoft Teams, que fornece as ferramentas necessárias para que a sua aplicação aceda às capacidades nativas do dispositivo do utilizador. Use as APIs de localização, como getLocation e showLocation, para integrar os recursos em seu aplicativo.

Vantagens

Pode utilizar as APIs de localização, como getLocation e showLocation , para integrar as capacidades na sua aplicação.

Observação

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

A vantagem de integrar capacidades de localização nas suas aplicações do Teams é utilizar a funcionalidade de localização no cliente Web do Teams, no ambiente de trabalho e no dispositivo móvel com a biblioteca de cliente JavaScript do Microsoft Teams. Os cenários seguintes mostram as vantagens das capacidades de localização:

A principal vantagem da integração de capacidades de localização nas suas aplicações do Teams é que permite que os programadores de aplicações Web na plataforma Teams utilizem a funcionalidade de localização com a biblioteca de cliente JavaScript do Microsoft Teams.

  • Partilhe dados de saúde autênticos de torres de rede móvel com a gestão. 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 equipa de suporte técnico numa área especificada. A aplicação pede à equipa de suporte para partilhar a sua localização atual, que a gestão pode utilizar para alocar pedidos de TI ao técnico de suporte mais próximo depois de verificar o respetivo perfil.

  • Comunique a localização depois de concluir uma tarefa no campo. A aplicação de processamento de tarefas pede permissão para localizar a localização. Depois de o utilizador conceder permissão, a aplicação deteta a localização exata. O utilizador também pode selecionar uma localização ao arrastar um pino para a localização de conclusão da tarefa sobre o mapa.

  • Capte a presença através de selfies dentro da loja de retalho. O gerente da loja pode acompanhar a presença dos trabalhadores pedindo-lhes que partilhem uma selfie através de uma aplicação de presença. Os dados de localização são capturados e enviados juntamente com a imagem. Este cenário aplica-se principalmente aos trabalhadores de primeira linha.

A imagem seguinte ilustra a experiência da aplicação Web da API getLocation:

Ilustração a mostrar o seletor de localização.

Para integrar as capacidades de localização, tem de:

Atualizar manifesto

Atualize seu aplicativo do Teams do arquivo manifest.json do adicionando a devicePermissions propriedade e especificando geolocation. Permite que a sua aplicação peça as permissões necessárias aos utilizadores antes de começarem a utilizar as capacidades de localização. A atualização para o manifesto do aplicativo é a seguinte:

"devicePermissions": [
    "geolocation",
],

Observação

APIs de Localização

A tabela seguinte lista o conjunto de APIs para ativar as capacidades de localização do dispositivo:

API Descrição Configuração de entrada
getLocation Fornece a localização atual do dispositivo do utilizador ou abre o seletor de localização nativo e devolve a localização escolhida pelo utilizador. A getLocation API utiliza os dois parâmetros de entrada seguintes como parte da interface LocationProps : allowChooseLocation, showMap:
A experiência deriva da combinação destes dois parâmetros de entrada:
- (verdadeiro, verdadeiro): é iniciado um mapa e o utilizador pode escolher qualquer localização no mesmo.
- (verdadeiro, falso): é iniciado um mapa e o utilizador pode escolher qualquer localização no mesmo.
- (falso, verdadeiro): é iniciado um mapa. O utilizador só pode submeter a localização atual.
- (falso, falso): o mapa não foi iniciado. A localização atual do utilizador é obtida.
showLocation Mostra a localização no mapa. Utiliza uma única localização do parâmetro de entrada, que contém as coordenadas da localização a mostrar no mapa.

Observação

Para getLocation a API:

  • Se allowChooseLocation estiver definido como verdadeiro, showMap será ignorado.
  • showMap= falso não é suportado na Web ou no ambiente de trabalho do Teams.

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

Importante

Quando a sua aplicação ou serviços acedem a uma API da Microsoft que fornece uma localização através do Mapas Bing, compreende e concorda que qualquer conteúdo fornecido através do Mapas Bing, incluindo geocódigos, só pode ser utilizado na API da Microsoft através da qual o conteúdo é fornecido. A sua utilização do Bing Maps é regida pelos Termos de Utilização do Utilizador Final do Bing Maps disponíveis em go.microsoft.com e na Declaração de Privacidade da Microsoft.
Além disso, tem de fornecer uma ligação de hipertexto para a TOU do Bing Maps, que está localizada aqui, na parte inferior de cada página da sua Aplicação, onde os serviços podem ser acedidos, visualizados ou dentro dos termos de utilização da sua aplicação. É responsável por notificar os utilizadores finais das alterações à TOU do Bing Maps e está em conformidade com as instruções razoáveis da Microsoft para o fazer. Não irá encorajar ou exigir que qualquer utilizador final viole os termos da TOU do Bing Maps. Caso um utilizador final viole a TOU do Bing Maps, a Microsoft poderá cessar imediatamente o presente contrato.

Trechos de código

  • Chame getLocation a API para obter a localização:

    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 apresentar a localização:

    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 utilizador 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 utilizadores podem verificar a localização atual e ver todos os check-ins de localização anteriores com o bot. View View Exibir

Confira também