Instalación del Widget JavaScript

Guía paso a paso para instalar el widget JavaScript de FreshNews.ai en su sitio web para un rendimiento óptimo de E-E-A-T y SEO.

🔧 Developer Shortcut (Cursor / Copilot Ready)

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

¿Por qué este método?

Este es el método de integración principal y recomendado porque proporciona un valor óptimo de E-E-A-T (Experiencia, Experiencia, Autoridad, Confianza).

Optimizado para E-E-A-T: El contenido se renderiza directamente en su dominio (no en un iframe), permitiendo que Google lo indexe y atribuya correctamente
Beneficios SEO: Los motores de búsqueda ven el contenido como parte de su sitio, mejorando la autoridad de su dominio
Control Total: Personalice el estilo, la marca y el renderizado para que coincida perfectamente con su sitio
Mejor Rendimiento: Sin sobrecarga de iframe, cargas de página más rápidas

Pasos de Instalación

Configuración DNS (La Base)

Para producción, debe usar un dominio personalizado CNAME (por ejemplo, signals.sudominio.com). El inquilino se resuelve automáticamente desde el dominio, por lo que no necesita proporcionar un slug de inquilino.

CNAME es requerido para producción. Reemplace 'signals.sudominio.com' con su dominio personalizado CNAME real.

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

Instalación del Script (Head y Rendimiento)

Agregue el script de inserción y CSS opcional a la sección <head> de su página. Use 'defer' para la ejecución más 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: Reemplace 'signals.sudominio.com' con su dominio personalizado CNAME real. El widget resolverá automáticamente el inquilino desde su dominio.

Colocación del Widget (Modos Lista vs. Artículo)

Coloque el contenedor del widget donde desea que aparezca el contenido. Elija entre lista de perspectivas, lista de señales o modo de artículo único.

Modo A: Lista de Señales

Muestra una lista de señales diarias. Perfecto para una página de señales o sección de señales en la página de inicio.

<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.

Manejar Actualizaciones/Cargas Directas (Usuarios de Next.js y Frameworks)

Cuando se usa data-embed-nav="true", el widget actualiza la URL mediante history.pushState. Al actualizar o cargar directamente, tu aplicación necesita una ruta que coincida con el patrón de URL del artículo.

Este paso solo es necesario si estás usando un framework como Next.js, Remix o similar. Si estás usando HTML plano, puedes omitir este paso.

Cuando un usuario hace clic en un artículo, el widget actualiza la URL a /[lang]/signals/[slug] (o /[lang]/insights/[slug]). Si el usuario actualiza o carga directamente esa URL, tu aplicación debe tener un manejador de ruta para ello. La ruta debe renderizar la misma página que tu página de lista - el widget leerá el slug de la URL y mostrará el artículo del lado del cliente.

Ejemplo de Next.js App Router:

// app/[lang]/signals/[slug]/page.tsx
// Renderiza la misma página que app/[lang]/signals/page.tsx
// El widget lee el slug de window.location.pathname

export default function SignalArticlePage({ params }) {
  // Renderiza el mismo componente que tu página de lista
  return <SignalsPageContent locale={params.locale} />
}

Características de Alto Rendimiento

Stale-While-Revalidate

Cargas instantáneas con frescura. El widget muestra contenido en caché inmediatamente (retraso de 0ms), luego obtiene datos frescos en segundo plano para actualizaciones suaves.

Pantallas de Esqueleto

Sin cambio de diseño. El widget muestra pantallas de esqueleto animadas durante la carga en lugar de texto 'Cargando...' para un mejor rendimiento percibido.

Obtención Paralela

La marca y los artículos se obtienen en paralelo (sin bloqueo), por lo que los artículos se renderizan inmediatamente incluso si la API de marca es lenta.

Cómo Aparecen los Nuevos Artículos

Renderizado Instantáneo (retraso de 0ms)

El widget usa almacenamiento en caché de LocalStorage para mostrar contenido inmediatamente. En la primera visita, los artículos se cargan instantáneamente desde la caché (retraso percibido de 0ms), luego se obtienen datos frescos en segundo plano.

Actualización Suave

La obtención en segundo plano asegura frescura sin alterar la experiencia del usuario. Los nuevos artículos aparecen sin problemas a medida que se publican, sin cambios de diseño o indicadores de carga.

Ventaja de Descubrimiento

💡 Por qué esto importa para la IA: Los motores generativos (GEO) y los motores de respuestas (AEO) buscan estructuras HTML rápidas y autorizadas. El enfoque "Stale-While-Revalidate" de nuestro widget asegura que los rastreadores de IA encuentren su contenido inmediatamente, mientras que sus usuarios obtienen una experiencia de carga instantánea.

Recursos Adicionales

Para documentación detallada de la API, consulte la documentación EMBED-API.md. Para solución de problemas, contáctenos en contact@freshnews.ai.

← Installation