Criar uma página de configuraçãoCreate a configuration page

Uma página de configuração é um tipo especial de página de conteúdo que permite que os usuários configurem alguns aspectos de seu aplicativo do teams.A configuration page is a special type of content page that allows your users to configure some aspect of your Teams app. Normalmente, são usados como parte de:Typically these are used as part of:

  • Guia chat de grupo ou canal-a página de configuração permite coletar informações de seus usuários e definir a contentUrl página de conteúdo a ser exibida.A channel or group chat tab - The configuration page allows you to collect information from your users and set the contentUrl of the content page to display.
  • Uma extensão de mensagensA messaging extension
  • Um conector do Office 365A Office 365 Connector

Configurando uma guia chat de grupo ou canalConfiguring a channel or group chat tab

Uma página de configuração informa a página de conteúdo como ela deve renderizar.A configuration page informs the content page how it should render. O aplicativo deve fazer referência ao SDK e à chamada do cliente JavaScript do Microsoft Teams microsoft.initialize() .Your application must reference the Microsoft Teams JavaScript client SDK and call microsoft.initialize(). Além disso, suas URLs devem ser pontos de extremidade HTTPS seguros e disponíveis na nuvem.Additionally, your URLs must be secure HTTPS endpoints and available from the cloud. Veja a seguir um exemplo de página de configuração.Below is a configuration page example.

<head>
<script src='https://statics.teams.cdn.office.net/sdk/v1.6.0/js/MicrosoftTeams.min.js'></script>
</head>
    <body>
        <button onclick="(document.getElementById('icon').src = '/images/iconGray.png'); colorClickGray()">Select Gray</button>
        <img id="icon" src="/images/teamsIcon.png" alt="icon" style="width:100px" />
        <button onclick="(document.getElementById('icon').src = '/images/iconRed.png'); colorClickRed()">Select Red</button>

        <script>
            microsoftTeams.initialize();
            let saveGray = () => {
                microsoftTeams.settings.registerOnSaveHandler((saveEvent) => {
                    microsoftTeams.settings.setSettings({
                        websiteUrl: "https://yourWebsite.com",
                        contentUrl: "https://yourWebsite.com/gray",
                        entityId: "grayIconTab",
                        suggestedDisplayName: "MyNewTab"
                    });
                    saveEvent.notifySuccess();
                });
            }
            let saveRed = () => {
                microsoftTeams.settings.registerOnSaveHandler((saveEvent) => {
                    microsoftTeams.settings.setSettings({
                        websiteUrl: "https://yourWebsite.com",
                        contentUrl: "https://yourWebsite.com/red",
                        entityId: "redIconTab",
                        suggestedDisplayName: "MyNewTab"
                    });
                    saveEvent.notifySuccess();
                });
            }

            let gr = document.getElementById("gray").style;
            let rd = document.getElementById("red").style;

            const colorClickGray = () => {
                gr.display = "block";
                rd.display = "none";
                microsoftTeams.settings.setValidityState(true);
                saveGray()
            }

            const colorClickRed = () => {
                rd.display = "block";
                gr.display = "none";
                microsoftTeams.settings.setValidityState(true);
                saveRed();
            }
        </script>
    </body>
...

Aqui, os usuários são apresentados com dois botões de opção, selecione cinza ou selecione vermelho para exibir o conteúdo da guia com um ícone vermelho ou cinza.Here, the user is presented with two option buttons, Select Gray or Select Red to display the tab content with either a red or gray icon. A escolha do botão relativo dispara saveGray() ou saveRed() invoca o seguinte:Choosing the relative button fires saveGray() or saveRed() and invokes the following:

  1. O settings.setValidityState(true) é definido como true.The settings.setValidityState(true) is set to true.
  2. O microsoftTeams.settings.registerOnSaveHandler() manipulador de eventos é disparado.The microsoftTeams.settings.registerOnSaveHandler() event handler is triggered.
  3. O botão salvar na página de configuração do aplicativo, carregado no Microsoft Teams, está habilitado.The Save button on the app's configuration page, uploaded in Teams, is enabled.

Esse código permite que as equipes saibam que os requisitos de configuração foram satisfeitos e a instalação pode continuar.This code lets Teams know that the configuration requirements have been satisfied and the installation can proceed. Ao salvar, os parâmetros de settings.setSettings() são definidos, conforme definido pela Settings interface, para a instância atual (consulte interface de configurações ).On Save, the parameters of settings.setSettings() are set, as defined by the Settings interface, for the current instance (See Settings interface ). Por fim, saveEvent.notifySuccess() é chamado para indicar que a URL de conteúdo foi resolvida com êxito.Finally, saveEvent.notifySuccess() is called to indicate that the content URL has successfully resolved.

Observação

  • Se um manipulador de gravação foi registrado usando microsoftTeams.settings.registerOnSaveHandler() o, o retorno de chamada deve invocar saveEvent.notifySuccess() ou saveEvent.notifyFailure() indicar o resultado da configuração.If a save handler was registered using microsoftTeams.settings.registerOnSaveHandler(), the callback must invoke saveEvent.notifySuccess() or saveEvent.notifyFailure() to indicate the outcome of the configuration.
  • Se nenhum manipulador de salvamento foi registrado, a saveEvent.notifySuccess() chamada é automaticamente feita imediatamente após o usuário selecionando o botão salvar .If no save handler was registered, the saveEvent.notifySuccess() call is automatically made immediately upon the user selecting the Save button.

Obter dados de contexto para suas configurações de guiaGet context data for your tab settings

Sua guia pode exigir informações contextuais para exibir conteúdo relevante.Your tab might require contextual information to display relevant content. As informações contextuais podem aprimorar ainda mais o apelo da guia ao fornecer uma experiência de usuário mais personalizada.Contextual information can further enhance your tab's appeal by providing a more customized user experience.

A interface de contexto do Microsoft Teams define as propriedades que podem ser usadas para sua configuração de guia.The Teams Context interface defines the properties that can be used for your tab configuration. Você pode coletar os valores de variáveis de dados de contexto de duas maneiras:You can collect the values of context data variables in two ways:

  1. Insira espaços reservados para cadeia de caracteres de consulta de URL no seu manifesto configurationURL .Insert URL query string placeholders in your manifest's configurationURL.

  2. Use o método SDK do teams microsoftTeams.getContext((context) =>{} .Use the Teams SDK microsoftTeams.getContext((context) =>{} method.

Inserir espaços reservados no configurationURLInsert placeholders in the configurationURL

Os espaços reservados de interface de contexto podem ser adicionados à sua base configurationUrl .Context interface placeholders can be added to your base configurationUrl. Por exemplo:For example:

URL baseBase Url
...
"configurationUrl": "https://yourWebsite/config",
...

URL base com cadeias de caracteres de consultaBase URL with query strings

...
"configurationUrl": "https://yourWebsite/config?team={teamId}&channel={channelId}&{locale}"
...

Depois que a página for carregada, os espaços reservados de cadeia de caracteres de consulta serão atualizados pelo Teams com os valores relevantes.After your page has uploaded, the query string placeholders will be updated by Teams with the relevant values. Você pode incluir lógica na página de configuração para recuperar e usar esses valores.You can include logic in your configuration page to retrieve and use those values. Para obter mais informações sobre como trabalhar com cadeias de caracteres de consulta de URL, consulte URLSearchParams in MDN Web docs. Veja um exemplo de como extrair um valor da configurationURL Propriedade acima:For more information on working with URL query strings see URLSearchParams in MDN web docs. Here is an example of how to extract a value from the above configurationURL property:

<script>
   microsoftTeams.initialize();
   const getId = () => {
        let urlParams = new URLSearchParams(document.location.search.substring(1));
        let blueTeamId = urlParams.get('team');
        return blueTeamId
    }
//For testing, you can invoke the following to view the pertinent value:
document.write(getId());
</script>

Usar a getContext() função para recuperar o contextoUse the getContext() function to retrieve context

Quando invocado, a microsoftTeams.getContext((context) => {}) função recupera a interface de contexto.When invoked, the microsoftTeams.getContext((context) => {}) function retrieves the Context interface. Você pode adicionar essa função à página de configuração para recuperar os valores de contexto:You can add this function to your configuration page to retrieve context values:

<!-- `userPrincipalName` will render in the span with the id "user". -->

<span id="user"></span>
...
<script>
    microsoftTeams.getContext((context) =>{
        let userId = document.getElementById('user');
        userId.innerHTML = context.userPrincipalName;
    });
</script>
...

Contexto e autenticaçãoContext and Authentication

Você pode exigir autenticação antes de permitir que um usuário configure seu aplicativo ou seu conteúdo pode incluir fontes que têm seus próprios protocolos de autenticação.You might require authentication before allowing a user to configure your app or your content might include sources that have their own authentication protocols. Consulte autenticar um usuário em uma guia do Microsoft Teams as informações de contexto podem ser usadas para ajudar a construir solicitações de autenticação e URLs de página de autorização.See Authenticate a user in a Microsoft Teams tab Context information can be used to help construct authentication requests and authorization page URLs. Certifique-se de que todos os domínios usados nas páginas da guia estão listados na manifest.json validDomains matriz.Make sure that all domains used in your tab pages are listed in the manifest.json validDomains array.

Modificar ou remover uma guiaModify or remove a tab

As opções de remoção suportadas podem aprimorar ainda mais a experiência do usuário.Supported removal options can further refine the user experience. Você pode permitir que os usuários modifiquem, reconfigurem ou renomeie uma guia de grupo/canal, definindo a propriedade do manifesto canUpdateConfiguration como true .You can enable users to modify, reconfigure, or rename a group/channel tab by setting your manifest's canUpdateConfiguration property to true. Além disso, você pode designar o que acontece com o conteúdo quando uma guia é removida, incluindo uma página de opções de remoção no seu aplicativo e definir um valor para a removeUrl Propriedade na setSettings() configuração (veja abaixo).In addition, you can designate what happens to the content when a tab is removed by including a removal options page in your app and setting a value for the removeUrl property in the setSettings() configuration (see below). As guias pessoais não podem ser modificadas, mas podem ser desinstaladas pelo usuário.Personal tabs can't be modified but can be uninstalled by the user. Para obter mais informações, consulte criar uma página de remoção para sua guia.For more information, see Create a removal page for your tab.

Clientes móveisMobile clients

Se você optar por ter a guia canal/grupo exibida em clientes móveis do Microsoft Teams, a setSettings() configuração deverá ter um valor para a websiteUrl Propriedade (veja abaixo).If you choose to have your channel/group tab appear on Teams mobile clients, the setSettings() configuration must have a value for the websiteUrl property (see below). O suporte completo para guias em clientes móveis será lançado em breve.Full support for tabs on mobile clients will be released soon. Para se preparar para a atualização, siga as orientações para guias em celular ao criar suas guias.To prepare for the update, you should follow the guidance for tabs on mobile when creating your tabs.

Configuração do Microsoft Teams SetSettings () para a página de remoção e/ou clientes móveis:Microsoft Teams setSettings() configuration for removal page and/or mobile clients:

microsoftTeams.settings.setSettings({
    contentUrl: "add content page URL here",
    entityId: "add unique name here",
    suggestedDisplayName: "add name to display on tab here",
    websiteUrl: "URL REQUIRED FOR MOBILE CLIENTS",
    removeUrl: "ADD REMOVAL PAGE URL HERE"
});