Instalação do Widget JavaScript

Guia passo a passo para instalar o widget JavaScript FreshNews.ai no seu site para desempenho ideal de E-E-A-T e SEO.

🔧 Developer Shortcut (Cursor / Copilot Ready)

Using Cursor or AI-assisted development? Generate the integration automatically.

Por que este método?

Este é o método de integração principal e recomendado porque fornece valor ideal de E-E-A-T (Experiência, Expertise, Autoridade, Confiança).

Otimizado para E-E-A-T: O conteúdo é renderizado diretamente no seu domínio (não em um iframe), permitindo que o Google o indexe e atribua corretamente
Benefícios SEO: Os mecanismos de busca veem o conteúdo como parte do seu site, melhorando a autoridade do seu domínio
Controle Total: Personalize estilo, marca e renderização para corresponder perfeitamente ao seu site
Melhor Desempenho: Sem sobrecarga de iframe, carregamentos de página mais rápidos

Passos de Instalação

Configuração DNS (A Base)

Para produção, você deve usar um domínio personalizado CNAME (por exemplo, signals.seudominio.com). O locatário é automaticamente resolvido a partir do domínio, então você não precisa fornecer um slug de locatário.

CNAME é necessário para produção. Substitua 'signals.seudominio.com' pelo seu domínio personalizado CNAME real.

signals.seudominio.com → CNAME → ingest.freshnews.ai

Instalação do Script (Head e Desempenho)

Adicione o script de incorporação e CSS opcional à seção <head> da sua página. Use 'defer' para execução mais rápida.

<!-- Performance: Pre-connect to API and R2 for faster loading -->
<link rel="preconnect" href="https://signals.your-domain.com" />
<link rel="preconnect" href="https://pub-xxxxx.r2.dev" />

<!-- Optional: Basic styling -->
<link rel="stylesheet" href="https://signals.your-domain.com/embed/insights.css" />

<!-- Required: Embed script - Use 'defer' in <head> for fastest execution -->
<script src="https://signals.your-domain.com/embed/insights.js" defer></script>

Importante: Substitua 'signals.seudominio.com' pelo seu domínio personalizado CNAME real. O widget resolverá automaticamente o locatário a partir do seu domínio.

Posicionamento do Widget (Modos Lista vs. Artigo)

Coloque o contêiner do widget onde deseja que o conteúdo apareça. Escolha entre lista de percepções, lista de sinais ou modo de artigo único.

Modo A: Lista de Sinais

Exibe uma lista de sinais diários. Perfeito para uma página de sinais ou seção de sinais na página inicial.

<div
  data-freshnews-widget="insights"
  data-mode="signals-list"
  data-api-base="https://signals.your-domain.com"
  data-link-base="https://your-site.com/signals"
  data-embed-nav="true"
  data-kind="daily"
  data-limit="20"
  data-language="en"
></div>

Note: For CNAME custom domains, no data-tenant attribute is needed. Only add data-tenant="your-slug" for localhost or testing with signals.freshnews.ai.

Lidar com Atualizações/Carregamentos Diretos (Usuários Next.js e Frameworks)

Ao usar data-embed-nav="true", o widget atualiza a URL via history.pushState. Ao atualizar ou carregar diretamente, seu aplicativo precisa de uma rota que corresponda ao padrão de URL do artigo.

Esta etapa só é necessária se você estiver usando um framework como Next.js, Remix ou similar. Se estiver usando HTML simples, você pode pular esta etapa.

Quando um usuário clica em um artigo, o widget atualiza a URL para /[lang]/signals/[slug] (ou /[lang]/insights/[slug]). Se o usuário atualizar ou carregar diretamente essa URL, seu aplicativo deve ter um manipulador de rota para isso. A rota deve renderizar a mesma página que sua página de lista - o widget lerá o slug da URL e exibirá o artigo no lado do cliente.

Exemplo Next.js App Router:

// app/[lang]/signals/[slug]/page.tsx
// Renderize a mesma página que app/[lang]/signals/page.tsx
// O widget lê o slug de window.location.pathname

export default function SignalArticlePage({ params }) {
  // Renderize o mesmo componente que sua página de lista
  return <SignalsPageContent locale={params.locale} />
}

Recursos de Alto Desempenho

Stale-While-Revalidate

Carregamentos instantâneos com frescor. O widget exibe conteúdo em cache imediatamente (atraso de 0ms), depois busca dados frescos em segundo plano para atualizações suaves.

Telas de Esqueleto

Sem mudança de layout. O widget exibe telas de esqueleto animadas durante o carregamento em vez do texto 'Carregando...' para melhor desempenho percebido.

Busca Paralela

Marca e artigos são buscados em paralelo (não bloqueante), então os artigos são renderizados imediatamente mesmo se a API de marca for lenta.

Como Novos Artigos Aparecem

Renderização Instantânea (atraso de 0ms)

O widget usa cache de LocalStorage para mostrar conteúdo imediatamente. Na primeira visita, os artigos carregam instantaneamente do cache (atraso percebido de 0ms), depois dados frescos são buscados em segundo plano.

Atualização Suave

A busca em segundo plano garante frescor sem perturbar a experiência do usuário. Novos artigos aparecem perfeitamente conforme são publicados, sem mudanças de layout ou indicadores de carregamento.

Vantagem de Descoberta

💡 Por que isso importa para IA: Mecanismos generativos (GEO) e mecanismos de resposta (AEO) procuram estruturas HTML rápidas e autoritárias. A abordagem "Stale-While-Revalidate" do nosso widget garante que rastreadores de IA encontrem seu conteúdo imediatamente, enquanto seus usuários obtêm uma experiência de carregamento instantânea.

Recursos Adicionais

Para documentação detalhada da API, consulte a documentação EMBED-API.md. Para solução de problemas, entre em contato conosco em contact@freshnews.ai.

← Installation