Pedir permissões de dispositivo para a sua aplicação Teams

Você pode enriquecer seu aplicativo Teams com recursos nativos do dispositivo, como câmera, microfone e localização. Este documento orienta você sobre como solicitar o consentimento do usuário e acessar as permissões do dispositivo nativo.

Permissões de dispositivo nativo

Você deve solicitar as permissões do dispositivo para acessar as funcionalidades nativas do dispositivo. As permissões de dispositivo funcionam de forma semelhante para todas as construções de aplicações, como separadores, caixas de diálogo (referidos como módulos de tarefas no TeamsJS v1.x) ou extensões de mensagens. O usuário deve ir para a página de permissões nas configurações do Teams para gerenciar permissões de dispositivo. Ao acessar os recursos do dispositivo, você pode criar experiências mais avançadas na plataforma do Teams, como:

• Capturar e ver imagens
• Digitalizar QR ou código de barras
• Gravar e partilhar vídeos curtos
• Gravar memorandos de áudio e guardá-los para utilização posterior
• Utilizar as informações de localização do utilizador para apresentar informações relevantes

Acesse Permissões de acesso

A biblioteca de cliente JavaScript do Microsoft Teams fornece as ferramentas necessárias para que a sua aplicação Teams aceda às permissões de dispositivo do utilizador e crie uma experiência mais rica.

Embora o acesso a esses recursos seja padrão em navegadores da Web modernos, você deve informar o Teams sobre os recursos usados atualizando o manifesto do aplicativo. Esta atualização permite-lhe pedir permissões enquanto a sua aplicação é executada no ambiente de trabalho do Teams.

Gerenciar permissões

Um usuário pode gerenciar permissões de dispositivo nas configurações do Teams selecionando Permitir ou Negar permissões para aplicativos específicos.

Especificar permissões

Atualize o manifest.json do seu dispositivo adicionando devicePermissions e especificando qual das cinco propriedades a seguir você usa em seu aplicativo:

"devicePermissions": [
    "media",
    "geolocation",
    "notifications",
    "midi",
    "openExternal"
],

Cada propriedade permite-lhe pedir aos utilizadores que peçam o seu consentimento:

Para obter mais informações, consulte o manifesto do aplicativo.

Verificar permissões do seu aplicativo

Depois de adicionar devicePermissions ao manifesto do aplicativo, verifique as permissões usando a API de permissões HTML5 sem causar um prompt:

// Different query options:
navigator.permissions.query({ name: 'camera' });
navigator.permissions.query({ name: 'microphone' });
navigator.permissions.query({ name: 'geolocation' });
navigator.permissions.query({ name: 'notifications' });
navigator.permissions.query({ name: 'midi', sysex: true });

// Example:
navigator.permissions.query({name:'geolocation'}).then(function(result) {
  if (result.state == 'granted') {
    // Access granted
  } else if (result.state == 'prompt') {
    // Access has not been granted
  }
});

Usar APIs do Teams para obter permissões de dispositivo

Tire partido do HTML5 adequado ou da API do Teams para apresentar um pedido de consentimento para aceder às permissões do dispositivo.

Por exemplo:

• Para pedir ao utilizador para aceder à respetiva localização, tem de chamar getCurrentPosition():

  navigator.geolocation.getCurrentPosition(function (position) { /*... */ });
  

• Para pedir ao utilizador para aceder à câmara no ambiente de trabalho ou na Web, tem de chamar getUserMedia():

  navigator.mediaDevices.getUserMedia({ audio: true, video: true });
  

• Para capturar as imagens em dispositivos móveis, o Teams Mobile pede permissão quando liga captureImage()para :

          function captureImage() {
          microsoftTeams.media.captureImage((error, files) => {
              // 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);
                  }
              } else if (files) {
                  image = files[0].content;
                  // Adding this image string in src attr of image tag will display the image on web page.
                  let imageString = "data:" + item.mimeType + ";base64," + image;
              }
          });
      } 
  

• As notificações solicitam ao utilizador quando chama requestPermission():

  Notification.requestPermission(function(result) { /* ... */ });
  

• Para utilizar a câmara ou aceder à galeria de fotografias, a aplicação Teams pede permissão quando chama selectMedia():

   function selectMedia() {
   microsoftTeams.media.selectMedia(mediaInput, (error, attachments) => {
       // 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);
           }
       } else if (attachments) {
           // creating image array which contains image string for all attached images. 
           const imageArray = attachments.map((item, index) => {
               return ("data:" + item.mimeType + ";base64," + item.preview)
           })
       }
   });
  } 
  

• Para usar o microfone, o Aplicativo móvel do Teams solicita permissão quando você chama selectMedia():

   function selectMedia() {
   microsoftTeams.media.selectMedia({ maxMediaCount: 1, mediaType: microsoftTeams.media.MediaType.Audio }, (error: microsoftTeams.SdkError, attachments: microsoftTeams.media.Media[]) => {
       // 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);
           }
       }
  
       if (attachments) {
           // taking the first attachment  
           let audioResult = attachments[0];
  
           // setting audio string which can be used in Video tag
           let audioData = "data:" + audioResult.mimeType + ";base64," + audioResult.preview
       }
   });
   }
  

• Para pedir ao utilizador para partilhar a localização na interface de mapa, a aplicação Teams pede permissão quando chama getLocation():

  • TeamsJS v2
  • TeamsJS v1

  function getLocation() {
    location.getLocation({ allowChooseLocation: true, showMap: true }).then((location) => { 
        let currentLocation = JSON.stringify(location);
    }).catch((error) => { /*Error getting location*/ })} 
  

Eis como os pedidos de permissões de dispositivos são apresentados aos utilizadores em dispositivos móveis e no ambiente de trabalho.

Comportamento de permissão entre sessões de início de sessão

As permissões do dispositivo são armazenadas para cada sessão de início de sessão. Significa que, se iniciar sessão noutra instância do Teams, por exemplo, noutro computador, as permissões de dispositivo das sessões anteriores não estarão disponíveis. Por conseguinte, tem de voltar a reunir as permissões do dispositivo para a nova sessão. Também significa que, se terminar sessão no Teams ou mudar de inquilino no Teams, as permissões do seu dispositivo serão eliminadas da sessão de início de sessão anterior.

Exemplo de código

Próxima etapa

Confira também

• Funcionalidades de dispositivo
• Integrar recursos de mídia
• Integre o recurso de scanner QR ou de código de barras no Teams
• Integrar funcionalidades de localização no Teams
• APIs de aplicações de reunião