Activación como un número que puedes mover, no como una sensación que tienes

La mayoría de las integraciones de analytics dispersa las llamadas de evento por el lado cliente, espera lo mejor y produce un dashboard del que nadie se fía. El tracking de activación en producción se parece a los cuatro archivos de abajo: un registry de eventos tipado por Zod, un helper track() llamado desde Server Actions, una agregación nocturna escribiendo en tenant_metrics, y la query del funnel que el dashboard lee. Servidor de punta a punta; la fuente de verdad en Postgres; el vendor (PostHog o Plausible) aguas abajo.

1. El registry de eventos tipado

Cada evento tiene un nombre, un schema de properties y un owner. Añadir un evento es una PR que actualiza este archivo; si no se hace, el helper queda no tipable en el call site.

// src/lib/analytics/events.ts
import { z } from 'zod'

export const EVENT_NAMES = [
  'user.signed_up',
  'user.verified_email',
  'tenant.created',
  'project.created',
  'invite.sent',
  'invite.accepted',
  'subscription.started',
  'first_value.reached',
] as const

export type EventName = (typeof EVENT_NAMES)[number]

export const EVENT_PROPS = {
  'user.signed_up': z.object({
    source: z.enum(['organic', 'paid', 'referral', 'direct']).optional(),
    plan: z.string().optional(),
  }),
  'user.verified_email': z.object({
    verification_age_minutes: z.number().int().nonnegative(),
  }),
  'tenant.created': z.object({
    plan: z.string(),
    seat_count: z.number().int().positive().default(1),
  }),
  'project.created': z.object({
    project_id: z.string().uuid(),
    template: z.string().optional(),
  }),
  'invite.sent': z.object({
    invite_id: z.string().uuid(),
    role: z.enum(['owner', 'admin', 'member', 'billing']),
  }),
  'invite.accepted': z.object({
    invite_id: z.string().uuid(),
    accept_age_hours: z.number().int().nonnegative(),
  }),
  'subscription.started': z.object({
    stripe_subscription_id: z.string(),
    plan: z.string(),
  }),
  'first_value.reached': z.object({
    flow: z.string(),
    elapsed_minutes: z.number().int().nonnegative(),
  }),
} as const satisfies Record<EventName, z.ZodTypeAny>

export type EventProps<T extends EventName> = z.infer<(typeof EVENT_PROPS)[T]>

2. El helper track()

Una función tipada llamada desde cualquier Server Action. Valida las properties en runtime, escribe en Postgres y reenvía al vendor de analytics cuando está configurado. Si la validación falla lanza; preferimos encontrar el bug antes que escribir un evento malformado.

// src/lib/analytics/track.ts
import { adminClient } from '@/lib/supabase/admin'
import { EVENT_PROPS, type EventName, type EventProps } from './events'

interface TrackInput<T extends EventName> {
  tenantId: string
  userId: string | null
  event: T
  properties: EventProps<T>
}

export async function track<T extends EventName>(
  input: TrackInput<T>,
): Promise<void> {
  const schema = EVENT_PROPS[input.event]
  const validated = schema.parse(input.properties)

  // Escribe primero en nuestra tabla events; esa es la fuente de verdad.
  const { error } = await adminClient.from('events').insert({
    tenant_id: input.tenantId,
    user_id: input.userId,
    event_name: input.event,
    properties: validated,
  })
  if (error) throw error

  // Reenvía a PostHog si está configurado. Un fallo aquí queda loggeado pero
  // nunca lanza; el dashboard del cliente depende de la escritura en Postgres,
  // no de llegar al tercero.
  if (process.env.POSTHOG_API_KEY) {
    void fetch(`${process.env.POSTHOG_HOST}/i/v0/e/`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        api_key: process.env.POSTHOG_API_KEY,
        event: input.event,
        properties: {
          ...validated,
          $groups: { tenant: input.tenantId },
          distinct_id: input.userId ?? input.tenantId,
        },
      }),
    }).catch(() => {})
  }
}

3. Una Server Action que dispara un evento

El evento se dispara DESPUÉS de que la escritura en la base de datos tiene éxito. Las dos operaciones van dentro de un try / catch para que un estado parcial no deje el evento escrito sin la fila correspondiente, o viceversa.

// app/[lang]/(app)/projects/actions.ts
'use server'

import { z } from 'zod'
import { revalidatePath } from 'next/cache'
import { createServerClient } from '@/lib/supabase/server'
import { getServerSession, getActiveTenantId } from '@/lib/auth/server'
import { track } from '@/lib/analytics/track'

const Input = z.object({
  name: z.string().min(1).max(200),
  template: z.string().optional(),
})

export async function createProject(
  raw: unknown,
): Promise<{ ok: true; projectId: string } | { ok: false; error: string }> {
  const session = await getServerSession()
  if (!session) return { ok: false, error: 'unauthorised' }

  const tenantId = await getActiveTenantId()
  if (!tenantId) return { ok: false, error: 'no active tenant' }

  const parsed = Input.safeParse(raw)
  if (!parsed.success) return { ok: false, error: 'invalid input' }

  const supabase = await createServerClient()
  const { data: project, error } = await supabase
    .from('projects')
    .insert({
      tenant_id: tenantId,
      name: parsed.data.name,
      template: parsed.data.template ?? null,
      created_by: session.userId,
    })
    .select('id')
    .single()

  if (error) return { ok: false, error: error.message }

  // Dispara el evento de activación solo después de que la escritura DB ha ido bien.
  await track({
    tenantId,
    userId: session.userId,
    event: 'project.created',
    properties: {
      project_id: project.id,
      template: parsed.data.template,
    },
  })

  revalidatePath('/projects')
  return { ok: true, projectId: project.id }
}

4. La agregación nocturna y la query del funnel

La agregación calcula las métricas por tenant cada noche y las escribe en tenant_metrics. El dashboard lee de tenant_metrics (barato, indexado) en vez de reproducir el stream de eventos en cada carga de página.

-- supabase/migrations/0020_tenant_metrics.sql
create table tenant_metrics (
  tenant_id uuid primary key references tenants(id) on delete cascade,
  activation_score numeric(5,2) not null default 0,
  funnel_step_pct jsonb not null default '{}',
  time_to_activation_hours integer,
  drop_off_step text,
  events_total integer not null default 0,
  computed_at timestamptz not null default now()
);

create or replace function refresh_tenant_metrics()
returns void
language plpgsql
security definer
as $$
declare
  rec record;
begin
  for rec in
    select t.id as tenant_id, t.created_at as tenant_created_at
    from tenants t
  loop
    with funnel as (
      select
        event_name,
        min(created_at) as first_seen
      from events
      where tenant_id = rec.tenant_id
      group by event_name
    ),
    steps as (
      select
        (select first_seen from funnel where event_name = 'user.signed_up') as signed_up,
        (select first_seen from funnel where event_name = 'project.created') as project_created,
        (select first_seen from funnel where event_name = 'invite.accepted') as invite_accepted,
        (select first_seen from funnel where event_name = 'first_value.reached') as first_value
    )
    insert into tenant_metrics (tenant_id, activation_score, funnel_step_pct, time_to_activation_hours, drop_off_step, events_total, computed_at)
    select
      rec.tenant_id,
      case
        when first_value is not null then 100
        when invite_accepted is not null then 75
        when project_created is not null then 50
        when signed_up is not null then 25
        else 0
      end as activation_score,
      jsonb_build_object(
        'signed_up', signed_up is not null,
        'project_created', project_created is not null,
        'invite_accepted', invite_accepted is not null,
        'first_value', first_value is not null
      ) as funnel_step_pct,
      case
        when first_value is not null
          then extract(epoch from (first_value - signed_up))::int / 3600
      end as time_to_activation_hours,
      case
        when first_value is null and invite_accepted is not null then 'first_value'
        when invite_accepted is null and project_created is not null then 'invite_accepted'
        when project_created is null and signed_up is not null then 'project_created'
      end as drop_off_step,
      (select count(*) from events where tenant_id = rec.tenant_id),
      now()
    from steps
    on conflict (tenant_id) do update set
      activation_score = excluded.activation_score,
      funnel_step_pct = excluded.funnel_step_pct,
      time_to_activation_hours = excluded.time_to_activation_hours,
      drop_off_step = excluded.drop_off_step,
      events_total = excluded.events_total,
      computed_at = now();
  end loop;
end;
$$;

// app/admin/funnel/page.tsx
import { Suspense } from 'react'
import { adminClient } from '@/lib/supabase/admin'

async function FunnelData() {
  const { data: rows } = await adminClient
    .from('tenant_metrics')
    .select('tenant_id, activation_score, drop_off_step, time_to_activation_hours, computed_at')
    .order('computed_at', { ascending: false })
    .limit(200)

  if (!rows) return <p>No metrics yet.</p>

  return (
    <table className="ds-table">
      <thead>
        <tr>
          <th>Tenant</th>
          <th>Score</th>
          <th>Drop-off</th>
          <th>Time to activation</th>
          <th>Computed</th>
        </tr>
      </thead>
      <tbody>
        {rows.map((r) => (
          <tr key={r.tenant_id}>
            <td>{r.tenant_id}</td>
            <td>{r.activation_score}</td>
            <td>{r.drop_off_step ?? '—'}</td>
            <td>{r.time_to_activation_hours ?? '—'}</td>
            <td>{new Date(r.computed_at).toLocaleString()}</td>
          </tr>
        ))}
      </tbody>
    </table>
  )
}

export default function FunnelPage() {
  return (
    <Suspense fallback={<p>Loading funnel…</p>}>
      <FunnelData />
    </Suspense>
  )
}

5. Cómo encaja todo esto

Las Server Actions disparan eventos según tienen éxito. La tabla events es la fuente de verdad; row-level security acota las lecturas al tenant de manera automática. La agregación nocturna deriva métricas por tenant que el dashboard lee en una sola query. PostHog o Plausible reciben una copia para exploración; la tabla interna es contra la que el equipo optimiza.

La activación deja de ser una sensación del founder y pasa a ser un número en un dashboard que el equipo abre el lunes por la mañana. El funnel se convierte en el artefacto contra el que cada decisión de producto argumenta; los próximos diez experimentos tienen un objetivo en vez de una corazonada.