JavaScript Widget Installation

Step-by-step guide to installing the FreshNews.ai JavaScript widget on your website for optimal SEO, AEO, and GEO Optimization.

🔧 Developer Shortcut (Cursor / Copilot Ready)

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

Why this works

Rendering content directly on the domain (via JS or CNAME) is the only way to build domain authority in 2026. This approach ensures AI discovery engines and search crawlers attribute expertise to your brand.

E-E-A-T Optimized: Content is rendered directly on your domain (not in an iframe), allowing Google to properly index and attribute it
SEO, AEO & GEO Benefits: Search engines and AI agents see the content as part of your site, improving your domain authority
Full Control: Customize styling, branding, and rendering to match your site perfectly
Better Performance: No iframe overhead, faster page loads

Installation Steps

DNS Setup (The Foundation)

For production, you must use a CNAME custom domain (e.g., signals.yourdomain.com). The tenant is automatically resolved from the domain, so you don't need to provide a tenant slug.

CNAME is required for production. Replace 'signals.yourdomain.com' with your actual CNAME custom domain.

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

Performance Header Tags

Add the embed script and optional CSS to your page's <head> section. Include `<link rel="preconnect">` tags for faster loading and use `defer` for fastest execution.

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

Important: Replace 'signals.yourdomain.com' with your actual CNAME custom domain. The widget will auto-resolve the tenant from your domain. CNAME is required for production.

Widget Placement (List vs. Article modes)

Place the widget container where you want the content to appear. Choose between insights list, signals list, or single article mode.

Mode A: Signals List

Display a list of daily signals. Perfect for a signals page or homepage signals section.

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

Handle Refresh/Direct Loads (Next.js & Framework Users)

When using data-embed-nav="true", the widget updates the URL via history.pushState. On refresh or direct load, your app needs a route that matches the article URL pattern.

This step is only needed if you're using a framework like Next.js, Remix, or similar. If you're using plain HTML, you can skip this step.

When a user clicks an article, the widget updates the URL to /[lang]/signals/[slug] (or /[lang]/insights/[slug]). If the user refreshes or directly loads that URL, your app must have a route handler for it. The route should render the same page as your list page - the widget will read the slug from the URL and display the article client-side.

Next.js App Router example:

// app/[lang]/signals/[slug]/page.tsx
// Render the same page as app/[lang]/signals/page.tsx
// The widget reads the slug from window.location.pathname

export default function SignalArticlePage({ params }) {
  // Render the same component as your list page
  return <SignalsPageContent locale={params.locale} />
}

High-Performance Features

Stale-While-Revalidate

Instant loads with freshness. The widget shows cached content immediately (0ms delay), then fetches fresh data in the background for soft-updates.

Skeleton Screens

No layout shift. The widget shows animated skeleton screens during loading instead of 'Loading...' text for better perceived performance.

Parallel Fetching

Branding and articles are fetched in parallel (non-blocking), so articles render immediately even if branding API is slow.

How New Articles Appear

Instant Render (0ms delay)

The widget uses LocalStorage caching to show content immediately. On first visit, articles load instantly from cache (0ms perceived delay), then fresh data is fetched in the background.

Soft Refresh

Background fetching ensures freshness without jarring the user experience. New articles appear seamlessly as they're published, with no layout shifts or loading spinners.

Discovery Advantage

💡 Why this matters for AI: Generative engines (GEO) and Answer engines (AEO) look for fast, authoritative HTML structures. Our widget's "Stale-While-Revalidate" approach ensures AI crawlers find your content immediately, while your users get an instant-load experience.

Additional Resources

For troubleshooting, contact us at contact@freshnews.ai.

← Installation