Pular para o conteúdo
PTEN

Eventos (Relay)

Reaja no navegador quando os seus clientes interagem com o orçamento.

A ponte de mensagens

O iframe do Cord Elements foi projetado para nunca isolar o seu site do que acontece dentro dele. Usando uma ponte bidirecional via window.postMessage, o Cord faz o “relay” (retransmissão) dos eventos do cartão diretamente para o seu ambiente window pai.

Isso é muito útil para disparar pixels de analytics (como o Meta Pixel ou o Google Analytics), lançar animações de confete quando uma proposta é aprovada ou redirecionar o usuário para uma página de “Obrigado” depois de um pagamento bem-sucedido.

Ouvir eventos

Você pode ouvir os eventos de forma nativa associando um addEventListener ao nó do DOM do elemento incorporado:

const container = document.querySelector('[data-cord-token]');

container.addEventListener('cord:approved', (event) => {
  console.log('The quote was approved!');
  console.log('Approved by:', event.detail.signed_by);
});

Dicionário de eventos

Todos os eventos têm o prefixo cord: para evitar colisões de nomes com outras bibliotecas. O detail de cada evento sempre inclui token (o token público do orçamento) e folio (p. ex. "COT-0148"), além dos campos próprios listados abaixo.

Ciclo de vida do componente

  • cord:ready: Disparado no momento exato em que o SDK termina de renderizar o conteúdo, calcular a altura final e as fontes terminam de carregar.
  • cord:resize: Emitido continuamente cada vez que a altura do iframe muda (útil apenas se você escrever o seu próprio contêiner e não usar o embed.js).
  • cord:viewed: Disparado junto com cord:ready, assim que o orçamento termina de ser renderizado dentro do iframe — é o sinal de que o conteúdo já está visível para a sua página anfitriã. O registro oficial no banco de dados de que o cliente visualizou o orçamento passa por um mecanismo interno independente, que exige que a aba esteja realmente visível (para não contar como “visualização” o próprio vendedor pré-visualizando o link dele); não presuma que os dois acontecem no mesmo instante.

Interação comercial

  • cord:approved: Emitido no instante em que o usuário aprova os termos da proposta comercial. Devolve no detail dados úteis como o hash de validação e quem assinou (signed_by).
  • cord:signed: Disparado no MESMO instante que cord:approved, com o mesmo detail (signed_by, hash) — no Cord, aprovar e assinar são uma única ação do cliente, não duas etapas separadas no tempo. Ouça o que for semanticamente mais claro para você; não espere que um “chegue depois” do outro.
  • cord:pay: Emitido quando o usuário clica no botão para iniciar o fluxo de pagamento online (cartão, transferência bancária ou os demais métodos que a empresa tiver habilitados). O detail traz a url absoluta da página de pagamento. O Cord já a abre em uma janela própria (o pagamento nunca roda dentro do iframe): não navegue a sua página para essa URL, use-a apenas para o seu analytics.
  • cord:rejected: Disparado se o cliente marcar explicitamente a proposta como recusada. O detail inclui o comentario que ele tiver deixado.
  • cord:message: Ativado cada vez que o cliente deixa um comentário geral ou uma contraproposta no chat do orçamento.
  • cord:item_comment: Disparado quando o usuário deixa um comentário específico sobre um item (linha de produto) do orçamento, com o item_id correspondente no detail.

Status

  • cord:updated: O orçamento mudou enquanto estava aberto (o vendedor editou itens, valores ou condições). O orçamento já se redesenhou sozinho; use o evento para atualizar o que a sua página mostra ao redor.
  • cord:status_changed: O status mudou (sent, viewed, approved, rejected, paid, expired…). O detail traz o novo status (e saldo na fatura).
  • cord:paid: Somente em <cord-invoice>: a fatura foi quitada. O detail traz folio, moneda e saldo.

cord:ready também traz status, moneda e total, para que a sua página desenhe o próprio resumo sem outra chamada.

Modo somente leitura

Se a sua organização não tiver domínios permitidos em Configurações › Gerador de orçamentos incorporável, ou se a página anfitriã não estiver nessa lista, o orçamento é exibido em somente leitura: não oferece aprovar, assinar, pagar nem escrever, e o botão leva ao link público do orçamento em uma nova aba. Nesse modo os eventos chegam sem detail: uma página que não está na sua lista não recebe quem assinou, valores nem a URL de pagamento.

Barra de depuração

Com debug ativo, o Elements desenha no seu site um painel com os eventos do iframe, cada requisição à API com o seu request_id e os avisos de configuração (por exemplo, valores de appearance que o Cord descartou).

<cord-quote token="a1b2c3d4e5f60718" debug></cord-quote>
<!-- ou com embed.js -->
<div data-cord-token="a1b2c3d4e5f60718" data-cord-debug></div>

No React, <CordProvider debug>. O painel só aparece com uma chave pk_test_; com pk_live_ ele se limita a um aviso no console. Sem chave (Web Component ou embed.js), só aparece em localhost ou se a URL tiver ?cord_debug=1, para que um atributo esquecido nunca o mostre aos seus clientes.