Visão geral das opções de programabilidade do Flex UI (IU do Flex)

Manager

O Flex Manager (Gerente do Flex) é o ponto de acesso para controlar sua instância do Flex e todos os produtos Twilio subjacentes usados para comunicações e tarefas de atribuição. Isso significa que, em seu projeto Flex, você pode acessar o TaskRouter ou o cliente de Chat diretamente pelo Flex Manager (Gerente do Flex).

Além do próprio Flex, o Manager (Gerente do Flex) também dá acesso aos SDKs Conversations, Sync, Voice e TaskRouter.

Como obter a instância do Manager

Você pode acessar o Manager da seguinte maneira:

No método init do seu plugin

init(flex, manager) {
  // use manager here
}

Em seu aplicativo, chamando o método 'getInstance'

Flex.Manager.getInstance()

ou chamando o método 'create' ao inicializar o Flex

return Flex
  .provideLoginInfo(configuration, "#container")
  .then(() => Flex.Manager.create(configuration))
  .then(manager => {
    // use manager here
  })
  .catch(error => handleError(error));

Você pode fazer o check-out do projeto de amostra sobre como inicializar o Flex.

Para obter a descrição detalhada do Manager, visite nossos documentos da API Flex UI (IU do Flex)

Configuração

A configuração do Flex UI (IU do Flex) permite que você controle a maneira como o app geral é carregado, bem como o comportamento de Componentes do Flex individuais.

Os Componentes do Flex podem ser modificados de duas maneiras:

por meio da componentProps no Objeto de configuração
por meio da API defaultProps

Usando `componentProps` no Objeto de configuração

Exemplo

var appConfig = {

  componentProps: {
    CRMContainer: {
      uriCallback: (task) => task
        ? `https://www.bing.com/search?q=${task.attributes.name}`
        : "http://bing.com"
    }
  },
};

API React defaultProps

Você também pode configurar propriedades padrão para componentes em um plugin usando a API React defaultprops de forma programática:

componentProps: { [Component Name]: { [Prop Name]: [PropValue] } }

Exemplo

flex.CRMContainer
  .defaultProps
  .uriCallback = (task) => task
    ? `https://www.bing.com/search?q=${task.attributes.name}`
    : "http://bing.com/";

flex.MainHeader
  .defaultProps
  .logoUrl = "https://static0.twilio.com/marketing/bundles/archetype.alpha/img/logo-wordmark--red.svg";

Acesse os documentos da API Flex UI (IU do Flex) para obter a descrição completa do Objeto de configuração Objeto de configuração e Adereços de componente.

Substituição das strings de idioma

Você pode substituir qualquer string editando o objeto strings na instância do Flex Manager (Gerente do Flex):

flex.Manager.getInstance().strings.TaskLineCallAssigned = "I am a content string!";

5. Task list - String customization_slice.png

Para obter a lista completa de strings de IU, consulte os documentos da API da UI Flex (IU do Flex)

Suporte a modelos com sintaxe no estilo Mustache

O Flex usa Handlebars para modelar e suporta a sintaxe e as expressões do estilo Mustache nas strings de conteúdo, ou seja, incorporar espaços reservados de valor entre chaves duplas. Veja um exemplo:

manager.strings.TaskInfoPanelContent = `
<h1>TASK CONTEXT</h1>
<h2>Task type</h2>
<p>1{{task.attributes.title}}</p>
<p>2{{task.title}}</p>
<h2>Task created on</h2>
<p>{{task.dateCreated}}</p>
<h2>Task priority</h2>
<p>{{task.priority}}</p>
<h2>Task queue</h2>
<p>{{task.taskQueueName}}</p>
<hr />
<h1>CUSTOMER CONTEXT</h1>
<h2>Customer name / phone number</h2>
<p>{{task.attributes.name}}</p>
`;

Dentro do contexto de cada componente e string, conteúdo dinâmico adicional está disponível: por exemplo, acessando Propriedades ou atributos da tarefa.

Acesso ao contexto da tarefa: propriedades e atributos

Dentro do contexto de cada componente e string, conteúdo dinâmico adicional está disponível: por exemplo, acessando Propriedades ou atributos da tarefa.

Aqui está um exemplo do uso em um modelo de algumas das propriedades e atributos listados acima:

manager.strings.TaskExtraInfo = "My task {{task.attributes.name}} was created on {{task.dateCreated}}";

Funções auxiliares

As funções auxiliares fornecem uma maneira de personalizar o texto com informações dinâmicas. Aqui está um exemplo do uso de uma função auxiliar para habilitar atualizações dinâmicas:

manager.strings.TaskExtraInfo = "Time since last update: {{helper.durationSinceUpdate}}";

Você pode encontrar todas as funções auxiliares disponíveis nos documentos da API Flex UI (IU do Flex).

Temas do Flex UI (IU do Flex)

A interface de criação de temas do Flex UI (IU do Flex) mapeia de perto para o sistema de design Twilio Paste. Essa estrutura é baseada no conceito de tokens de projeto, um conjunto de variáveis que você pode modificar. Essa estrutura promove a consistência, a personalização e a acessibilidade na Web.

Configuração do tema

A configuração do tema é feita com a chave de configuração chamada config.theme com a seguinte estrutura

interface ThemeConfigProps {
   isLight?: boolean; // Represents if light or dark theme
   tokens?: Tokens; // Paste tokens
   componentThemeOverrides?: Object; // Object containing styles of the component which is to be overridden.
}

Temas de componentes

Para componentes que recebem o tema como adereços, props.theme.tokens pode ser usado. Para obter mais informações sobre cada token, consulte a Twilio Paste

Tokens personalizados

Use tokens personalizados para passar seus próprios tokens personalizados para o tema usando o exemplo abaixo

  appconfig = {
    theme: {
      tokens: {
        custom: {
          myCustomToken: "#ccc"
        }
      }
    }
  }

ThemeProvider

Uma API Flex.setProviders() pode ser usada para carregar provedores no nível raiz uma vez e não precisa se preocupar com o agrupamento novamente, pois o contexto será definido corretamente. Agora, para usar Colar em plugins Flex, os desenvolvedores não precisarão finalizar Colar ThemeProvider em todos os seus componentes. Explore a API em nossos documentos da API Flex UI (IU do Flex).

Ao usar Colar, os desenvolvedores precisam passar o CustomizationProvider de Colar para o Flex usando a API Flex.setProviders, conforme abaixo. Ao fazer isso, envolveremos o Flex com o provedor aprovado e os desenvolvedores não precisam se preocupar em buscar o tema certo e passá‐lo.

import { CustomizationProvider } from "@twilio-paste/core/customization";
 
Flex.setProviders({
   PasteThemeProvider: CustomizationProvider
});
 
Flex.AgentDesktopView.Panel1.Content.add(
   <PasteButton key="A" variant="primary">
       Paste Button
   </PasteButton>
);
 
Flex.AgentDesktopView.Panel1.Content.add(
   <PasteButton key="B" variant="primary">
       Paste Button
   </PasteButton>
);

Flex.setProviders() também permite que os desenvolvedores passem seu próprio provedor personalizado, que precisa ser definido no nível raiz. Eles podem fazer isso conforme o exemplo abaixo:

Flex.setProviders({
   CustomProvider: (RootComponent) => (props) => {
       return (
           <Context.Provider value={{ test: "123" }}>
               <RootComponent {...props} />
           </Context.Provider>
       );
   }
});
 
Flex.AgentDesktopView.Panel1.Content.add(
   <Context.Consumer>
       {(value) => {
           <div>{value.foo}</div> // Will print 123
       }}
   </Context.Consumer>
);

O exemplo abaixo mostra como usar um provedor personalizado para modelar componentes de IU de material

Flex.setProviders({
      CustomProvider: (RootComponent) => (props) => {
          return (
            <StylesProvider generateClassName={createGenerateClassName({
              productionPrefix: 'pluginXYZ',
            })}>
                  <RootComponent {...props} />
              </StylesProvider>
          );
      }
});

Flex.AgentDesktopView.Panel1.Content.add(<StyledSampleComponent  key="no1"  />);

Usar a Twilio Paste

Nem todos os componentes criados precisam começar do zero. As bibliotecas de componentes React existentes podem ajudá‐lo a usar componentes que já foram criados com compatibilidade de navegador, tamanhos de tela responsivos e acessibilidade em mente. Internamente, flex-ui utiliza o Twilio Paste para muitos componentes. Você também pode usar o Paste para criar componentes que começam com um estilo semelhante ao layout existente do Flex.

Embora o Paste já seja uma dependência da flex-ui, recomendamos incluí‐lo como uma dependência explícita no seu projeto de plugin package.json. Você adicionaria isso em suas dependencies:

// package.json

"dependencies": {
    ...
    "@twilio-paste/core": "^10.20.0",
},

Adicionar/substituir/remover componentes

O Flex UI (IU do Flex) é uma biblioteca de componentes programáveis ou dinâmicos que expõem uma propriedade Content e permitem adicionar, substituir e remover qualquer componente e seus secundários. Cada secundário imediato de um componente tem uma chave (necessária para os métodos add ereplace) e um conjunto de propriedades que serão herdadas pelos secundários. Para ver a lista completa de componentes, encontre uma key do componente ou explore os adereços de componentes, vá para documentos da API Flex UI (IU do Flex).

Propriedade de conteúdo e métodos de adição/substituição/remoção

Abaixo, você pode encontrar uma lista de componentes de IU e detalhes, que podem ser substituídos de forma programática. Isso pode ser feito usando os métodos add, replace e remove com opções. Observação: todos os componentes devem ter uma chave declarada.

Sintaxe para métodos de adição/substituição

Flex.Component.Content.add(<MyComponent key="demo-component"/>, {options});
Flex.Component.Content.replace(<MyComponent key="demo-component"/>, {options});

Abaixo está um exemplo de adição de um componente chamado AnotherMuteButton ao componente MainHeader, alinhado à extremidade (aqui à esquerda) e colocado como o primeiro componente na frente dos componentes nativos MuteButton e UserControls:

Flex.MainHeader.Content.add(<AnotherMuteButton key="mute"/>, {
  sortOrder: -1, 
  align: “end”
});

Sintaxe para método de remoção

O método de remoção permite remover secundários imediatos de um componente programável pela chave deles.

Flex.Component.Content.remove(key, {options});

Abaixo está um exemplo de remoção do componente AnotherMuteButton do componente MainHeader. Este componente é removido pela chave que definimos acima, "mute".

Flex.MainHeader.Content.remove("mute");

Opções para métodos de adicionar/substituir/remover

se (Expressão)

Usado nos métodos add e replace para adicionar condições em que o componente é adicionado ou substituído. Exemplo:

Flex.MainHeader.Content.add(<AnotherMuteButton key="mute"/>, {
  if : props => props.task.source.taskChannelUniqueName === "custom1" 
});

sortOrder (number)

Usado no método add para especificar a ordem em que o novo componente é colocado em relação a outros secundários do componente principal. Os componentes secundários nativos têm prioridade. O contador de ordem de classificação começa com 0. Para sempre colocar um novo componente no início ou no fim da ordem, utilize números grandes como -100 ou 100, dependendo da direção. Exemplo:

Flex.MainHeader.Content.add(<AnotherMuteButton key="mute"/>, {
  sortOrder: -1
});

align ('start' | 'end')

Usado no método add para alinhar novos componentes tanto para cima/baixo quanto para a direita/esquerda, dependendo da direção do componente principal. Os valores possíveis são:

start - alinha o novo componente à esquerda ou na parte superior
end - alinha o novo componente à direita ou à parte inferior

Exemplo:

Flex.MainHeader.Content.add(<AnotherMuteButton key="mute"/>, {
  align: “end”
});

Ações de IU e Flex Events

O Flex UI (IU do Flex) está constantemente emitindo dados de eventos que descrevem como o usuário está interagindo com o Flex UI (IU do Flex). À medida que você escreve Plugins, a Estrutura de ações permite que você aproveite esses eventos e defina sua própria lógica para descrever como deseja que o Flex UI (IU do Flex), os dados do CRM ou quaisquer outros dados sejam alterados. Você pode registrar eventos antes ou depois de uma ação ser ativada ou até mesmo substituir o comportamento de uma Ação.

Registrar e chamar uma Ação

Actions.registerAction(name: string, action: ActionFunction, payloadUpdate?: PayloadUpdateFunction)

Registra uma ação nomeada e fornece o código que deve ser executado ao chamá‐la. O método payloadUpdate é opcional e usado para acionar um retorno de chamada para modificar o payload dado à chamada de ação.

Actions.invokeAction(name: string)

Chama uma ação nomeada. Retorna uma Promessa.

Actions.addListener(name: string, action: ActionFunction)

Implementa uma função personalizada a ser acionada antes ou depois de uma Ação específica.

Adicionar e remover ouvintes de eventos

Você pode adicionar e remover ouvintes de eventos.

Eventos suportados:

before[eventName] (por exemplo "beforeAcceptTask")
Chamado quando uma ação nomeada é acionada, mas antes de o corpo de ação ser executado. Você pode cancelar a ação fornecida com o corpo do evento.

after[eventName]
Chamado depois que a ação parou de ser executada.

Observe que o evento afterLogout não é suportado. Depois que o trabalhador tiver se desconectado, ele retornará à tela de login do Flex.

Substituir uma ação

Actions.replaceAction(name: string, action: ReplacedActionFunction)

Substitui a implementação padrão de uma ação nomeada e fornece uma implementação alternativa. A ação substituída será chamada com os mesmos parâmetros da implementação original para que você possa adicionar mais lógica e, em seguida, chamar a ação original em sua função de substituição.

Notificações no app e no navegador

O Flex UI (IU do Flex) fornece uma API do lado do cliente para gerenciar notificações no Flex UI (IU do Flex).

O que é uma notificação no Flex?

Uma notificação é um alerta que informa ao usuário qual alteração de estado ou erro ocorreu em um componente ou página quando não é mais possível visualizar esse componente ou página

Os usuários podem ser notificados no Flex usando uma barra de notificações, notificações do navegador ou ambas.

Quais são os recursos de estrutura de notificação?

Registrar notificações personalizadas, incluindo notificações do navegador
Personalizar notificações padrão
Desativar notificações de IU padrão
Substituir notificações padrão por definição de canal de tarefa
Personalizar como as notificações de IU padrão são exibidas
Registrar suas notificações de IU personalizadas e especificar como processá-las

Barra de notificações

A barra de notificações é uma maneira in-app de alertar o usuário. A barra de notificações tem uma variedade de opções, como ícone, ações e tempo limite.

Notificações do navegador

O Flex usa a API de notificação de navegador padrão como base para a implementação de notificações do navegador. As notificações de navegador podem ser ativadas no dashboard de administração do Flex UI (IU do Flex).

As notificações do navegador serão exibidas se o Flex for minimizado.

Observação: devido a restrições de segurança em navegadores, as Notificações de navegador não são suportadas quando o Flex é fornecido como iframe em uma página da Web entre domínios. Isso inclui as integrações do Salesforce e do Zendesk.

Solicitar permissões

Para começar a mostrar notificações do navegador, o usuário precisa primeiro conceder permissões. Por padrão, o Flex solicitará permissões ao usuário se elas não forem concedidas ou bloqueadas.

Se você quiser adicionar lógica personalizada sobre a solicitação de permissões, como solicitá‐la com base em alguma ação do usuário na interface do usuário, poderá enviar Notification.requestPermission() a partir do seu código personalizado.

Processador de notificações do navegador

Para exibir uma notificação do navegador, use a chave options com uma tag do browser. Os documentos da API do Flex contêm uma lista completa de propriedades disponíveis. Se nenhuma chave do browser for passada para options, o Flex não mostrará nenhuma notificação do navegador.

Ações da barra de notificações

Um componente auxiliar NotificationBar.Action que pode ser usado para fornecer ação clicável para definição de notificação.

interface NotificationBarActionProps {
    label: React.ReactText; // Can be simple text string or a template string
    onClick: NotificationBarActionCallback;
    icon?: string;
}

A referência completa para o Notification Manager e uma lista de notificações padrão estão disponíveis nos documentos da API Flex.

Gerenciamento de estado

O Flex UI (IU do Flex) 2.0 inclui o Redux Toolkit e algumas novas APIs para gerenciar seu estado interno. Essas ferramentas fornecem algumas barreiras para o gerenciamento do estado, ajudando você a configurar o código padrão com mais facilidade e com padrões melhores.

Recomendamos o uso de um único armazenamento Redux, ou permita que o Flex UI (IU do Flex) crie seu próprio armazenamento ou passe um armazenamento personalizado usando a API Manager.create()

useFlexSelector

Um wrapper ao redor do método useSelector do Redux. Ele expõe a mesma API, mas adiciona algumas validações do Flex para garantir que o estado interno do Flex seja utilizável. Esse seletor é específico para trabalhar com o próprio estado Flex. Fora do estado de acesso do Flex, recomendamos o uso do padrão useSelector.

const MyComponent = (props) => {
   const viewState = useFlexSelector(state => state.view);
   return (
       {viewState.isSideNavOpen &&
           <div>My Custom Code</div>
       }
   )
}

O seletor assume o estado de exibição atual do componente personalizado. O seletor garante que o estado que está sendo selecionado é seguro para leitura e pode ser usado no aplicativo sem efeitos colaterais. Isso não poderia ser garantido com o useSelector.

useFlexDispatch

Um wrapper ao redor do método useDispatch do Redux. Ele impede que os despachos causem efeitos colaterais ao estado do Flex, garantindo que suas alterações funcionem conforme esperado. Use este gancho para interagir com o estado do Flex. Você pode usar o método nativo useDispatch fora do estado do Flex.

const MyComponent = (props) => {
   const viewState = useFlexSelector(state => state.view);
   const dispatch = useFlexDispatch();
   return (
       {viewState.isSideNavOpen &&
               <button onClick={() => dispatch({type: 'close_side_bar'})}>My Custom Code</button>
       }
   )
}

Saiba mais sobre como usar o Redux em nossos guias para desenvolvedores

Definições do canal de tarefas

Flex é um contact center multicanal. Oferecemos suporte a vários canais prontos para uso e estamos constantemente adicionando mais canais. A partir da versão 1.0, oferecemos suporte aos seguintes canais nativos:

Voice
SMS com suporte a MMS
WebChat com anexos de mídia
WhatsApp

Com a API Task Channel Definition, você também pode adicionar canais personalizados e substituir o comportamento dos existentes.

API Task Channel Definition

Todos os canais de tarefas que o Flex UI (IU do Flex) manipula são definidos e registrados na API Canais de tarefas. O Flex registra as definições padrão do Canal de tarefas, mas os usuários e plugins podem registrar suas próprias definições. Quando os componentes baseados em tarefas são renderizados, a primeira definição de canal correspondente para uma determinada tarefa será usada. Se houver mais de uma correspondência de definição de canal para uma tarefa, a definição registrada mais recentemente será usada. Isso permite que você registre uma definição de canal mais específica para substituir o comportamento de uma geral.

Em uma definição de canal de tarefa, você pode especificar:

retorno de chamada para determinar quais tarefas são aplicáveis
strings (modelos) para usar em diferentes componentes do Flex com base no status da tarefa
cores a serem usadas na lista de tarefas com base no status da tarefa
ícones a serem mostrados na lista de tarefas, guias e telas com base no status da tarefa
componentes personalizados a serem adicionados a componentes baseados em tarefas se o canal for aplicável
componentes personalizados a serem substituídos em componentes baseados em tarefas se o canal for aplicável

Saiba mais sobre como trabalhar com Definições de canais de tarefas nos guias do desenvolvedor.

insightsClient

O insightsClient fornece acesso ao Twilio Sync SDK. Para contas do Flex, isso dá acesso aos dados de trabalhadores e tarefas por meio do uso de duas classes:

Classe LiveQuery: para consultar dados Flex e receber atualizações enviadas sempre que registros novos (ou atualizados) corresponderem à expressão fornecida
Classe InstantQuery: para obter um instantâneo estático dos dados do Flex

Ambas as classes precisam de dois argumentos:

Nome do índice: conjunto de dados para o qual a consulta é executada. Os nomes de índice atualmente suportados para o Flex são: tr-task, tr-worker, tr-reservation, tr-queue.
Consulta: esta é a consulta usada para filtrar os dados do índice. A sintaxe da consulta está documentada aqui. A consulta pode ser uma string vazia: nesse caso, todo o conjunto de dados é retornado (por exemplo, todos os trabalhadores).

Exemplo de LiveQuery

Neste exemplo, o insightsClient é usado para consultar os trabalhadores com o activity_name definido como Available e assinar alterações. Isso significa que cada vez que um trabalhador altera o status para Available, um evento itemUpdated é disparado. Se um trabalhador alterar o status de Available para qualquer outro status, o evento itemRemoved será disparado.

Flex.Manager.insightsClient
  .liveQuery('tr-worker', 'data.activity_name == "Available"')
  .then(function (args) {
    console.log(
      'Subscribed to live data updates for worker in "Available" activity'
    );
    args.on('itemRemoved', function (args) {
      console.log('Worker ' + args.key + ' is no longer "Available"');
    });
    args.on('itemUpdated', function (args) {
      console.log('Worker ' + args.key + ' is now "Available"');
    });
  })
  .catch(function (err) {
    console.log('Error when subscribing to live updates', err);
  });

Exemplo do InstantQuery

Neste exemplo, o insightsClient é usado para consultar os trabalhadores com habilidades específicas dentro dos attributes. Isso retorna uma matriz de trabalhadores que pode ser usada para fornecer dados estáticos.

manager.insightsClient.instantQuery('tr-worker').then((q) => {
  q.on('searchResult', (items) => {
    // Do something with the results
  });
  q.search('data.attributes.languages contains "english"');
});

Precisa de ajuda?

Às vezes, todos nós precisamos; a programação é difícil. Receba ajuda agora da nossa equipe de suporte, ou confie na sabedoria da multidão navegando pelo Stack Overflow Collective da Twilio ou buscando a tag Twilio no Stack Overflow.

Precisa de ajuda?

Obrigado pelo seu feedback!

Obrigado pelo seu feedback!