Atribución de ingresos por palabra clave multi-señal

¿Qué hace Atribución de ingresos por palabra clave multi-señal?

Estás ejecutando un análisis de atribución de ingresos a nivel de palabra clave utilizando la exportación masiva de GSC y los datos de GA4, ambos en BigQuery. La salida es una tabla markdown ordenable con (consulta, página, intención, clics, sesiones atribuidas, conversiones atribuidas, ingresos atribuidos, confianza) más un breve resumen titulado.

Cuándo usarlo

Activa esta habilidad siempre que el usuario quiera saber qué consultas están generando valor de tráfico (sesiones, conversiones, ingresos) en lugar de solo clics. La metodología lleva la atribución un nivel más fino que la herramienta estándar ga4_gsc_query_revenue del MCP, ya que se une en tres señales (página + fecha + dispositivo) antes de distribuir las métricas de GA4, aplica ponderación por intención para que las consultas de marca y transaccionales obtengan más crédito que las informacionales, y renormaliza para que los totales coincidan exactamente con GA4.

Si el usuario solo quiere la cuota de clics o una respuesta de una línea como "qué palabras clave posiciona mi sitio", usa ahrefs-quick-lookup o la herramienta preconstruida ga4_gsc_query_revenue en su lugar.

Entradas requeridas

Pregunta por cualquiera de estas que falte. Usa los valores por defecto mostrados si el usuario no los especifica.

Parámetro	Por defecto	Notas
brand_terms	requerido	Array en minúsculas. Coincidencia por subcadena de nivel 1. Usa formas canónicas de la marca (ej. ['snippet digital', 'snippetdigital']).
brand_tokens	[]	Array en minúsculas. Tokens de prefijo raíz de nivel 2. Cada token coincide con el inicio de cualquier palabra, así que 'model' captura 'models', 'modelling', 'modeling'. Recomendado para cualquier marca de varias palabras para capturar variaciones de orden de palabras y raíces.
brand_min_token_matches	2	Cuántos tokens de brand_tokens deben aparecer en una consulta para que sea de marca. 2 es el valor por defecto correcto para marcas de 2 palabras.
brand_negative_terms	[]	Array en minúsculas. Guarda de falsos positivos de nivel 3. Cualquier consulta que contenga uno de estos NUNCA se considera de marca. Úsalo para marcas de una sola palabra ambiguas (ej. ['apple pie', 'apple cider'] para Apple).
gsc_dataset	requerido	El conjunto de datos que contiene searchdata_url_impression, ej. searchconsole.
ga4_dataset	requerido	El conjunto de datos de exportación de GA4, ej. analytics_123456789.
days	28	Días hacia atrás desde hoy menos 3 (GSC tiene un retraso de ~3 días).
min_clicks	5	Ignorar consultas con menos clics totales en la ventana.
value_per_conversion	0.0	Valor fijo opcional por lead si GA4 no tiene valor monetario. Establecer a ej. 499.0 para un valor de conversión fijo.
conversion_events	['form_submit', 'generate_lead', 'purchase']	Nombres de eventos de GA4 que se cuentan como conversiones.

Los pesos de intención y las expresiones regulares de intención también son configurables (ver bloque DECLARE en attribution.sql). Los valores por defecto están ajustados para sitios B2B / de generación de leads; el peso transaccional puede necesitar aumentarse a 2.5 para ecommerce.

Coincidencia de marca: cómo completarla

Al preguntar al usuario por los términos de marca, pregunta explícitamente por ambos niveles:

"¿Cuál es tu marca? Dame 1) las frases exactas que la gente escribe para ti (ej. 'snippet digital', 'snippetdigital'), y 2) las palabras únicas de tu marca para coincidir como raíces (ej. 'snippet', 'digital')."

Para la mayoría de las marcas de varias palabras, el nivel 2 debe contener las mismas palabras que el nivel 1 divididas en tokens individuales. Ejemplos:

Marca	brand_terms (nivel 1)	brand_tokens (nivel 2)	min
Coca-Cola	['coca cola', 'cocacola', 'coke']	['coca', 'cola']	2
Snippet Digital	['snippet digital', 'snippetdigital']	['snippet', 'digital']	2
UK Models	['uk models', 'ukmodels']	['uk', 'model']	2
Keyword Insights	['keyword insights', 'keywordinsights']	['keyword', 'insights']	2

Para marcas de una sola palabra (Apple, Notion, Stripe), el nivel 2 generalmente es innecesario. Usa el nivel 3 para excluir falsos positivos:

Marca	brand_terms (nivel 1)	brand_negative_terms (nivel 3)
Apple (la empresa)	['apple']	['apple pie', 'apple cider', 'apple fruit']
Stripe (pagos)	['stripe']	['pin stripe', 'stripe pattern']

Si el usuario informa que consultas obviamente relacionadas con la marca se clasifican como informacionales (ej. plurales o variaciones de orden de palabras que se escapan), la solución es casi siempre agregar tokens de nivel 2.

Procedimiento

1. Confirmar las entradas. Si faltan brand_terms, gsc_dataset o ga4_dataset, pregúntale al usuario. Confirma explícitamente cualquier valor inusual (ej. days > 90, min_clicks > 25).

2. Verificar que ambos conjuntos de datos existen. Antes de ejecutar la consulta completa, ejecuta dos pruebas económicas a través de la herramienta query del MCP de BigQuery:

   • SELECT MAX(data_date) FROM \{gsc_dataset}.searchdata_url_impression``
   • SELECT MAX(_TABLE_SUFFIX) FROM \{ga4_dataset}.events_*`` Si alguna falla, muestra el error exacto al usuario y detente. No continúes con la consulta principal.

3. Ejecutar la consulta de atribución. Usa la herramienta query del MCP de BigQuery con el SQL en attribution.sql, después de sustituir <<GSC_DATASET>> y <<GA4_DATASET>> con los nombres de los conjuntos de datos del usuario. Actualiza el bloque DECLARE para reflejar los brand_terms, days, min_clicks, value_per_conversion y conversion_events del usuario. Establece max_rows a 200 para capturar la cola larga.

4. Renderizar la salida. Formatea el resultado como una tabla markdown ordenada por ingresos atribuidos descendente. Columnas: consulta, página, intención, clics, sesiones_atribuidas, conversiones_atribuidas, ingresos_atribuidos (con símbolo de moneda), candidatos_en_página, confianza. Después de la tabla, escribe:

   • Un titular de 2-3 frases que resuma el total de clics, sesiones, conversiones, ingresos y la proporción de marca.
   • Los 3 principales impulsores de alta confianza (una línea cada uno).
   • Cualquier patrón que valga la pena señalar (ej. páginas de ALTA confianza con cero conversiones, divisiones de intención inusuales, variaciones de marca no detectadas por la regla de subcadena).

5. Opcionalmente, renderizar el artefacto visual. Si el usuario solicita un panel, una instantánea o una captura de pantalla, construye un widget HTML en línea usando la herramienta show_widget del MCP. El widget debe incluir: 4 tarjetas de métricas (clics, sesiones, conversiones, ingresos), un gráfico de barras horizontal de las 12 principales consultas por ingresos atribuidos codificado por colores según la intención, un gráfico de barras apiladas de la distribución de intención (clics vs sesiones vs ingresos) y una tabla ordenable y filtrable.

Problemas comunes y qué hacer

• Términos de marca no detectados por la regla de subcadena. "uk model" no contiene "uk models". Siempre revisa proactivamente la lista de marcas: incluye singular/plural, con y sin espacios, errores tipográficos comunes, títulos de trabajo internos. Si ves consultas informacionales en la página de inicio superando a las de marca en clics brutos, casi siempre es una variación de marca faltante.
• Los ingresos son cero en todas partes. Esto significa que GA4 no está poblado ecommerce.purchase_revenue o event_params.value. Para sitios de generación de leads esto es normal. O acepta las conversiones como métrica de éxito, o pasa value_per_conversion para que los ingresos se imputen como conversiones x valor.
• Todas las calificaciones de confianza son BAJAS porque todo está en la página de inicio. Este es un hallazgo legítimo, no un error. La página de inicio realmente tiene demasiadas consultas candidatas para atribuir limpiamente. Señálalo como un hallazgo estructural ("los enlaces internos y las páginas de aterrizaje temáticas dividirían esta atribución en partes deterministas") en lugar de intentar manipular la puntuación.
• La tasa de unión parece baja. GSC y GA4 normalizan las URLs de manera diferente (barras inclinadas finales, cadenas de consulta, fragmentos). El SQL elimina las barras inclinadas finales y las cadenas de consulta en ambos lados; si la tasa de unión sigue siendo inferior al 50%, verifica si hay discrepancias de protocolo (http vs https) o diferencias de nombre de host (www vs no-www).
• El filtro orgánico de GA4 excluye demasiado. El SQL filtra las sesiones donde cualquier evento informa medium=organic. Si la configuración de GA4 del usuario usa valores diferentes de fuente de tráfico (ej. Organic Search como agrupación de canal), edita la cláusula WHERE en el CTE ga4_sessions.
• El conjunto de datos de GSC está en un proyecto y el de GA4 en otro. Las consultas entre proyectos de BigQuery funcionan bien; solo califica completamente ambos marcadores de posición, ej. project-a.searchconsole, project-b.analytics_123456789. La cuenta de servicio MCP necesita acceso de lectura en ambos.

Ejemplo de formato de salida

## [dominio] atribución de ingresos por palabra clave, últimos 28 días

**Ventana:** 2026-04-01 a 2026-04-28
**Términos de marca:** "..." | **Clics mínimos:** 5

| Consulta | Página | Intención | Clics | Sesiones Atrib. | Conversiones Atrib. | Ingresos Atrib. | Confianza |
|---|---|---|---|---|---|---|---|
| ... | ... | marca | 280 | 263.4 | 19.96 | 9.960 € | ALTA |

Titular: 903 clics, 697 sesiones atribuidas, 39 conversiones, 19.461 € de ingresos. La marca captura el 86% de las conversiones con el 57% de los clics.

Principales 3 impulsores de alta confianza
1. ...
2. ...
3. ...

Patrones
- ...
- ...

Archivos en esta habilidad

• attribution.sql: la consulta parametrizada
• SKILL.md: este archivo
• examples/synthetic_saas_demo.md: un ejemplo de salida para referencia