Tutorial de código do Dice Roller

Artigo
05/28/2023

No aplicativo de exemplo Dice Roller, os usuários são mostrados um dado com um botão para rolar. Quando os dados são rolados, o SDK do Live Share usa o Fluid Framework para sincronizar os dados entre os clientes, para que todos vejam o mesmo resultado. Para sincronizar dados, execute as seguintes etapas no arquivo app.js:

Configurar o aplicativo
Ingressar em um contêiner do Fluid
Gravar o modo de exibição do estágio de reunião
Conectar o Modo de Exibição de Estágio de Reunião ao Live Share
Gravar o modo de exibição do painel lateral
Gravar o modo de exibição de configurações

Configurar o aplicativo.

Você pode começar importando os módulos necessários. O exemplo usa o LiveState DDS e o LiveShareClient do SDK do Live Share. O exemplo dá suporte à Extensibilidade de Reunião do Teams, portanto, você deve incluir a biblioteca de clientes JavaScript do Microsoft Teams (TeamsJS). Por fim, o exemplo foi projetado para ser executado localmente e em uma reunião do Teams, portanto, você precisa incluir mais peças do Fluid Framework para testar o exemplo localmente.

Os aplicativos criam contêineres Fluid usando um esquema que define um conjunto de objetos iniciais que estão disponíveis para o contêiner. O exemplo usa um LiveState para armazenar o valor de dados atual que foi rolado.

Os aplicativos de reunião do Teams exigem várias exibições, como conteúdo, configuração e estágio. Você pode criar uma start() função para ajudar a identificar a exibição. Isso ajuda a renderizar e executar qualquer inicialização necessária. O aplicativo dá suporte à execução local em um navegador da Web e de dentro de uma reunião do Teams. A start() função procura um inTeams=true parâmetro de consulta para determinar se está em execução no Teams.

Observação

Ao executar no Teams, seu aplicativo precisa chamar app.initialize() antes de chamar outros métodos teams-js.

Além do inTeams=true parâmetro de consulta, você pode usar um parâmetro de view=content|config|stage consulta para determinar a exibição que precisa ser renderizada.

import { app, pages, LiveShareHost } from "@microsoft/teams-js";
import { LiveShareClient, TestLiveShareHost, LiveState } from "@microsoft/live-share";

const searchParams = new URL(window.location).searchParams;
const root = document.getElementById("content");

// Define container schema

const containerSchema = {
  initialObjects: { diceState: LiveState },
};

// STARTUP LOGIC

async function start() {
  // Check for page to display
  let view = searchParams.get("view") || "stage";

  // Check if we are running on stage.
  if (!!searchParams.get("inTeams")) {
    // Initialize teams app
    await app.initialize();
  }

  // Load the requested view
  switch (view) {
    case "content":
      renderSidePanel(root);
      break;
    case "config":
      renderSettings(root);
      break;
    case "stage":
    default:
      const { container } = await joinContainer();
      renderStage(container.initialObjects.diceState, root);
      break;
  }
}

start().catch((error) => console.error(error));

Ingressar em um contêiner do Fluid

Nem todas as exibições do aplicativo precisam ser colaborativas. O modo de exibição stagesempre precisa de recursos colaborativos, o modo de exibição contentpode precisar de recursos colaborativos e o modo de exibição confignunca deve precisar de recursos colaborativos. Para os modos de exibição que precisam de recursos colaborativos, você precisará ingressar em um contêiner do Fluid associado à reunião atual.

Ingressar no contêiner para a reunião é tão simples quanto inicializar o LiveShareClient com uma LiveShareHost instância do SDK do Cliente do Teams e, em seguida, chamar seu joinContainer() método.

Ao executar localmente, você pode inicializar LiveShareClient com uma TestLiveShareHost instância.

async function joinContainer() {
  // Are we running in teams? If so, use LiveShareHost, otherwise use TestLiveShareHost
  const host = !!searchParams.get("inTeams")
    ? LiveShareHost.create()
    : TestLiveShareHost.create();
  // Create client
  const client = new LiveShareClient(host);
  // Join container
  return await client.joinContainer(containerSchema, onContainerFirstCreated);
}

Ao testar localmente, TestLiveShareHost atualiza a URL do navegador para conter a ID do contêiner de teste que foi criado. Copiar esse link para outras guias do navegador faz com que a junção LiveShareClient do contêiner de teste que foi criado. Se a modificação da URL de aplicativos interferir na operação do aplicativo, a estratégia usada para armazenar a ID dos contêineres de teste poderá ser personalizada usando as opções setLocalTestContainerId e getLocalTestContainerId passadas para LiveShareClient.

Gravar o Modo de Exibição de Estágio

Muitos aplicativos de Extensibilidade de Reunião do Teams foram projetados para React para sua estrutura de modo de exibição, mas isso não é necessário. Por exemplo, este exemplo usa métodos HTML/DOM padrão para renderizar um modo de exibição.

Iniciar com um modo de exibição estático

É fácil criar o modo de exibição usando dados locais sem nenhuma funcionalidade do Fluid e, em seguida, adicionar o Fluid alterando algumas partes principais do aplicativo.

A renderStage função acrescenta o stageTemplate ao elemento HTML passado e cria um rolo de dados de trabalho com um valor de dados aleatório cada vez que o botão Rolar é selecionado. O diceState será usado nas próximas etapas.

const stageTemplate = document.createElement("template");

stageTemplate["innerHTML"] = `
  <div class="wrapper">
    <div class="dice"></div>
    <button class="roll"> Roll </button>
  </div>
`;
function renderStage(diceState, elem) {
  elem.appendChild(stageTemplate.content.cloneNode(true));
  const rollButton = elem.querySelector(".roll");
  const dice = elem.querySelector(".dice");

  const updateDice = () => {
    // Get a random value between 1 and 6
    const diceValue = Math.floor(Math.random() * 6) + 1;
    // Unicode 0x2680-0x2685 are the sides of a die (⚀⚁⚂⚃⚄⚅).
    dice.textContent = String.fromCodePoint(0x267f + value);
  };
  rollButton.onclick = () => updateDice();
  updateDice(1);
}

Modificar o LiveState

Para começar a usar o Live Share no aplicativo, a primeira coisa a ser alterada é o que acontece quando o usuário seleciona o rollButton. Em vez de atualizar o estado local diretamente, o botão atualiza o número armazenado como um state valor em diceState. Sempre que você liga .set() com um novo state, esse valor é distribuído a todos os clientes. Qualquer alteração no diceState pode fazer com que um stateChanged evento seja emitido, e um manipulador de eventos pode disparar uma atualização do modo de exibição.

Esse padrão é comum nas estruturas de dados distribuídas fluida e live share porque permite que a exibição se comporte da mesma maneira para alterações locais e remotas.

rollButton.onclick = () =>
  diceState.set(Math.floor(Math.random() * 6) + 1);

Depender dos dados do Fluid

A próxima alteração que precisa ser feita é alterar a updateDice função para recuperar o valor de dados mais recente de LiveState cada vez updateDice que for chamado.

const updateDice = () => {
  const diceValue = diceState.state;
  dice.textContent = String.fromCodePoint(0x267f + diceValue);
};

Manipular alterações remotas

Os valores retornados de diceState são apenas um instantâneo do momento. Para manter os dados atualizados à medida que são alterados, um manipulador de eventos deve ser registrado diceState para chamar updateDice sempre que o stateChanged evento for enviado.

diceState.on("stateChanged", updateDice);

Inicializar o LiveState

Antes de começar a receber as alterações do Live Share no aplicativo, primeiro você deve chamar initialize() seu LiveState objeto com um valor inicial. Esse valor inicial não substitui nenhum estado existente enviado por outros usuários.

Depois de inicializar LiveState, o stateChanged evento registrado anteriormente começa a disparar sempre que uma alteração é feita. No entanto, para atualizar a interface do usuário dentro do valor inicial, chame updateDice().

await diceState.initialize(1);
updateDice();

Gravar o modo de exibição do painel lateral

O modo de exibição do painel lateral, carregado por meio da guia contentUrl com o contexto de quadro sidePanel, é exibido para o usuário em um painel lateral quando ele abre seu aplicativo em uma reunião. O objetivo do modo de exibição do painel lateral é permitir que um usuário selecione conteúdo para o aplicativo antes de compartilhar o aplicativo na fase de reunião. Para os aplicativos de SDK do Live Share, o modo de exibição do painel lateral também pode ser usado como uma experiência complementar para o aplicativo. A chamada joinContainer() do modo de exibição do painel lateral se conecta ao mesmo contêiner fluido ao qual o Modo de Exibição de Estágio está conectado. Esse contêiner pode então ser usado para se comunicar com o Modo de Exibição de Estágio. Verifique se você está se comunicando com o Modo de Exibição de Estágio de todos e a exibição do painel lateral.

O modo de exibição do painel lateral do exemplo solicita que o usuário selecione o botão Compartilhar na janela de conteúdo compartilhado.

const sidePanelTemplate = document.createElement("template");

sidePanelTemplate["innerHTML"] = `
  <style>
    .wrapper { text-align: center }
    .title { font-size: large; font-weight: bolder; }
    .text { font-size: medium; }
  </style>
  <div class="wrapper">
    <p class="title">Lets get started</p>
    <p class="text">Press the share to stage button to share Dice Roller to the meeting stage.</p>
  </div>
`;

function renderSidePanel(elem) {
  elem.appendChild(sidePanelTemplate.content.cloneNode(true));
}

Gravar o modo de exibição de configurações

A exibição de configurações, carregada configurationUrl no manifesto do aplicativo, é mostrada a um usuário quando ele adiciona seu aplicativo pela primeira vez a uma reunião do Teams. Esse modo de exibição permite que o desenvolvedor configure o contentUrl para a guia fixada à reunião com base na entrada do usuário. Esta página é necessária no momento, mesmo que nenhuma entrada do usuário seja necessária para definir o contentUrl.

Observação

Não há suporte para o Live Share no joinContainer() contexto de guia settings .

O modo de exibição de configurações do exemplo solicita que o usuário selecione o botão Salvar.

const settingsTemplate = document.createElement("template");

settingsTemplate["innerHTML"] = `
  <style>
    .wrapper { text-align: center }
    .title { font-size: large; font-weight: bolder; }
    .text { font-size: medium; }
  </style>
  <div class="wrapper">
    <p class="title">Welcome to Dice Roller!</p>
    <p class="text">Press the save button to continue.</p>
  </div>
`;

function renderSettings(elem) {
  elem.appendChild(settingsTemplate.content.cloneNode(true));

  // Save the configurable tab
  pages.config.registerOnSaveHandler((saveEvent) => {
    pages.config.setConfig({
      websiteUrl: window.location.origin,
      contentUrl: window.location.origin + "?inTeams=1&view=content",
      entityId: "DiceRollerFluidLiveShare",
      suggestedDisplayName: "DiceRollerFluidLiveShare",
    });
    saveEvent.notifySuccess();
  });

  // Enable the Save button in config dialog
  pages.config.setValidityState(true);
}

Testar localmente

Você pode testar seu aplicativo localmente, usando npm run start. Para obter mais informações, confira guia de início rápido.

Testar no Teams

Depois de começar a executar seu aplicativo localmente com npm run start, você poderá testar seu aplicativo em Teams. Se você quiser testar seu aplicativo sem implantação, baixe e use o ngrok serviço de túnel.

Criar um túnel ngrok para permitir que o Teams acesse seu aplicativo

Baixe ngrok.
Use o ngrok para criar um túnel com a porta 8080. Execute o seguinte comando:
```
 ngrok http 8080 --host-header=localhost
```
Um novo terminal ngrok é aberto com uma nova URL, por exemplo https:...ngrok.io. A nova URL é o túnel que aponta para seu aplicativo, que precisa ser atualizado em seu aplicativo manifest.json.

Criar o pacote do aplicativo para realizar o sideload no Teams

Ir para a pasta de exemplo live-share-sdk\samples\javascript\01.dice-roller do Dice Roller no computador. Você também pode marcar o manifest.json do exemplo Dice Roller no GitHub.
Abra manifest.json e atualize a URL de configuração.

Substitua https://<<BASE_URI_DOMAIN>> pelo ponto de extremidade http do ngrok.
Você pode atualizar essas propriedades nas seguintes situações:
- Defina developer.name como seu nome.
- Atualize developer.websiteUrl com seu site.
- Atualize developer.privacyUrl com sua política de privacidade.
- Atualize developer.termsOfUseUrl com seus termos de uso.
Compacte o conteúdo da pasta de manifesto para criar manifest.zip. Verifique se manifest.zip contém apenas o arquivo de origem manifest.json, o ícone color e o ícone outline.
1. No Windows, selecione todos os arquivos no diretório .\manifest e compacte-os.
Observação
- Não feche a pasta contendo.
- Dê um nome descritivo ao arquivo ZIP. Por exemplo, DiceRollerLiveShare.
Para obter mais informações sobre o manifesto, visite a documentação do manifesto do Teams

Fazer sideload do aplicativo em uma reunião

Abra o Teams.
Agende uma reunião no calendário do Teams. Certifique-se de convidar pelo menos um participante para a reunião.
Ingresse na reunião.
Na janela de reunião na parte superior, selecione + Aplicativos>Gerenciar aplicativos.
No painel Gerenciar aplicativos, selecione Carregar um aplicativo personalizado.
1. Se você não vir a opção para Carregar aplicativo personalizado, siga as instruções para habilitar aplicativos personalizados em seu locatário.
Selecione e carregue o arquivo manifest.zip do computador.
Selecione Adicionar para adicionar seu aplicativo de exemplo à reunião.
Selecione + Aplicativos, digite Dice Roller na caixa de pesquisa de Localizar um aplicativo.
Selecione o aplicativo para ativá-lo na reunião.
Selecione Salvar.

O aplicativo Dice Roller é adicionado ao painel de reunião do Teams.
No painel lateral, selecione o ícone Compartilhar na janela de conteúdo compartilhado. O Teams inicia uma sincronização ao vivo com os usuários no estágio de reunião na reunião.

Agora você deve ver o rolador de dados no estágio de reunião.

Os usuários convidados para a reunião podem ver seu aplicativo na janela de conteúdo compartilhado quando ingressam na reunião.

Implantação

Depois de se preparar para implantar seu código, você pode usar o Kit de Ferramentas do Teams ou o Portal do Desenvolvedor do Teams para provisionar e carregar o arquivo ZIP do aplicativo.

Observação

Você precisa adicionar seu appId provisionado ao manifest.json antes de carregar ou distribuir o aplicativo.

Exemplos de código

Nome do exemplo	Descrição	JavaScript
Dice Roller	Habilite todos os clientes conectados para rolar um dado e exibir o resultado.	Exibir

Próxima etapa

Principais recursos

Tutorial de código do Dice Roller

Configurar o aplicativo.

Ingressar em um contêiner do Fluid

Gravar o Modo de Exibição de Estágio

Iniciar com um modo de exibição estático

Modificar o LiveState

Depender dos dados do Fluid

Manipular alterações remotas

Inicializar o LiveState

Gravar o modo de exibição do painel lateral

Gravar o modo de exibição de configurações

Testar localmente

Testar no Teams

Criar um túnel ngrok para permitir que o Teams acesse seu aplicativo

Criar o pacote do aplicativo para realizar o sideload no Teams

Fazer sideload do aplicativo em uma reunião

Implantação

Exemplos de código

Próxima etapa

Confira também

Recursos adicionais

Recursos adicionais

Tutorial de código do Dice Roller

Configurar o aplicativo.

Ingressar em um contêiner do Fluid

Gravar o Modo de Exibição de Estágio

Iniciar com um modo de exibição estático

Conectar o Modo de Exibição de Estágio de Reunião ao Live Share

Modificar o LiveState

Depender dos dados do Fluid

Manipular alterações remotas

Inicializar o LiveState

Gravar o modo de exibição do painel lateral

Gravar o modo de exibição de configurações

Testar localmente

Testar no Teams

Criar um túnel ngrok para permitir que o Teams acesse seu aplicativo

Criar o pacote do aplicativo para realizar o sideload no Teams

Fazer sideload do aplicativo em uma reunião

Implantação

Exemplos de código

Próxima etapa

Confira também

Recursos adicionais

Recursos adicionais