Visão geral das opções de programabilidade do Flex UI (IU do Flex)
Manager
O Flex Manager (Gerente do Flex) é o ponto de acesso para controlar sua instância do Flex e todos os produtos Twilio subjacentes usados para comunicações e tarefas de atribuição. Isso significa que, em seu projeto Flex, você pode acessar o TaskRouter ou o cliente de Chat diretamente pelo Flex Manager (Gerente do Flex).
Além do próprio Flex, o Manager (Gerente do Flex) também dá acesso aos SDKs Conversations, Sync, Voice e TaskRouter.
Como obter a instância do Manager
Você pode acessar o Manager da seguinte maneira:
No método init do seu plugin
init(flex, manager) {
// use manager here
}
Em seu aplicativo, chamando o método 'getInstance'
Flex.Manager.getInstance()
ou chamando o mé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));
Você pode fazer o check-out do projeto de amostra sobre como inicializar o Flex.
Para obter a descrição detalhada do Manager, visite nossos documentos da API Flex UI (IU do Flex)
Configuração
A configuração do Flex UI (IU do Flex) permite que você controle a maneira como o app geral é 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 configuração - por meio da API defaultProps
Usando componentProps
no Objeto de configuração
Exemplo
var appConfig = {
componentProps: {
CRMContainer: {
uriCallback: (task) => task
? `https://www.bing.com/search?q=${task.attributes.name}`
: "http://bing.com"
}
},
};
API React defaultProps
Você também pode configurar propriedades padrão para componentes em um plugin usando a API React defaultprops
de forma programá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 descrição completa do Objeto de configuraçãoObjeto de configuração e Adereços de componente.
Substituição das strings de idioma
Você pode substituir qualquer string editando o objeto strings
na instância do Flex Manager (Gerente do Flex):
flex.Manager.getInstance().strings.TaskLineCallAssigned = "I am a content string!";
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 expressões do estilo Mustache nas strings de conteúdo, ou seja, incorporar espaç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, conteúdo dinâmico adicional está disponí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, conteúdo dinâmico adicional está disponível: por exemplo, acessando Propriedades ou atributos da tarefa.
Aqui está 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}}";
Funções auxiliares
As funções auxiliares fornecem uma maneira de personalizar o texto com informações dinâmicas. Aqui está um exemplo do uso de uma função auxiliar para habilitar atualizações dinâmicas:
manager.strings.TaskExtraInfo = "Time since last update: {{helper.durationSinceUpdate}}";
Você pode encontrar todas as funções auxiliares disponíveis nos documentos da API Flex UI (IU do Flex).
Temas do Flex UI (IU do Flex)
A interface de criação de temas do Flex UI (IU do Flex) mapeia de perto para o sistema de design Twilio Paste. Essa estrutura é baseada no conceito de tokens de projeto, um conjunto de variáveis que você pode modificar. Essa estrutura promove a consistência, a personalização e a acessibilidade na Web.
Configuração do tema
A configuração do tema é feita com a chave de configuraçã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 adereços, props.theme.tokens
pode ser usado. Para obter mais informações sobre cada token, consulte a Twilio Paste
Tokens personalizados
Use tokens personalizados para passar seus pró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 nível raiz uma vez e não precisa se preocupar com o agrupamento novamente, pois o contexto será definido corretamente. Agora, para usar Colar em plugins Flex, os desenvolvedores não precisarã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 não precisam se preocupar em buscar o tema certo e passá‐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()
também permite que os desenvolvedores passem seu próprio provedor personalizado, que precisa ser definido no ní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 começar do zero. As bibliotecas de componentes React existentes podem ajudá‐lo a usar componentes que já foram criados com compatibilidade de navegador, tamanhos de tela responsivos e acessibilidade em mente. Internamente, flex-ui
utiliza o Twilio Paste para muitos componentes. Você também pode usar o Paste para criar componentes que começam com um estilo semelhante ao layout existente do Flex.
Embora o Paste já seja uma dependência da flex-ui
, recomendamos incluí‐lo como uma dependência explícita no seu projeto de plugin package.json
. Você adicionaria isso em suas dependencies
:
// package.json
"dependencies": {
...
"@twilio-paste/core": "^10.20.0",
},
Adicionar/substituir/remover componentes
O Flex UI (IU do Flex) é uma biblioteca de componentes programáveis ou dinâmicos que expõem uma propriedade Content
e permitem adicionar, substituir e remover qualquer componente e seus secundários. Cada secundário imediato de um componente tem uma chave (necessária para os métodos add
ereplace
) e um conjunto de propriedades que serão herdadas pelos secundários. Para ver a lista completa de componentes, encontre uma key
do componente ou explore os adereços de componentes, vá para documentos da API Flex UI (IU do Flex).
Propriedade de conteúdo e métodos de adição/substituição/remoção
Abaixo, você pode encontrar uma lista de componentes de IU e detalhes, que podem ser substituídos de forma programática. Isso pode ser feito usando os métodos add
, replace
e remove
com opções. Observação: todos os componentes devem ter uma chave declarada.
Sintaxe para métodos de adição/substituição
Flex.Component.Content.add(<MyComponent key="demo-component"/>, {options});
Flex.Component.Content.replace(<MyComponent key="demo-component"/>, {options});
Abaixo está um exemplo de adição de um componente chamado AnotherMuteButton ao componente MainHeader, alinhado à extremidade (aqui à 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 método de remoção
O método de remoção permite remover secundários imediatos de um componente programável pela chave deles.
Flex.Component.Content.remove(key, {options});
Abaixo está um exemplo de remoção do componente AnotherMuteButton do componente MainHeader. Este componente é removido pela chave que definimos acima, "mute".
Flex.MainHeader.Content.remove("mute");
Opções para métodos de adicionar/substituir/remover
se (Expressão)
Usado nos métodos add
e replace
para adicionar condições em que o componente é adicionado ou substituído. Exemplo:
Flex.MainHeader.Content.add(<AnotherMuteButton key="mute"/>, {
if : props => props.task.source.taskChannelUniqueName === "custom1"
});
sortOrder (number)
Usado no método add
para especificar a ordem em que o novo componente é colocado em relação a outros secundários do componente principal. Os componentes secundários nativos têm prioridade. O contador de ordem de classificação começa com 0. Para sempre colocar um novo componente no início ou no fim da ordem, utilize números grandes como -100 ou 100, dependendo da direção. Exemplo:
Flex.MainHeader.Content.add(<AnotherMuteButton key="mute"/>, {
sortOrder: -1
});
align ('start' | 'end')
Usado no método add
para alinhar novos componentes tanto para cima/baixo quanto para a direita/esquerda, dependendo da direção do componente principal. Os valores possíveis são:
- start - alinha o novo componente à esquerda ou na parte superior
- end - alinha o novo componente à direita ou à parte inferior
Exemplo:
Flex.MainHeader.Content.add(<AnotherMuteButton key="mute"/>, {
align: “end”
});
Ações de IU e Flex Events
O Flex UI (IU do Flex) está constantemente emitindo dados de eventos que descrevem como o usuário está interagindo com o Flex UI (IU do Flex). À medida que você escreve Plugins, a Estrutura de ações permite que você aproveite esses eventos e defina sua própria lógica para descrever como deseja que o Flex UI (IU do Flex), os dados do CRM ou quaisquer outros dados sejam alterados. Você pode registrar eventos antes ou depois de uma ação ser ativada ou até mesmo substituir o comportamento de uma Ação.
Registrar e chamar uma Ação
Actions.registerAction(name: string, action: ActionFunction, payloadUpdate?: PayloadUpdateFunction)
Registra uma ação nomeada e fornece o código que deve ser executado ao chamá‐la. O método payloadUpdate é opcional e usado para acionar um retorno de chamada para modificar o payload dado à chamada de ação.
Actions.invokeAction(name: string)
Chama uma ação nomeada. Retorna uma Promessa.
Actions.addListener(name: string, action: ActionFunction)
Implementa uma função personalizada a ser acionada antes ou depois de uma Ação específica.
Adicionar e remover ouvintes de eventos
Você pode adicionar e remover ouvintes de eventos.
Eventos suportados:
before[eventName] (por exemplo "beforeAcceptTask"
)
Chamado quando uma ação nomeada é acionada, mas antes de o corpo de ação ser executado. Você pode cancelar a ação fornecida com o corpo do evento.
after[eventName]
Chamado depois que a ação parou de ser executada.
Observe que o evento afterLogout
não é suportado. Depois que o trabalhador tiver se desconectado, ele retornará à tela de login do Flex.
Substituir uma ação
Actions.replaceAction(name: string, action: ReplacedActionFunction)
Substitui a implementação padrão de uma ação nomeada e fornece uma implementação alternativa. A ação substituída será chamada com os mesmos parâmetros da implementação original para que você possa adicionar mais lógica e, em seguida, chamar a ação original em sua função de substituição.
Notificações no app e no navegador
O Flex UI (IU do Flex) fornece uma API do lado do cliente para gerenciar notificações no Flex UI (IU do Flex).
O que é uma notificação no Flex?
Uma notificação é um alerta que informa ao usuário qual alteração de estado ou erro ocorreu em um componente ou página quando não é mais possível visualizar esse componente ou página
Os usuários podem ser notificados no Flex usando uma barra de notificações, notificações do navegador ou ambas.
Quais são os recursos de estrutura de notificação?
- Registrar notificações personalizadas, incluindo notificações do navegador
- Personalizar notificações padrão
- Desativar notificações de IU padrão
- Substituir notificações padrão por definição de canal de tarefa
- Personalizar como as notificações de IU padrão são exibidas
- Registrar suas notificações de IU personalizadas e especificar como processá-las
Barra de notificações
A barra de notificações é uma maneira in-app
de alertar o usuário. A barra de notificações tem uma variedade de opções, como ícone, ações e tempo limite.
Notificações do navegador
O Flex usa a API de notificação de navegador padrão como base para a implementação de notificações do navegador. As notificações de navegador podem ser ativadas no dashboard de administração do Flex UI (IU do Flex).
As notificações do navegador serão exibidas se o Flex for minimizado.
Observação: devido a restrições de segurança em navegadores, as Notificações de navegador não são suportadas quando o Flex é fornecido como iframe em uma página da Web entre domínios. Isso inclui as integrações do Salesforce e do Zendesk.
Solicitar permissões
Para começar a mostrar notificações do navegador, o usuário precisa primeiro conceder permissões. Por padrão, o Flex solicitará permissões ao usuário se elas não forem concedidas ou bloqueadas.
Se você quiser adicionar lógica personalizada sobre a solicitação de permissões, como solicitá‐la com base em alguma ação do usuário na interface do usuário, poderá enviar Notification.requestPermission()
a partir do seu código personalizado.
Processador de notificações do navegador
Para exibir uma notificação do navegador, use a chave options
com uma tag do browser
. Os documentos da API do Flex contêm uma lista completa de propriedades disponíveis. Se nenhuma chave do browser
for passada para options
, o Flex não mostrará nenhuma notificação do navegador.
Ações da barra de notificações
Um componente auxiliar NotificationBar.Action
que pode ser usado para fornecer ação clicável para definição de notificação.
interface NotificationBarActionProps {
label: React.ReactText; // Can be simple text string or a template string
onClick: NotificationBarActionCallback;
icon?: string;
}
A referência completa para o Notification Manager e uma lista de notificações padrão estão disponí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 você a configurar o código padrão com mais facilidade e com padrões melhores.
Recomendamos o uso de um único armazenamento Redux, ou permita que o Flex UI (IU do Flex) crie seu próprio armazenamento ou passe um armazenamento personalizado usando a API Manager.create()
useFlexSelector
Um wrapper ao redor do método useSelector
do Redux. Ele expõe a mesma API, mas adiciona algumas validações do Flex para garantir que o estado interno do Flex seja utilizável. Esse seletor é específico para trabalhar com o próprio estado Flex. Fora do estado de acesso do Flex, recomendamos o uso do padrã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 exibição atual do componente personalizado. O seletor garante que o estado que está sendo selecionado é seguro para leitura e pode ser usado no aplicativo sem efeitos colaterais. Isso não poderia ser garantido com o useSelector
.
useFlexDispatch
Um wrapper ao redor do método useDispatch
do Redux. Ele impede que os despachos causem efeitos colaterais ao estado do Flex, garantindo que suas alterações funcionem conforme esperado. Use este gancho para interagir com o estado do Flex. Você pode usar o mé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
Definições do canal de tarefas
Flex é um contact center multicanal. Oferecemos suporte a vários canais prontos para uso e estamos constantemente adicionando mais canais. A partir da versão 1.0, oferecemos suporte aos seguintes canais nativos:
- Voice
- SMS com suporte a MMS
- WebChat com anexos de mídia
Com a API Task Channel Definition, você també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 são definidos e registrados na API Canais de tarefas. O Flex registra as definições padrão do Canal de tarefas, mas os usuários e plugins podem registrar suas próprias definições. Quando os componentes baseados em tarefas são renderizados, a primeira definição de canal correspondente para uma determinada tarefa será usada. Se houver mais de uma correspondência de definição de canal para uma tarefa, a definição registrada mais recentemente será usada. Isso permite que você registre uma definição de canal mais específica para substituir o comportamento de uma geral.
Em uma definição de canal de tarefa, você pode especificar:
- retorno de chamada para determinar quais tarefas são aplicá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
- í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 aplicável
- componentes personalizados a serem substituídos em componentes baseados em tarefas se o canal for aplicável
Saiba mais sobre como trabalhar com Definições de canais de tarefas nos guias do desenvolvedor.
insightsClient
O insightsClient
fornece acesso ao Twilio Sync SDK. Para contas do Flex, isso dá acesso aos dados de trabalhadores e tarefas por meio do uso de duas classes:
- Classe LiveQuery: para consultar dados Flex e receber atualizações enviadas sempre que registros novos (ou atualizados) corresponderem à expressão fornecida
- Classe InstantQuery: para obter um instantâneo estático dos dados do Flex
Ambas as classes precisam de dois argumentos:
- Nome do índice: conjunto de dados para o qual a consulta é executada. Os nomes de índice atualmente suportados para o Flex são:
tr-task
,tr-worker
,tr-reservation
,tr-queue
. - Consulta: esta é a consulta usada para filtrar os dados do índice. A sintaxe da consulta está documentada aqui. A consulta pode ser uma string vazia: nesse caso, todo o conjunto de dados é retornado (por exemplo, todos os trabalhadores).
Exemplo de LiveQuery
Neste exemplo, o insightsClient é usado para consultar os trabalhadores com o activity_name
definido como Available
e assinar alterações. Isso significa que cada vez que um trabalhador altera o status para Available
, um evento itemUpdated
é disparado. Se um trabalhador alterar o status de Available
para qualquer outro status, o evento itemRemoved
será 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 é usado para consultar os trabalhadores com habilidades específicas dentro dos attributes
. Isso retorna uma matriz de trabalhadores que pode ser usada para fornecer dados está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.