Marketing automation with built‑in analytics in Herald

#fastapi #react #postgres #celery

Problem

Indie developers and small teams ship code faster than they write about it. Herald automates the generation of blog posts and social copy from repo events, but the real value lies in knowing which pieces actually reach an audience. Without visibility into read counts and engagement, a developer cannot optimize the content calendar or justify the time spent on marketing automation.

Solution Overview

Herald adds Umami analytics directly into the published posts. The integration captures page views, referrer data, and user interaction without sending data to third‑party services. By embedding a lightweight script with the correct website ID, every time a reader visits a Dev.to or Medium article that Herald published, the event is recorded and surfaced in the Herald dashboard. This gives developers a single source of truth for marketing automation metrics.

How It Works

Herald is built on FastAPI with SQLAlchemy for persistence, Celery for background tasks, Redis for task queues, and a React front‑end styled with Tailwind CSS. The analytics pipeline is split between the back‑end and the front‑end.

1. Back‑end: Exposing the Umami Endpoint

The FastAPI application exposes a small endpoint that the front‑end calls when a page loads. The endpoint simply records the event in a PostgreSQL table.

# app/api/analytics.py
from fastapi import APIRouter, Depends
from sqlalchemy.orm import Session
from app.db import get_db
from app.models import PageView

router = APIRouter(prefix="/analytics")

@router.post("/view")
def record_view(page: str, user_agent: str, db: Session = Depends(get_db)):
    view = PageView(page=page, user_agent=user_agent)
    db.add(view)
    db.commit()
    return {"status": "ok"}

The PageView model stores the page URL, user agent, timestamp, and a reference to the content ID. No sensitive data is logged.

2. Front‑end: Injecting the Umami Script

In the React component that renders a published article, we inject the Umami script once per page load. The script tag is added only if the UMAMI_WEBSITE_ID environment variable is set.

// components/Article.tsx
import { useEffect } from "react";

export default function Article({ content }) {
  useEffect(() => {
    const script = document.createElement("script");
    script.async = true;
    script.src = "https://umami.example.com/umami.js";
    script.setAttribute("data-website-id", process.env.NEXT_PUBLIC_UMAMI_ID ?? "");
    document.body.appendChild(script);
  }, []);

  return <article>{content.body}</article>;
}

The script automatically reports page views to the Umami backend, which in turn forwards the data to the Herald analytics endpoint.

3. Celery Task: Aggregating Metrics

Once a view is recorded, a Celery worker processes the event to update aggregate metrics used in the content calendar. The task runs every minute, batching view records to reduce database load.

# app/tasks/analytics.py
from celery import shared_task
from app.db import get_session
from app.models import PageView, Content

@shared_task
def aggregate_views():
    session = get_session()
    views = session.query(PageView).filter(PageView.processed == False).all()
    for v in views:
        content = session.query(Content).filter_by(url=v.page).first()
        if content:
            content.views += 1
        v.processed = True
    session.commit()

The aggregated view count is displayed in the Herald UI next to each content item, allowing developers to see which AI‑generated posts performed best.

Using the Feature

Enable Umami – Set UMAMI_WEBSITE_ID in the Heroku / Fly.io config.
Deploy – The front‑end automatically injects the script; no changes to the Dev.to or Medium publishing logic are required.
View Dashboard – In the Herald UI, open the content calendar. Each row now shows a Views column populated from the Umami data.
Iterate – Use the view counts to adjust the content calendar and prioritize topics that resonate with readers.

The integration is optional; developers who prefer not to use Umami simply omit the environment variable, and the feature falls back to the default analytics path.

Benefits

No third‑party tracking – All data stays within the Herald stack, respecting privacy.
Real‑time insights – The Celery aggregation runs every minute, giving near‑real‑time metrics.
Seamless developer experience – The integration requires only a single environment variable and a few lines of code.
Data‑driven marketing automation – By tying view counts to AI‑generated content, developers can refine their content calendar and improve engagement.

Conclusion

Herald’s built‑in Umami analytics solves a core pain point for indie developers: knowing whether the automated marketing pipeline is delivering value. By combining FastAPI, Celery, and React, the feature provides a lightweight, privacy‑preserving way to measure engagement, enabling data‑driven decisions in marketing automation without hiring a marketer.

DEV Community