7 min de leitura

Integração com Ghost

Adicione o Zenovay a qualquer publicação Ghost (Ghost(Pro), Ghost CMS auto-hospedado ou Ghost Cloud) em dois minutos. O Code Injection do Ghost está totalmente disponível em todos os planos, então esta integração funciona para criadores no plano gratuito e publicadores auto-hospedados.

O Code Injection está disponível em todos os planos Ghost, incluindo o Ghost CMS auto-hospedado. Não é necessário fazer upgrade.

Início rápido

Etapa	Onde	O que fazer
1	Painel do Zenovay	Copie seu snippet de rastreamento
2	Admin do Ghost → Settings → Code injection → Site Header	Cole-o
3	Salve	Clique em Save
4	Painel do Zenovay	Visitantes em tempo real aparecem em ~30 segundos

Método 1: Injeção no Site Header (Recomendado)

O painel Code Injection do Ghost escreve HTML bruto no <head> de todas as páginas renderizadas pelo seu tema. Isso inclui a página inicial, posts, páginas, tags, autores e o fluxo de assinatura.

Passo a passo

Faça login no seu painel de administração do Ghost (geralmente https://seu-site.com/ghost/).
Na barra lateral esquerda, clique em Settings (ícone de engrenagem).
Role para baixo até Site → Code injection.
Na caixa Site Header, cole:

<script defer data-tracking-code="YOUR_TRACKING_CODE" src="https://api.zenovay.com/z.js"></script>

Clique em Save.

Verifique

Abra seu site Ghost em modo anônimo e visualize o código-fonte — você deve ver <script defer data-tracking-code=...> entre <head> e </head>. Sua visita deve aparecer na visualização em tempo real do Zenovay em ~30 segundos.

Método 2: Injeção por post / por página

Para rastrear apenas um post ou página específico (por ex., um anúncio de newsletter pago), abra o post no editor e use o Code Injection no nível do post:

Abra um post ou página no editor.
Clique no ícone de engrenagem (configurações) no canto superior direito.
Role para baixo e expanda Code injection.
Cole o snippet em Post Header.
Atualize o post.

O Code Injection por post é acrescentado depois do Code Injection global. Não cole o rastreador em ambos — você vai contar duas vezes.

Rastreamento de eventos personalizados

Após o carregamento do rastreador, você pode chamar window.zenovay() de qualquer template de tema Ghost, bloco de Code Injection ou embed HTML em Markdown de post.

Os formulários de inscrição do Ghost emitem um evento personalizado members:signup no sucesso. Adicione isso em Site Header → Code injection (após a linha do rastreador):

<script>
  document.addEventListener('DOMContentLoaded', () => {
    document.addEventListener('submit', (e) => {
      const form = e.target;
      if (form?.matches('[data-members-form]')) {
        if (window.zenovay) {
          window.zenovay('track', 'signup', {
            form_type: form.dataset.membersForm || 'signup',
            page: window.location.pathname,
          });
        }
      }
    }, true);
  });
</script>

O Ghost renderiza botões de assinar / acionar portal com atributos data-portal. Escute os cliques:

<script>
  document.addEventListener('DOMContentLoaded', () => {
    document.addEventListener('click', (e) => {
      const target = e.target.closest('[data-portal]');
      if (target && window.zenovay) {
        window.zenovay('track', 'portal_opened', {
          action: target.dataset.portal,
          page: window.location.pathname,
        });
      }
    }, true);
  });
</script>

Identifique membros

O Ghost expõe o membro atual através de /members/api/member/. Busque e identifique em todas as páginas:

<script>
  fetch('/members/api/member/', { credentials: 'include' })
    .then(r => r.ok ? r.json() : null)
    .then(member => {
      if (member && window.zenovay) {
        window.zenovay('identify', {
          userId: member.uuid,
          email: member.email,
          name: member.name,
          plan: member.subscriptions?.[0]?.plan?.nickname,
        });
      }
    })
    .catch(() => {});
</script>

Rastreamento de conversões pagas

Para atribuição de receita em assinaturas pagas, use a integração de webhook do Stripe do Ghost e envie eventos do Stripe para o Zenovay via nossa API de rastreamento server-side. O rastreamento client-side perde eventos de assinatura que são concluídos depois que o usuário fechou a aba (o Ghost envia o recibo de forma assíncrona).

Exemplo rápido server-side (Node.js no seu próprio receptor de webhook):

// Forward Stripe checkout.session.completed → Zenovay
app.post('/webhooks/stripe', async (req, res) => {
  const event = req.body;
  if (event.type === 'checkout.session.completed') {
    const session = event.data.object;
    await fetch('https://api.zenovay.com/v1/track', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${process.env.ZENOVAY_API_KEY}`,
      },
      body: JSON.stringify({
        event: 'purchase',
        userId: session.customer_email,
        properties: {
          transaction_id: session.id,
          revenue: session.amount_total / 100,
          currency: session.currency,
        },
      }),
    });
  }
  res.json({ received: true });
});

Trabalhando com temas Ghost personalizados

Se você mantém um tema Ghost personalizado (por ex., derivado de Casper, Source ou Edition), o Code Injection é renderizado via o helper {{ghost_head}}. Enquanto o default.hbs do seu tema incluir:

{{!-- in default.hbs --}}
{{ghost_head}}

…então o Zenovay carrega corretamente. A maioria dos temas Ghost de terceiros inclui isso por padrão. Se o seu não incluir, adicione dentro de <head> antes de </head>.

Requisitos do plano

Edição do Ghost	Code Injection	Temas personalizados	Rastreamento server-side
Ghost(Pro) Starter	✅	❌ (somente Casper)	✅ via webhooks
Ghost(Pro) Creator	✅	✅	✅
Ghost(Pro) Team / Business	✅	✅	✅
Ghost CMS auto-hospedado	✅	✅	✅

Problemas comuns

{{ghost_head}} ausente em temas personalizados. Este é o problema número 1 em sites com tema personalizado. Se o rastreador não aparece no código-fonte da página, verifique se seu default.hbs inclui o helper. Sem ele, o Code Injection não tem onde renderizar.

Posts AMP. Se você habilitou AMP via a integração Ghost AMP, o Code Injection não se aplica às URLs /seu-post/amp/ (AMP remove scripts arbitrários). Desative o AMP ou aceite que o tráfego AMP não será rastreado. A partir do Ghost 5.x, o AMP está sendo desenfatizado; recomendamos desativá-lo.

Emails de newsletter. O Code Injection se aplica apenas ao seu site, não aos emails de newsletter enviados. As aberturas de email são rastreadas pelo próprio Ghost; você pode sincronizar esses dados via a API Admin do Ghost para o Zenovay se desejar, mas isso está fora do escopo da integração básica.

Posts exclusivos para membros. O rastreador dispara em cada renderização de página, incluindo visualizações prévias com paywall. Se você quiser rastrear visualizações de post apenas depois que o paywall for desbloqueado, condicione seu evento personalizado à resposta de /members/api/member/ acima.

Ghost auto-hospedado no Docker / Kubernetes. Nenhuma configuração adicional necessária — o Code Injection fica no banco de dados do Ghost, não no sistema de arquivos. Basta colar o snippet pela interface do admin como de costume.

Solução de problemas

Sintoma	Causa provável	Correção
Sem dados	Rastreador não está no código-fonte da página	Verifique se `{{ghost_head}}` está presente no `default.hbs`
Sem dados em alguns posts	Code Injection por post substituindo	Mova o snippet para o Header global
Visualizações de página duplicadas	Snippet no Site Header e no Code Injection por post	Escolha um escopo
Sem dados nas URLs `/amp/`	AMP remove scripts	Desative AMP ou aceite a lacuna
Membros nunca identificados	`/members/api/member/` retorna 404	Você está em uma versão mais antiga do Ghost (< 4.x) — faça upgrade

Privacidade e conformidade

Para rastreamento sem cookies, adicione data-cookieless="true":

<script defer
        data-tracking-code="YOUR_TRACKING_CODE"
        data-cookieless="true"
        src="https://api.zenovay.com/z.js"></script>

O próprio analytics de membros do Ghost usa cookies first-party de qualquer forma, então adicionar o Zenovay em modo sem cookies é um padrão comum: você mantém os dados de membros baseados em email do Ghost, além de obter análises de visitantes sem cookies no restante do site.

Consulte Conformidade de Privacidade para o panorama completo.

Recursos relacionados

Precisa de ajuda? Entre em contato pelo [email protected] ou visite nossa Central de Ajuda.