A captura automática do Fullstory vê cliques. Seu negócio precisa ver pedidos, planos e clientes. Veja como usar trackEvent, setIdentity e setProperties do jeito certo.
Índice do artigo
- O que é o Fullstory?
- Como instalar: snippet ou SDK npm
- trackEvent: eventos com propriedades
- Tipagem de propriedades: o detalhe que muda relatórios
- setIdentity e setProperties: perfis de usuário
- Métodos assíncronos e a ordem das chamadas
- Consentimento: capturar só depois do sim
- Os erros que mais aparecem
- Perguntas frequentes sobre Fullstory
O Fullstory grava tudo. É exatamente por isso que, sem instrumentação, ele vira uma biblioteca gigante sem catálogo. A Browser API é o catálogo.
O que é o Fullstory?
O Fullstory é uma plataforma de digital experience analytics: captura a sessão do usuário (session replay), gera métricas de interação, sinais de frustração e permite buscar sessões por comportamento. A documentação técnica cobre Browser API, Server API, Mobile API e integrações.
Em uma frase: o Fullstory transforma cada sessão em dado pesquisável; a Browser API decide o que é pesquisável para o seu negócio.
Como instalar: snippet ou SDK npm
O caminho clássico é o snippet de captura no head, com variáveis como o ID da organização e o namespace da API. Para aplicações modernas, o SDK oficial @fullstory/browser expõe uma função init, que deve ser chamada o mais cedo possível no carregamento da aplicação, e um export FullStory equivalente ao objeto global FS.
Duas opções úteis do SDK: devMode, para desativar a captura em ambiente de desenvolvimento, e recordOnlyThisIFrame, para quando a aplicação roda dentro de um iframe e deve ser tratada como sessão própria.
trackEvent: eventos com propriedades
Eventos personalizados são criados com FS(‘trackEvent’, { name, properties }).
FS('trackEvent', {
name: 'Produto Adicionado',
properties: {
product_id: 'SKU-123',
categoria: 'Tênis',
preco: 299.90,
quantidade: 1
}
});
Com isso você busca, por exemplo, todas as sessões em que alguém adicionou um produto de determinada categoria ao carrinho e depois abandonou.
Boa prática: o nome e as propriedades do evento no Fullstory seguem o mesmo dicionário do GA4.
Tipagem de propriedades: o detalhe que muda relatórios
Na versão 1 da API era preciso colocar sufixos de tipo nas propriedades (como _str ou _int). Na versão 2 isso não é mais necessário, e os sufixos devem ser omitidos. Os tipos são inferidos a partir do valor, e todo número é inferido como real (decimal).
Quando isso importa? Quando quantidade, dias de trial ou número de usuários precisam ser inteiros. Nesses casos, declare um schema para sobrescrever a inferência:
FS('trackEvent', {
name: 'Assinatura Criada',
properties: { plano: 'Pro', usuarios: 10, dias_trial: 14 },
schema: { properties: { usuarios: 'int', dias_trial: 'int' } }
});
setIdentity e setProperties: perfis de usuário
Para ligar a sessão ao cliente, use FS(‘setIdentity’, { uid, properties }). Para atualizar o perfil depois, FS(‘setProperties’, { type: ‘user’, properties }). O resultado é um perfil rico que permite buscar sessões por atributos como plano, segmento ou tempo de casa.
O uid deve ser o ID interno do seu banco, estável e sem dado pessoal. Propriedades como nome e e-mail só devem entrar com base legal definida pelo jurídico.
Métodos assíncronos e a ordem das chamadas
Todo método da API tem uma variante assíncrona (setIdentityAsync, trackEventAsync, getSessionAsync), que retorna um objeto tipo Promise. Isso resolve um problema clássico: disparar um evento de login antes de a identidade estar aplicada. Com await, a ordem fica garantida.
await FS('setIdentityAsync', { uid: user.id });
await FS('trackEventAsync', { name: 'Login' });
Um cuidado: não bloqueie a renderização da aplicação esperando o Fullstory. Se a ferramenta estiver bloqueada por um ad blocker, a Promise pode nunca resolver. Renderize primeiro, enriqueça depois.
Consentimento: capturar só depois do sim
Elementos configurados nas regras de privacidade como “capturar com consentimento” só são gravados depois de FS(‘setIdentity’, { consent: true }). Com consent: false, a captura desses elementos para.
Na prática, conecte essa chamada ao evento do seu banner de cookies ou CMP, de preferência via Google Tag Manager, para que a regra seja versionada e auditável. A definição de quais elementos exigem consentimento é uma decisão conjunta entre produto, jurídico e DPO.
Os erros que mais aparecem
- Sufixos de tipo da API v1 ainda presentes em implementações v2.
- Quantidades e contagens tratadas como decimal por falta de schema.
- trackEvent de login disparado antes de setIdentity.
- Aplicação esperando a Promise do Fullstory para renderizar.
- uid baseado em e-mail, que muda e fragmenta o histórico do cliente.
Perguntas frequentes sobre Fullstory
O que é o Fullstory?
Uma plataforma de digital experience analytics com session replay, métricas de interação e busca de sessões por comportamento.
Como criar um evento personalizado no Fullstory?
Com FS(‘trackEvent’, { name, properties }), enviando o nome do evento e as propriedades de negócio.
Preciso usar _str e _int nas propriedades?
Não na API v2. Os tipos são inferidos; use schema apenas para sobrescrever, por exemplo, números que devem ser inteiros.
Como identificar usuários no Fullstory?
Com FS(‘setIdentity’, { uid, properties }), usando o ID interno e estável do usuário.
O Fullstory tem SDK npm?
Sim, o @fullstory/browser, com função init e suporte a todas as chamadas da API v2.
Como o Fullstory lida com consentimento?
Elementos marcados para captura com consentimento só são gravados após FS(‘setIdentity’, { consent: true }).