---
name: shopify-trafico-por-pagina
description: "Reporta sesiones, tasa de conversión y tasa de rebote de cada página de producto y de colección con la analítica de Shopify. Úsala cuando quieras saber qué páginas atraen visitas y cuáles las convierten en ventas."
---

## Propósito
Consulta el motor de analítica integrado de Shopify (ShopifyQL) para obtener datos de tráfico por sesión de las páginas de producto y de colección. Muestra qué páginas atraen más tráfico, cuántas sesiones terminan en pedidos y dónde abandonan los visitantes: información lista para priorizar el SEO, enfocar el merchandising y elegir qué probar en pruebas A/B. Solo lectura: no ejecuta cambios.

## Requisitos
- Sesión autenticada de Shopify CLI: `shopify store auth --store <tu-tienda>.myshopify.com --scopes read_reports`. Las consultas se ejecutan con `shopify store execute`.
- Permisos (scopes) de API: `read_reports`
- Plan de Shopify: la analítica con ShopifyQL está disponible desde el plan Basic; para usar `sessions` como fuente de datos se necesita el plan Shopify o uno superior

## Parámetros

| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|-----------|------|-------------|----------------|-------------|
| store | string | sí | — | Dominio de la tienda (p. ej., mitienda.myshopify.com) |
| format | string | no | human | Formato de salida: `human` o `json` |
| dry_run | bool | no | false | Muestra una vista previa de las operaciones sin ejecutar cambios |
| days_back | integer | no | 30 | Ventana de análisis en días (p. ej., `30` = últimos 30 días) |
| page_type | string | no | both | Filtra por: `products`, `collections` o `both` |
| top_n | integer | no | 25 | Cantidad de páginas a mostrar en el ranking |
| sort_by | string | no | sessions | Métrica para ordenar: `sessions`, `conversion_rate` o `bounce_rate` |

## Pasos

1. **OPERACIÓN:** `shopifyqlQuery` — query (todas las páginas de entrada)
   **Entradas:** Texto ShopifyQL `FROM sessions SHOW sessions, conversion_rate GROUP BY landing_page_path SINCE -<days_back>d UNTIL today ORDER BY sessions DESC LIMIT 250`; `sessions` y `conversion_rate` son las métricas confirmadas para esta fuente de datos
   **Resultado esperado:** Todas las páginas de entrada con su cantidad de sesiones y su tasa de conversión; pagina con `OFFSET` si la cantidad de resultados es igual a 250

2. **Filtrado en memoria:** Filtra las filas cuyo `landing_page_path` empiece por `/products/` (páginas de producto) o `/collections/` (páginas de colección); aplica el parámetro `page_type`; ordena por `sort_by`; recorta a `top_n`; marca como `high_traffic_low_conversion` las páginas con sesiones por encima de la mediana y `conversion_rate < 0.02`

> **Nota:** ShopifyQL no admite `LIKE`, filtros `WHERE` por prefijo de texto ni alias de agregados que tapen nombres de columna reservados (`sessions`, `conversion_rate`). Todo el filtrado por tipo de página se debe hacer en memoria después de traer todas las filas.

## Operaciones GraphQL

```graphql
# shopifyqlQuery:query (tráfico por página) — validado con api_version 2025-01
query TrafficByPage($query: String!) {
  shopifyqlQuery(query: $query) {
    parseErrors
    tableData {
      columns {
        name
        dataType
        displayName
      }
      rows
    }
  }
}
```

La variable `$query` (una sola llamada: todas las páginas de entrada, filtradas en memoria):
```
FROM sessions
SHOW sessions, conversion_rate
GROUP BY landing_page_path
SINCE -<days_back>d
UNTIL today
ORDER BY sessions DESC
LIMIT 250
```

Luego filtra las filas en memoria:
- Páginas de producto: `landing_page_path.startsWith('/products/')`
- Páginas de colección: `landing_page_path.startsWith('/collections/')`
- `conversion_rate` llega como decimal (p. ej., `0.016` = 1,6 %): multiplícalo por 100 para mostrarlo

> **Confirmado en vivo con 2025-01:** `sessions` (INTEGER) y `conversion_rate` (PERCENT) son las métricas disponibles. `WHERE … LIKE`, `bounce_rate`, `converted_sessions` y los alias de agregados que tapan nombres reservados no se admiten en ShopifyQL `FROM sessions`.

## Seguimiento de la sesión

**Claude DEBE mostrar lo siguiente en cada etapa. Es obligatorio.**

**Al iniciar**, muestra:
```
╔══════════════════════════════════════════════╗
║  SKILL: Tráfico y conversión por página      ║
║  Tienda: <dominio de la tienda>              ║
║  Inicio: <AAAA-MM-DD HH:MM UTC>              ║
╚══════════════════════════════════════════════╝
```

**Después de cada paso**, muestra:
```
[N/TOTAL] <QUERY|MUTATION>  <NombreDeOperación>
          → Parámetros: <resumen breve de las entradas clave>
          → Resultado: <conteo o resultado>
```

**Al terminar**, muestra:

Para `format: human` (predeterminado):
```
══════════════════════════════════════════════
RESUMEN DEL RESULTADO
  Ventana de análisis:           <days_back> días
  Tipo de página:                <products|collections|both>
  Páginas analizadas:            <n>
  Página con más sesiones:       <ruta> (<n> sesiones)
  Página con mejor conversión:   <ruta> (<pct>%)
  Errores:                       0
  Archivo:                       traffic_by_page_<fecha>.csv
══════════════════════════════════════════════
```

Para `format: json`, muestra:
```json
{
  "skill": "shopify-trafico-por-pagina",
  "store": "<dominio>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": false,
  "steps": [
    { "step": 1, "operation": "ProductPageTraffic", "type": "query", "params_summary": "productos, últimos <days_back> días", "result_summary": "<n> páginas de producto obtenidas", "skipped": false },
    { "step": 2, "operation": "ProductPageTraffic", "type": "query", "params_summary": "colecciones, últimos <days_back> días", "result_summary": "<n> páginas de colección obtenidas", "skipped": false }
  ],
  "outcome": {
    "days_back": 30,
    "page_type": "both",
    "pages_analysed": 0,
    "results": [],
    "errors": 0,
    "output_file": "traffic_by_page_<fecha>.csv"
  }
}
```

## Formato de salida
Archivo CSV `traffic_by_page_<AAAA-MM-DD>.csv` con una fila por página:

| Columna | Descripción |
|---------|-------------|
| `page_type` | `product` o `collection` |
| `page_path` | Ruta de la URL (p. ej., `/products/red-sneaker`) |
| `sessions` | Total de sesiones que entraron por esta página |
| `conversion_rate_pct` | Tasa de conversión en porcentaje (la API la devuelve en decimal; se multiplica por 100) |
| `optimisation_flag` | `high_traffic_low_conversion` si las sesiones superan la mediana y la conversion_rate es < 2 % |

Con `format: human`, se muestra en pantalla una tabla con el ranking recortada a `top_n`, seguida de una lista corta de las páginas candidatas a optimizar marcadas con `high_traffic_low_conversion`.

## Manejo de errores
| Error | Causa | Solución |
|-------|-------|----------|
| `parseErrors` no vacío | Sintaxis ShopifyQL inválida; cada error es un texto simple | Registra cada texto y muéstraselo al usuario; causas comunes: poner alias a una columna reservada (`sessions`, `conversion_rate`), usar `LIKE` o pedir una columna que no existe, como `converted_sessions` o `bounce_rate` |
| `tableData` es null | No hay datos de analítica para el periodo | Amplía `days_back`; confirma que la tienda tenga tráfico |
| `ACCESS_DENIED` / falta el permiso `read_reports` | El permiso no se otorgó al autenticar | Vuelve a autenticar agregando el permiso `read_reports` |
| `THROTTLED` | Límite de solicitudes de analítica | Espera 2 s y reintenta hasta 3 veces |
| No quedan filas de producto o colección después de filtrar | Tienda de desarrollo o de pruebas, o sin tráfico que entre directo a las páginas del catálogo | Amplía `days_back`; ten en cuenta que la mayoría del tráfico puede entrar por la página de inicio |

## Buenas prácticas
1. Una `conversion_rate_pct` por debajo del 1 % en una página de producto con mucho tráfico merece revisión: mira si el producto está agotado, si tiene malas fotos o si le falta un llamado a la acción claro.
2. Las páginas de colección con tasas de rebote altas suelen indicar que el anuncio o el término de búsqueda que trajo la visita no coincide con el contenido de la colección: revisa el título SEO de la colección.
3. Usa `page_type: products` después de lanzar un producto nuevo para seguir su tracción inicial sin el ruido del tráfico de colecciones.
4. Combínala con `shopify-productos-mas-vendidos` para relacionar las páginas que mejor convierten con los productos que generan más ingresos reales.
5. Vuelve a correr el reporte cada semana después de hacer cambios en la página (textos, fotos, precios) para medir el impacto: la ventana de 7 días (`days_back: 7`) aísla bien el comportamiento posterior al cambio.