Integrar recursos de mídia

Você pode integrar recursos de dispositivo nativo, como câmera e microfone com seu aplicativo do Teams. Para integração, você pode usar a biblioteca de clientes JavaScript do Microsoft Teams que fornece as ferramentas necessárias para seu aplicativo acessar as permissões de dispositivo de um usuário. Use APIs de capacidade de mídia adequadas para integrar os recursos do dispositivo, como câmera e microfone com a plataforma teams em seu aplicativo Microsoft Teams, e criar uma experiência mais rica. O recurso de mídia está disponível para o cliente Web do Teams, a área de trabalho e o celular. Para integrar recursos de mídia, você deve atualizar o arquivo de manifesto do aplicativo e chamar as APIs de capacidade de mídia.

Para uma integração eficaz, você deve ter uma boa compreensão dos snippets de código para chamar as respectivas APIs, o que permite usar recursos de mídia nativa. É importante se familiarizar com os erros de resposta da API para lidar com os erros no seu aplicativo do Teams.

Vantagens

A vantagem de integrar recursos de dispositivo em seus aplicativos do Teams é que ele usa controles nativos do Teams para fornecer uma experiência avançada e imersiva para seus usuários. Os seguintes cenários mostram as vantagens das funcionalidades de mídia:

• Permitir que o usuário capture os mockups brutos desenhados em um quadro físico por meio de seu celular e use as imagens capturadas como opções de pesquisa no chat do grupo do Teams.

• Permitir que o usuário grave a mensagem de áudio e anexe-a a um tíquete de incidente.

• Permitir que o usuário examine os documentos físicos do smartphone para registrar uma declaração de seguro de carro.

• Permitir que o usuário grave um vídeo em um workite e carregue-o para atendimento.

Observação

• Atualmente, o Teams não dá suporte a permissões de dispositivo na janela de chat pop-out, guias e no painel lateral da reunião.
  
• As permissões do dispositivo são diferentes no navegador. Para saber mais, consulte permissões de dispositivo do navegador.
• O prompt de permissões de solicitação é exibido automaticamente no celular quando uma API relevante do Teams é iniciada. Para mais informações, consulte solicitar permissões de dispositivos.

Atualizar manifesto

Atualize seu aplicativo do Teams do arquivo manifest.json do adicionando a devicePermissions propriedade e especificando media. Ele permite que seu aplicativo peça permissões necessárias dos usuários antes de começar a usar a câmera para capturar a imagem, abrir a galeria para selecionar uma imagem para enviar como um anexo ou usar o microfone para gravar a conversa. A atualização para o manifesto do aplicativo é a seguinte:

"devicePermissions": [
    "media",
],

Observação

A API de Mídia não tem suporte no novo cliente do Teams. Recomendamos que você use HTML5 media.

APIs de funcionalidade de mídia

As APIs captureImage, selectMedia, getMedia e viewImages permitem que você use os recursos de mídia nativa da seguinte maneira:

• Use o microfone para permitir que os usuários gravem áudio (grave 10 minutos de conversa) do dispositivo.
• Use o controle de câmera nativo para permitir que os usuários capturem e anexem imagens e capturem vídeos (grave até cinco minutos de vídeo) em movimento.
• Use o suporte da galeria nativo para permitir que os usuários selecionem imagens do dispositivo como anexos.
• Use o controle do visualizador de imagens nativo para visualizar várias imagens ao mesmo tempo.
• Dá suporte a uma grande transferência de imagem (de 1 MB a 50 MB) por meio da ponte TeamsJS.
• Dê suporte a recursos avançados de imagem , permitindo que os usuários visualizem e editem imagens.
• Examine documentos, quadros e cartões de visita pela câmera.

Importante

• Você pode invocar as captureImageAPIs , selectMedia, getMediae viewImages de várias superfícies do Teams, incluindo caixas de diálogo (conhecidas como módulos de tarefa no TeamsJS v1.x), guias e aplicativos pessoais. Para obter mais informações, confira os pontos de entrada para aplicativos do Teams.
  
• A selectMedia API dá suporte a recursos de câmera e microfone por meio de diferentes configurações de entrada.
• A selectMedia API para acessar o recurso de microfone dá suporte somente para clientes móveis.
• A contagem máxima de imagens carregadas é determinada por maxMediaCount e também pelo tamanho total da matriz retornada pela selectMedia API. Verifique se o tamanho da matriz não excede 20 MB, se o tamanho da matriz exceder 20 MB, a API gerará um código de erro 10000 que é SIZE_EXCEEDED erro.

A tabela a seguir lista o conjunto de APIs para habilitar os recursos de mídia do dispositivo:

API	Descrição
captureImage (Câmera)	A API permite que os usuários ativem a câmera e capturem uma imagem ou selecionem mídia na galeria. Quando o captureImage retorno de chamada é disparado, a imagem é compartilhada como um arquivo. A API restringe os usuários a selecionar ou capturar uma única imagem para compartilhamento e é compatível apenas com clientes móveis.
selectMedia (Câmera)	A selectMedia API permite que os usuários capturem ou selecionem mídia na câmera ou galeria de seu dispositivo e, em seguida, a retornem ao aplicativo Web. Os usuários têm a capacidade de editar, cortar, girar, anotar ou desenhar imagens antes do envio. Em resposta ao selectMedia, o aplicativo Web obtém as IDs de mídia das imagens selecionadas e uma miniatura da mídia escolhida. Você pode configurar ainda mais essa API usando a configuração ImageProps .
selectMedia (Microphone)	Para acessar o recurso de microfone, defina o mediaType como 4 (Áudio) na selectMedia API. Essa API permite que os usuários gravem áudio usando o microfone do dispositivo e retorna os clipes gravados para o aplicativo Web. Os usuários têm a opção de pausar, gravar novamente ou visualizar a gravação antes de enviar. Em resposta a selectMedia, o aplicativo Web recebe as IDs de mídia das gravações de áudio selecionadas. Se você precisar definir uma duração específica para a gravação, use maxDuration. A duração atual da gravação é definida como 10 minutos, após a qual a gravação termina automaticamente.
getMedia	Essa API recupera a mídia capturada pela API selectMedia em partes, independentemente do tamanho da mídia. Essas partes são montados e enviados de volta para o aplicativo Web como um arquivo ou blob. Dividir mídia em partes menores facilita a transferência de arquivos grandes.
viewImages	Essa API permite que o usuário exiba imagens no modo de tela inteira como uma lista rolável.

A imagem a seguir mostra a experiência do aplicativo Web da captureImage API para o recurso de imagem no teams móvel:

• Inicie a câmera e capture a imagem para compartilhar:

  

• Selecione mídia na galeria para compartilhar:

  

Você pode exibir a experiência do aplicativo Web da API para área selectMedia de trabalho do Teams e móvel.

Dispositivo móvel

A imagem a seguir mostra a experiência do aplicativo Web da selectMedia API para o recurso de imagem:

Observação

Em dispositivos com versão do Android com menos de 7 anos, a selectMedia API inicia a experiência de câmera nativa do Android em vez da experiência de câmera nativa do Teams.

A imagem a seguir mostra a experiência do aplicativo Web da selectMedia API para o recurso de microfone:

Desktop

A imagem a seguir mostra a experiência do aplicativo Web da selectMedia API para o recurso de imagem:

Tratamento de erros

Certifique-se de lidar com esses erros adequadamente em seu aplicativo do Teams. A tabela a seguir lista os códigos de erro e as descrições nas quais os erros são gerados:

Código de erro	Nome do erro	Descrição
100	NÃO_SUPORTADO_NA_PLATAFORMA	A API não é compatível com a plataforma atual.
404	FILE_NOT_FOUND	O arquivo especificado não é encontrado no local determinado.
500	INTERNAL_ERROR	Erro interno encontrado durante a execução da operação necessária.
1.000	PERMISSION_DENIED	A permissão foi negada pelo usuário.
3000	NO_HW_SUPPORT	O hardware não dá suporte à funcionalidade.
4000	ARGUMENTOS_INVÁLIDOS	Um ou mais argumentos são inválidos.
8000	ABORTAR_USUÁRIO	O usuário anula a operação.
9000	ANTIGA_PLATAFORMA	O código da plataforma está desatualizado e não implementa essa API.
10000	SIZE_EXCEEDED	O valor retornado é muito grande e excedeu os limites de tamanho da plataforma.

Trechos de código

• Chame captureImage a API para iniciar e capturar imagem usando a câmera:

  microsoftTeams.media.captureImage((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);
    }
  } else if (attachments) {
    let y = attachments[0];
    img.src = ("data:" + y.mimeType + ";base64," + y.preview);
  }
  });
  

• Chame selectMedia a API para capturar e selecionar mídia na câmera ou galeria do dispositivo:

  let imageProp: microsoftTeams.media.ImageProps = {
      sources: [microsoftTeams.media.Source.Camera, microsoftTeams.media.Source.Gallery],
      startMode: microsoftTeams.media.CameraStartMode.Photo,
      ink: false,
      cameraSwitcher: false,
      textSticker: false,
      enableFilter: true,
  };
  let mediaInput: microsoftTeams.media.MediaInputs = {
      mediaType: microsoftTeams.media.MediaType.Image,
      maxMediaCount: 10,
      imageProps: imageProp
  };
  microsoftTeams.media.selectMedia(mediaInput, (error: microsoftTeams.SdkError, attachments: microsoftTeams.media.Media[]) => {
      if (error) {
          if (error.message) {
              alert(" ErrorCode: " + error.errorCode + error.message);
          } else {
              alert(" ErrorCode: " + error.errorCode);
          }
      }
      if (attachments) {
          let y = attachments[0];
          img.src = ("data:" + y.mimeType + ";base64," + y.preview);
      }
  });
  

• Chame selectMedia a API para capturar vídeos usando a câmera:

  • Capturando vídeos com fullscreen: true:

    fullscreen: true abre a câmera no modo de gravação de vídeo. Ele fornece uma opção para usar a câmera frontal e traseira e também fornece outros atributos, conforme mencionado no exemplo a seguir:

    
      const defaultLensVideoProps: microsoftTeams.media.VideoProps = {
          sources: [microsoftTeams.media.Source.Camera, microsoftTeams.media.Source.Gallery],
          startMode: microsoftTeams.media.CameraStartMode.Video,
          cameraSwitcher: true,
          maxDuration: 30
     }
      const defaultLensVideoMediaInput: microsoftTeams.media.MediaInputs = {
          mediaType: microsoftTeams.media.MediaType.Video,
          maxMediaCount: 6,
          videoProps: defaultLensVideoProps
     }
    

  • Capturando vídeos com fullscreen: false:

    fullscreen: false abre a câmera no modo de gravação de vídeo e usa apenas a câmera frontal. Normalmente fullscreen: false , é usado quando o usuário deseja gravar vídeo durante a leitura de conteúdo na tela do dispositivo.

    Esse modo também é isStopButtonVisible: true compatível com o que adiciona um botão stop na tela que permite que o usuário interrompa a gravação. Se isStopButtonVisible: false, a gravação puder ser interrompida chamando a API mediaController ou quando a duração da gravação tiver atingido maxDuration o tempo especificado.

    A seguir está um exemplo para interromper a gravação com maxDuration o tempo especificado:

       const defaultNativeVideoProps: microsoftTeams.media.VideoProps = {
          maxDuration: 30,
          isFullScreenMode: false,
          isStopButtonVisible: false,
          videoController: new microsoftTeams.media.VideoController(videoControllerCallback)
      }
       const defaultNativeVideoMediaInput: microsoftTeams.media.MediaInputs = {
          mediaType: microsoftTeams.media.MediaType.Video,
          maxMediaCount: 1,
          videoProps: defaultNativeVideoProps
      }
    

    A seguir está um exemplo para interromper a gravação chamando a API mediaController:

       const defaultNativeVideoProps: microsoftTeams.media.VideoProps = {
          videoController.stop(),
          isFullScreenMode: false,
          isStopButtonVisible: false,
          videoController: new microsoftTeams.media.VideoController(videoControllerCallback)
      }
       const defaultNativeVideoMediaInput: microsoftTeams.media.MediaInputs = {
          mediaType: microsoftTeams.media.MediaType.Video,
          maxMediaCount: 1,
          videoProps: defaultNativeVideoProps
      }
    

• Chame selectMedia a API para capturar imagens e vídeos usando a câmera:

  Essa API permite que os usuários selecionem entre capturar uma imagem ou um vídeo.

  
    const defaultVideoAndImageProps: microsoftTeams.media.VideoAndImageProps = {
      sources: [microsoftTeams.media.Source.Camera, microsoftTeams.media.Source.Gallery],
      startMode: microsoftTeams.media.CameraStartMode.Photo,
      ink: true,
      cameraSwitcher: true,
      textSticker: true,
      enableFilter: true,
      maxDuration: 30
    }
  
    const defaultVideoAndImageMediaInput: microsoftTeams.media.MediaInputs = {
      mediaType: microsoftTeams.media.MediaType.VideoAndImage,
      maxMediaCount: 6,
      videoAndImageProps: defaultVideoAndImageProps
    }
  
    let videoControllerCallback: microsoftTeams.media.VideoControllerCallback = {
      onRecordingStarted() {
        console.log('onRecordingStarted Callback Invoked');
      },
    };
  
    microsoftTeams.media.selectMedia(defaultVideoAndImageMediaInput, (error: microsoftTeams.SdkError, attachments: microsoftTeams.media.Media[]) => {
      if (error) {
          if (error.message) {
              alert(" ErrorCode: " + error.errorCode + error.message);
          } else {
              alert(" ErrorCode: " + error.errorCode);
          }
      }
  
      var videoElement = document.createElement("video");
      attachments[0].getMedia((error: microsoftTeams.SdkError, blob: Blob) => {
      if (blob) {
          if (blob.type.includes("video")) {
              videoElement.setAttribute("src", URL.createObjectURL(blob));
          }
      }
      if (error) {
          if (error.message) {
              alert(" ErrorCode: " + error.errorCode + error.message);
          } else {
              alert(" ErrorCode: " + error.errorCode);
          }
      }
      });
      });
  
  

• Chame getMedia a API para recuperar mídia grande em partes:

  let media: microsoftTeams.media.Media = attachments[0]
  media.getMedia((error: microsoftTeams.SdkError, blob: Blob) => {
      if (blob) {
          if (blob.type.includes("image")) {
              img.src = (URL.createObjectURL(blob));
          }
      }
      if (error) {
          if (error.message) {
              alert(" ErrorCode: " + error.errorCode + error.message);
          } else {
              alert(" ErrorCode: " + error.errorCode);
          }
      }
  });
  

• Chamar viewImages a API por ID, que é retornada pela selectMedia API:

  // View images by id:
  // Assumption: attachmentArray = select Media API Output
  let uriList = [];
  if (attachmentArray && attachmentArray.length > 0) {
      for (let i = 0; i < attachmentArray.length; i++) {
          let file = attachmentArray[i];
          if (file.mimeType.includes("image")) {
              let imageUri = {
                  value: file.content,
                  type: 1,
              }
              uriList.push(imageUri);
          } else {
              alert("File type is not image");
          }
      }
  }
  if (uriList.length > 0) {
      microsoftTeams.media.viewImages(uriList, (error: microsoftTeams.SdkError) => {
          if (error) {
              if (error.message) {
                  output(" ErrorCode: " + error.errorCode + error.message);
              } else {
                  output(" ErrorCode: " + error.errorCode);
              }
          }
      });
  } else {
      output("Url list is empty");
  }
  

• API de chamada viewImages por URL:

  // View Images by URL:
  // Assumption 2 urls, url1 and url2
  let uriList = [];
  if (URL1 != null && URL1.length > 0) {
      let imageUri = {
          value: URL1,
          type: 2,
      }
      uriList.push(imageUri);
  }
  if (URL2 != null && URL2.length > 0) {
      let imageUri = {
          value: URL2,
          type: 2,
      }
      uriList.push(imageUri);
  }
  if (uriList.length > 0) {
      microsoftTeams.media.viewImages(uriList, (error: microsoftTeams.SdkError) => {
          if (error) {
              if (error.message) {
                  output(" ErrorCode: " + error.errorCode + error.message);
              } else {
                  output(" ErrorCode: " + error.errorCode);
              }
          }
      });
  } else {
      output("Url list is empty");
  }
  

• Chamadas selectMedia e getMedia APIs para gravar áudio por meio do microfone:

    let mediaInput: microsoftTeams.media.MediaInputs = {
      mediaType: microsoftTeams.media.MediaType.Audio,
      maxMediaCount: 1,
      };
      microsoftTeams.media.selectMedia(mediaInput, (error: microsoftTeams.SdkError, attachments: microsoftTeams.media.Media[]) => {
          if (error) {
              if (error.message) {
                  alert(" ErrorCode: " + error.errorCode + error.message);
              } else {
                  alert(" ErrorCode: " + error.errorCode);
              }
          }
      // If you want to directly use the audio file (for smaller file sizes (~4MB))    if (attachments) {
      let audioResult = attachments[0];
      var videoElement = document.createElement("video");
      videoElement.setAttribute("src", ("data:" + audioResult.mimeType + ";base64," + audioResult.preview));
      audioResult.getMedia((error: microsoftTeams.SdkError, blob: Blob) => {
      if (blob) {
          if (blob.type.includes("video")) {
              videoElement.setAttribute("src", URL.createObjectURL(blob));
          }
      }
      if (error) {
          if (error.message) {
              alert(" ErrorCode: " + error.errorCode + error.message);
          } else {
              alert(" ErrorCode: " + error.errorCode);
          }
      }
  });
  });
  

Download de arquivos no teams móvel

Você pode configurar um aplicativo para permitir que os usuários baixem arquivos da visão da Web para seu dispositivo móvel.

Observação

O download de arquivos só tem suporte no cliente móvel do Android Teams e somente arquivos não autenticados podem ser baixados.

Para habilitar, siga as etapas:

1. Atualize o arquivo manifest.json do aplicativo teams adicionando a devicePermissions propriedade e especificando media conforme mostrado no manifesto de atualização.

2. Use o seguinte formato e adicione o atributo de download HTML à página da Web:

   <a href="path_to_file" download="download">Download</a>
   

Confira também

• Funcionalidades de dispositivo
• Integrar o recurso de leitor de código QR ou de barras no Teams
• Integrar funcionalidades de localização no Teams
• Integrar o Seletor de Pessoas
• Requisitos e considerações para bots de mídia hospedados pelo aplicativo
• Esquema de manifesto do aplicativo para o Teams
• Planejar guias responsivas para o aplicativo móvel do Teams