Widgets de ação (action button)

Novidade da v7

O tipo action foi introduzido na v7 (PliQ). Ver Novidades.

Um widget de ação é uma pesquisa que não tem botão flutuante do plugin — quem abre é o seu próprio site, a partir de um clique num elemento seu (um botão, um link) ou por código. É o contraponto dos widgets flutuantes.

Use quando quiser amarrar a pesquisa a uma ação real do usuário:

• Ao finalizar um atendimento
• Ao clicar em "Avaliar" / "Dar feedback"
• Ao concluir um pedido ou uma etapa importante

---

Como disparar

1. Pelo HTML (atributo)

Marque qualquer elemento do seu site com data-pliq-widget e o plugin abre o modal da pesquisa no clique — inclusive em elementos criados depois do load (SPAs):

<button data-pliq-widget="pesquisa-atendimento">
  Avaliar atendimento
</button>

2. Por código (JavaScript)

window.PliQ.openWidget('pesquisa-atendimento');

O valor ("pesquisa-atendimento") é a referência do widget, resolvida nesta ordem: name → url_survey (ver o JSON do widget).

Pré-requisitos

• Uma sessão ativa (PliQ.initialize já chamado) — sem sessão, o clique só gera um aviso no log.
• O widget precisa estar ativo. O openWidget também abre widgets flutuantes, mas o alvo natural é o tipo action.

---

Properties e tags

Ao abrir, você pode enviar properties (campos customizados) e tags que são gravadas junto com a resposta — perfeito para rastrear a origem.

No atributo

<button
  data-pliq-widget="pesquisa-atendimento"
  data-pliq-properties="status_atendimento:resolvido;tipo_atendimento:chat"
  data-pliq-tags="campanha-verao;time-suporte">
  Avaliar
</button>

Por código

window.PliQ.openWidget('pesquisa-atendimento', {
  properties: { status_atendimento: 'resolvido', tipo_atendimento: 'chat' },
  tags: ['campanha-verao', 'time-suporte'],
});

Atributo / opção	Formato	Descrição
data-pliq-properties / properties	chave:valor;chave2:valor2	Campos customizados na resposta
data-pliq-tags / tags	tag1;tag2	Tags na resposta

Tags globais

Além das tags por widget/chamada, dá pra registrar tags globais que entram em todas as respostas: PliQ.setTags(['campanha-verao']) (ou _pliqStt.tags). Ver Métodos → setTags.

A property precisa existir na pesquisa

Cada chave de property precisa estar cadastrada na pesquisa como property de texto (mesmo internal_name). Uma chave desconhecida faz a pesquisa abrir em uma página de erro. As tags não exigem cadastro prévio.

Os caracteres : e ; são separadores

Como : e ; separam os pares, eles são removidos do valor. Uma URL https://site.com/x chega como https//site.com/x (o caminho é preservado).

---

Placeholders dinâmicos

Nos valores você pode usar placeholders {...} que o plugin substitui na hora do clique/chamada:

<button data-pliq-widget="pesquisa-atendimento"
        data-pliq-properties="origem:{current_url};plano:{plano};email:{email}">
  Avaliar
</button>

Um {nome} é resolvido nesta ordem: built-in → variável global → campo do contato.

1. Built-ins (sempre disponíveis)

Placeholder	Vira
{current_url}	URL completa da página (window.location.href)
{current_path}	Caminho + query (/pagina?x=1)
{referrer}	Página de origem (document.referrer)
{title}	Título da página (document.title)

2. Variáveis globais (você define)

Qualquer variável que você registrar vira um placeholder {nome}. Dois jeitos, que se combinam:

// estático, junto do snippet de instalação:
p._pliqStt = { token: 'SEU_TOKEN', globals: { plano: 'premium', tenant: 'acme' } };

// dinâmico, em runtime — a qualquer momento antes do widget abrir:
window.PliQ.setGlobals({ plano: 'premium' });
window.PliQ.setGlobal('carrinho_id', '8821');

Depois, no widget: data-pliq-properties="plano:{plano};tenant:{tenant}". Ver Métodos → setGlobals.

3. Campos do contato logado

Os campos passados no initialize viram placeholders automaticamente: {name}, {email}, {phone}, {code_contact_client}, {enterprise}.

Ordem e nomes reservados

Os quatro built-ins são reservados. Uma variável global de mesmo nome que um campo do contato vence o contato. Um placeholder desconhecido fica literal (não some). Os nomes precisam casar com [A-Za-z0-9_].

Assim você registra de onde a pessoa veio, o plano, o e-mail — sem escrever nenhuma lógica de montagem de URL.

---

Retorno do openWidget

PliQ.openWidget(ref, options?) retorna boolean:

• true — modal aberto (ou já estava aberto)
• false — sem sessão ativa, referência não encontrada, ou widget inativo (o motivo é logado no console com log: true)

Ver a assinatura completa em Métodos → openWidget e o formato do widget em Visão geral → o JSON do widget.