API de User Activity

La API de User Activity permite que el propietario de una propiedad de Google Analytics recupere todos los datos de medición de estadísticas asociados con un solo usuario. Específicamente, la API recupera todos los datos de medición asociados con un ID de usuario o de cliente en particular.

Nota: Consulta la referencia de User-ID para obtener una introducción breve a los IDs de cliente, los IDs de usuario y las diferencias entre ellos.

Cómo realizar una solicitud de actividad del usuario

Para realizar una solicitud de actividad del usuario, crea un objeto de solicitud con los siguientes campos:

1. El ID de cliente o el ID de usuario asociado con el usuario

   • Consulta Identificación de usuarios y cookies para obtener detalles acerca de cómo buscar estos campos.

2. Un ID de vista de Analytics que contiene los datos asociados con el usuario.

   • Puedes usar el Explorador de cuentas para buscar tu ID de vista.

3. Si bien no es obligatorio, es probable que necesites un período para los datos que te interesan. De forma predeterminada, la API muestra la actividad del usuario durante la última semana.

Nota: Consulta la documentación de referencia para obtener una lista completa de los campos que acepta esta API, incluidos los valores predeterminados de los campos opcionales.

Solicitud de muestra

POST https://analyticsreporting.googleapis.com/v4/userActivity:search

{
    "viewId": "9999999",
    "user": {
        "type": "CLIENT_ID",
        "userId": "1034600000.76425000000"
    },
    "dateRange": {
        "startDate": "2018-01-01",
        "endDate": "2018-12-31",
    }
}

Respuesta de ejemplo

{
    "sessions": [{
        "sessionId": "1539184430",
        "deviceCategory": "desktop",
        "platform": "Windows",
        "dataSource": "web",
        "sessionDate": "2018-10-10"
        "activities": [{
            "activityTime": "2018-10-10T08:13:50.555105Z",
            "source": "(direct)",
            "medium": "(none)",
            "channelGrouping": "Direct",
            "campaign": "(not set)",
            "keyword": "(not set)",
            "hostname": "shop.googlemerchandisestore.com",
            "landingPagePath": "/gpsmap",
            "activityType": "PAGEVIEW",
            "customDimension": [{
                "index": 1,
                "value": "(not set)"
            }, ...]
        }, ...]
    }, ...]
    "totalRows": 1000,
    "nextPageToken": "A6JGY3",
    "sampleRate": 1
}

Nota: En este ejemplo, usamos ... para indicar arrays truncados.

Sesiones y actividades

Los datos de actividad del usuario se agrupan por sesión. Cada sesión contiene información general sobre la sesión, como el ID y la fecha, así como una lista de actividades del usuario para esa sesión. Las actividades del usuario de una sesión consisten en cada "hit" de la que fue responsable el usuario. Esto incluye las vistas de página, los eventos de comercio electrónico y los eventos personalizados enviados a través de gtag(...) o ga(...).

Nota: Las sesiones no pueden abarcar los límites de fechas. Si el tiempo que un usuario permanece en el sitio abarca dos días diferentes, esto aparecerá como dos sesiones diferentes en fechas diferentes. Para obtener más información sobre cómo se define una sesión en Google Analytics, consulta Cómo se define una sesión web en Analytics

Nota: La referencia Activity contiene una definición más precisa de una actividad y las formas sutiles en que se diferencia de un hit o un evento.

Paginación

La API de User Activity usa la paginación para dividir grandes conjuntos de datos en varias solicitudes y respuestas. Sin embargo, debido a que los datos que muestra la API están estructurados de manera jerárquica, el desarrollador debe tener en cuenta algunas consideraciones especiales para recopilar los datos de forma correcta.

El tipo "fila" básico a los efectos de la paginación es la actividad. Debido a que los datos del usuario están agrupados por sesión, el límite de una página puede ocurrir dentro de una sesión, y esa sesión puede tener actividades que abarquen varias páginas.

Punto clave: Los límites de la página pueden ocurrir dentro de una sesión.

Datos de muestra

A los fines de la demostración, usaremos los siguientes datos de muestra. En este ejemplo, el usuario interactuó con el sitio en 6 sesiones a lo largo de 3 días.

Fecha	ID de sesión	Etiqueta del evento	Tiempo
2018-11-23	1	A	10:26
2018-11-23	1	B	10:32
2018-11-23	1	C	10:39
2018-11-23	2	A	18:04
2018-11-23	2	B	18:11
2018-11-23	2	C	18:26
2018-11-24	3	A	11:26
2018-11-24	3	B	11:29
2018-11-24	3	C	11:39
2018-11-24	3	D	11:42
2018-11-24	4	A	23:50
2018-11-24	4	B	23:54
2018-11-25	5	C	00:02
2018-11-25	5	D	00:13
2018-11-25	6	A	13:01
2018-11-25	6	B	13:09
2018-11-25	6	C	13:12
2018-11-25	6	D	13:23

Página única

Si realizas una solicitud de actividad del usuario con un pageSize de al menos 18, todos los datos se entregarán en una sola página y se verán de la siguiente manera:

POST https://analyticsreporting.googleapis.com/v4/userActivity:search

{
    "viewId": "9999999",
    "user": {
        "type": "CLIENT_ID",
        "userId": "1034600000.76425000000",
    },
    "dateRange": {
        "startDate": "2018-11-20",
        "endDate": "2018-11-30",
    },
    "pageSize": 100,
}

{
    "totalRows": 18,
    "sessions": [{
            "sessionId": "1",
            "sessionDate": "2018-11-23",
            "activities": [{
                    "activityTime": "2018-11-23T10:26:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-23T10:32:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-23T10:39:00",
                    "event": {"eventLabel": "C"}
                }]
        }, {
            "sessionId": "2",
            "sessionDate": "2018-11-23",
            "activities": [{
                    "activityTime": "2018-11-23T18:04:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-23T18:11:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-23T18:26:00",
                    "event": {"eventLabel": "C"}
                }]
        }, {
            "sessionId": "3",
            "sessionDate": "2018-11-24",
            "activities": [{
                    "activityTime": "2018-11-24T11:26:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-24T11:29:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-24T11:39:00",
                    "event": {"eventLabel": "C"}
                }, {
                    "activityTime": "2018-11-24T11:42:00",
                    "event": {"eventLabel": "D"}
                }]
        }, {
            "sessionId": "4",
            "sessionDate": "2018-11-24",
            "activities": [{
                    "activityTime": "2018-11-24T23:50:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-24T23:54:00",
                    "event": {"eventLabel": "B"}
                }]
        }, {
            "sessionId": "5",
            "sessionDate": "2018-11-25",
            "activities": [{
                    "activityTime": "2018-11-25T00:01:00",
                    "event": {"eventLabel": "C"}
                }, {
                    "activityTime": "2018-11-25T00:13:00",
                    "event": {"eventLabel": "D"}
                }]
        }, {
            "sessionId": "6",
            "sessionDate": "2018-11-25",
            "activities": [{
                    "activityTime": "2018-11-25T13:01:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-25T13:09:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-25T10:12:00",
                    "event": {"eventLabel": "C"}
                }, {
                    "activityTime": "2018-11-25T10:23:00",
                    "event": {"eventLabel": "D"}
                }]
        }]
}

Nota: Se omitieron muchos campos por cuestiones de brevedad. El propósito de este ejemplo es mostrar la agrupación jerárquica de actividades y sesiones.

Varias páginas

Sin embargo, si el tamaño de tu página es 5, estos datos se dividirán en 4 páginas de respuesta:

Fecha	ID de sesión	Etiqueta del evento	Tiempo
Página 1:
2018-11-23	1	A	10:26
2018-11-23	1	B	10:32
2018-11-23	1	C	10:39
2018-11-23	2	A	18:04
2018-11-23	2	B	18:11
Página 2:
2018-11-23	2	C	18:26
2018-11-24	3	A	11:26
2018-11-24	3	B	11:29
2018-11-24	3	C	11:39
2018-11-24	3	D	11:42
Página 3:
2018-11-24	4	A	23:50
2018-11-24	4	B	23:54
2018-11-25	5	C	00:02
2018-11-25	5	D	00:13
2018-11-25	6	A	13:01
Página 4:
2018-11-25	6	B	13:09
2018-11-25	6	C	13:12
2018-11-25	6	D	13:23

Nota: Las actividades del usuario siempre están en orden, lo que significa que el límite entre las páginas nunca será aleatorio; siempre estará entre sesiones y actividades adyacentes en el tiempo.

Ten en cuenta que la sesión 2 está dividida en la primera y la segunda página, y que las 2 sesiones del 24 de noviembre se dividen en la segunda y la tercera página. Las respuestas se verán de la siguiente manera:

{
    "totalRows": 18,
    "nextPageToken": "UGMGQS",
    "sessions": [{
            "sessionId": "1",
            "sessionDate": "2018-11-23",
            "activities": [{
                    "activityTime": "2018-11-23T10:26:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-23T10:32:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-23T10:39:00",
                    "event": {"eventLabel": "C"}
                }]
        }, {
            "sessionId": "2",
            "sessionDate": "2018-11-23",
            "activities": [{
                    "activityTime": "2018-11-23T18:04:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-23T18:11:00",
                    "event": {"eventLabel": "B"}
                }]
        }]
}

{
    "totalRows": 18,
    "nextPageToken": "1FKOME",
    "sessions": [{
            "sessionId": "2",
            "sessionDate": "2018-11-23",
            "activities": [{
                    "activityTime": "2018-11-23T18:26:00",
                    "event": {"eventLabel": "C"}
                }]
        }, {
            "sessionId": "3",
            "sessionDate": "2018-11-24",
            "activities": [{
                    "activityTime": "2018-11-24T11:26:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-24T11:29:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-24T11:39:00",
                    "event": {"eventLabel": "C"}
                }, {
                    "activityTime": "2018-11-24T11:42:00",
                    "event": {"eventLabel": "D"}
                }]
        }]
}

{
    "totalRows": 18,
    "nextPageToken": "7S77H6",
    "sessions": [{
            "sessionId": "4",
            "sessionDate": "2018-11-24",
            "activities": [{
                    "activityTime": "2018-11-24T23:50:00",
                    "event": {"eventLabel": "A"}
                }, {
                    "activityTime": "2018-11-24T23:54:00",
                    "event": {"eventLabel": "B"}
                }]
        }, {
            "sessionId": "5",
            "sessionDate": "2018-11-25",
            "activities": [{
                    "activityTime": "2018-11-25T00:01:00",
                    "event": {"eventLabel": "C"}
                }, {
                    "activityTime": "2018-11-25T00:13:00",
                    "event": {"eventLabel": "D"}
                }]
        }, {
            "sessionId": "6",
            "sessionDate": "2018-11-25",
            "activities": [{
                    "activityTime": "2018-11-25T13:01:00",
                    "event": {"eventLabel": "A"}
                }]
        }]
}

{
    "totalRows": 18,
    "sessions": [{
            "sessionId": "6",
            "sessionDate": "2018-11-25",
            "activities": [{
                    "activityTime": "2018-11-25T13:09:00",
                    "event": {"eventLabel": "B"}
                }, {
                    "activityTime": "2018-11-25T10:12:00",
                    "event": {"eventLabel": "C"}
                }, {
                    "activityTime": "2018-11-25T10:23:00",
                    "event": {"eventLabel": "D"}
                }]
        }]
}

Muestreo de datos

Si un cliente acumuló una gran cantidad de datos para el período solicitado, la API puede mostrar solo un subconjunto de actividades de muestra. Cuando esto suceda, el campo sampleRate indicará qué fracción de las actividades del usuario se devolvió.

Cómo se muestrean los datos

Los datos del usuario se muestrean a nivel de la actividad. Por ejemplo, con una tasa de muestreo del 50% (0.5), la mitad de las actividades del usuario estará presente en la respuesta.

Estas actividades de muestra se seleccionan de manera arbitraria. La API no proporciona ninguna garantía sobre el muestreo aleatorio ni que el muestreo es proporcional a todas las actividades del período determinado.

Evita el muestreo de datos

Debido a que esta API trata una sesión como una simple colección de actividades, las sesiones para las que no aparezcan actividades en el conjunto muestreado no aparecerán en la respuesta. Si necesitas una lista completa de sesiones o actividades, realiza solicitudes de seguimiento con períodos más pequeños.

Por ejemplo, si solicitas datos de 2018-01-01 a 2018-12-31, y la respuesta indica una tasa de muestreo de 0.25, divide el período solicitado en 4 partes, de manera que cada parte contenga aproximadamente un cuarto de los datos originales:

• De 2018-01-01 a 2018-03-31
• De 2018-04-01 a 2018-06-30
• De 2018-07-01 a 2018-09-30
• De 2018-10-01 a 2018-12-31

Nota: Debido a un posible agrupamiento en clústeres de datos aleatorio, estos subrangos también pueden muestrearse. Por ejemplo, si la mayoría de los datos del usuario se produjeron en el período 2018-01-01 a 2018-03-31, es posible que debas realizar solicitudes adicionales hasta que tengas todos los datos sin muestrear.