Casos de uso avanzados

En este documento, se describen varias funciones avanzadas de la API de datos de Google Analytics v1. Para obtener una referencia detallada de la API, consulta la referencia de la API.

Cómo enumerar definiciones personalizadas y crear informes

La API de datos puede crear informes sobre las dimensiones y métricas personalizadas registradas. El método de la API de metadatos se puede usar para enumerar los nombres de la API de las definiciones personalizadas registradas de tu propiedad. Estos nombres de la API se pueden usar en las solicitudes de informes al runReport, por ejemplo.

En las siguientes secciones, se muestran ejemplos de cada tipo de definición personalizada. En estos ejemplos, reemplaza GA_PROPERTY_ID por el ID de tu propiedad.

Dimensiones personalizadas centradas en el evento

Paso 1: Consulta el método de la API de metadatos con el ID de tu propiedad.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

Paso 2: Busca la dimensión personalizada centrada en el evento sobre la que te interesa crear informes en la respuesta. Si la dimensión no está presente, debes registrarla.

"dimensions": [
...
    {
      "apiName": "customEvent:achievement_id",
      "uiName": "Achievement ID",
      "description": "An event scoped custom dimension for your Analytics property."
    },
...
],

Paso 3: Incluye la dimensión personalizada en una solicitud de informe. A continuación, se muestra una solicitud de muestra al método runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
  "dimensions": [{ "name": "customEvent:achievement_id" }],
  "metrics": [{ "name": "eventCount" }]
}

Dimensiones personalizadas centradas en el usuario

Paso 1: Consulta el método de la API de metadatos con el ID de tu propiedad.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

Paso 2: Busca la dimensión personalizada centrada en el usuario sobre la que te interesa crear informes en la respuesta. Si la dimensión no está presente, debes registrarla.

"dimensions": [
...
    {
      "apiName": "customUser:last_level",
      "uiName": "Last level",
      "description": "A user property for your Analytics property."
    },
...
],

Paso 3: Incluye la dimensión personalizada en una solicitud de informe. A continuación, se muestra una solicitud de muestra al método runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "entity": { "propertyId": "GA_PROPERTY_ID" },
  "dateRanges": [{ "startDate": "7daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "customUser:last_level" }],
  "metrics": [{ "name": "activeUsers" }]
}

Métricas personalizadas centradas en el evento

Paso 1: Consulta el método de la API de metadatos con el ID de tu propiedad.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

Paso 2: Busca la métrica personalizada centrada en el evento sobre la que te interesa crear informes en la respuesta. Si la métrica no está presente, debes registrarla.

"metrics": [
...
    {
      "apiName": "customEvent:credits_spent",
      "uiName": "Credits Spent",
      "description": "An event scoped custom metric for your Analytics property.",
      "type": "TYPE_STANDARD"
    },
...
],

Paso 3: Incluye la métrica personalizada en una solicitud de informe. A continuación, se muestra una solicitud de muestra al método runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "customEvent:credits_spent" }]
}

Métricas de porcentaje de eventos clave para un evento clave

Paso 1: Consulta el método de la API de metadatos con el ID de tu propiedad.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

Paso 2: Busca la métrica de porcentaje de eventos clave para un evento clave sobre la que te interesa crear informes en la respuesta. Si el evento clave no está presente, debes configurar el evento clave.

"metrics": [
...
    {
      "apiName": "sessionKeyEventRate:add_to_cart",
      "uiName": "Session key event rate for add_to_cart",
      "description": "The percentage of sessions in which a specific key event was triggered",
    },
...
],

Paso 3: Incluye la métrica de porcentaje de eventos clave en una solicitud de informe. A continuación, se muestra una solicitud de muestra al método runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "sessionKeyEventRate:add_to_cart" }]
}

Promedios de métricas personalizadas centradas en el evento

Paso 1: Consulta el método de la API de metadatos con el ID de tu propiedad.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

Paso 2: Busca el promedio de métricas personalizadas centradas en el evento sobre el que te interesa crear informes en la respuesta. Si la métrica no está presente, debes registrarla.

"metrics": [
...
    {
      "apiName": "averageCustomEvent:credits_spent",
      "uiName": "Average Credits Spent",
      "description": "The average of an event scoped custom metric for your Analytics property.",
      "type": "TYPE_STANDARD"
    },
...
],

Paso 3: Incluye el promedio de métricas personalizadas en una solicitud de informe. A continuación, se muestra una solicitud de muestra al método runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "2020-11-01", "endDate": "2020-11-10" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "averageCustomEvent:credits_spent" }]
}

Ejemplos de informes de cohortes

Los informes de cohortes crean una serie temporal de la retención de usuarios para la cohorte. Para obtener documentación detallada de cada campo de la API, consulta la referencia de REST para CohortSpec.

Cómo crear un informe de cohorte

A continuación, se muestra un informe de cohorte de muestra en el que se cumplen las siguientes condiciones:

  • La cohorte está formada por usuarios con una firstSessionDate de 2020-12-01. Esto se configura con el objeto cohorts. Las dimensiones y métricas de la respuesta del informe solo se basarán en los usuarios de la cohorte.
  • El informe de cohorte mostrará tres columnas. Esto se configura con los objetos de dimensiones y métricas.
    • La dimensión cohort es el nombre de la cohorte.
    • La dimensión cohortNthDay es la cantidad de días desde 2020-12-01.
    • La métrica cohortActiveUsers es la cantidad de usuarios que aún están activos.
  • El objeto cohortsRange especifica que el informe debe contener datos de eventos que comiencen el 2020-12-01 y finalicen el 2020-12-06 para esta cohorte.
    • Cuando se usa una granularidad de DAILY, se recomienda la dimensión cohortNthDay para garantizar la coherencia.

La solicitud de informe para la cohorte es la siguiente:

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dimensions": [{ "name": "cohort" }, { "name": "cohortNthDay" }],
  "metrics": [{ "name": "cohortActiveUsers" }],
  "cohortSpec": {
    "cohorts": [
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-12-01", "endDate": "2020-12-01" }
      }
    ],
    "cohortsRange": {
      "endOffset": 5,
      "granularity": "DAILY"
    }
  },
}

Para esta solicitud, se muestra una respuesta de informe de ejemplo:

{
  "dimensionHeaders": [
    { "name": "cohort" }, { "name": "cohortNthDay" }
  ],
  "metricHeaders": [
    { "name": "cohortActiveUsers", "type": "TYPE_INTEGER" }
  ],
  "rows": [
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0000" }],
      "metricValues": [{ "value": "293" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0001" }],
      "metricValues": [{ "value": "143" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0002" }],
      "metricValues": [{ "value": "123" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0003" }],
      "metricValues": [{ "value": "92" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0005" }],
      "metricValues": [{ "value": "86" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0004" }],
      "metricValues": [{ "value": "83" }]
    }
  ],
  "metadata": {},
  "rowCount": 6
}

A partir de esta respuesta del informe, se muestra un gráfico para este informe de cohorte. Una estadística de este informe es que la mayor disminución en los usuarios activos de esta cohorte se produce entre el primer y el segundo día.

Visualización de los usuarios de la cohorte a lo largo del tiempo

Varias cohortes y fracción de retención de usuarios

La adquisición y la retención de usuarios son formas de hacer crecer tu sitio web o aplicación. Los informes de cohortes se centran en la retención de usuarios. En este ejemplo, el informe muestra que esta propiedad mejoró su retención de usuarios de 4 días en un 10% en el transcurso de dos semanas.

Para crear este informe, especificamos tres cohortes: la primera con una firstSessionDate de 2020-11-02, la segunda con una firstSessionDate de 2020-11-09 y la tercera con una firstSessionDate de 2020-11-16. Debido a que la cantidad de usuarios de tu propiedad será diferente para estos tres días, comparamos la métrica de fracción de retención de usuarios de la cohorte de cohortActiveUsers/cohortTotalUsers en lugar de usar la métrica directa cohortActiveUsers.

La solicitud de informe para estas cohortes es la siguiente:

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dimensions": [{ "name": "cohort" },{ "name": "cohortNthDay" }],
  "metrics": [
    {
      "name": "cohortRetentionFraction",
      "expression": "cohortActiveUsers/cohortTotalUsers"
    }
  ],
  "cohortSpec": {
    "cohorts": [
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-11-02", "endDate": "2020-11-02" }
      },
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-11-09", "endDate": "2020-11-09" }
      },
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-11-16", "endDate": "2020-11-16" }
      }
    ],
    "cohortsRange": {
      "endOffset": 4,
      "granularity": "DAILY"
    }
  },
}

Para esta solicitud, se muestra una respuesta de informe de ejemplo:

{
  "dimensionHeaders": [{ "name": "cohort" },{ "name": "cohortNthDay" }],
  "metricHeaders": [{
      "name": "cohortRetentionFraction",
      "type": "TYPE_FLOAT"
    }
  ],
  "rows": [
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0000" }],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0000" }],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0000" }],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0001" }],
      "metricValues": [{ "value": "0.308" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0001" }],
      "metricValues": [{ "value": "0.272" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0002" }],
      "metricValues": [{ "value": "0.257" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0001" }],
      "metricValues": [{ "value": "0.248" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0003" }],
      "metricValues": [{ "value": "0.235" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0004" }],
      "metricValues": [{ "value": "0.211" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0002" }],
      "metricValues": [{ "value": "0.198" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0002" }],
      "metricValues": [{ "value": "0.172" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0003" }],
      "metricValues": [{ "value": "0.167" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0004" }],
      "metricValues": [{ "value": "0.155" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0003" }],
      "metricValues": [{ "value": "0.141" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0004" }],
      "metricValues": [{ "value": "0.118" }]
    }
  ],
  "metadata": {},
  "rowCount": 15
}

A partir de esta respuesta del informe, se muestra un gráfico para este informe de cohorte. Una estadística de este informe es que la retención de usuarios de 4 días aumentó un 10% en el transcurso de dos semanas. La cohorte posterior con firstSessionDate de 2020-11-16 supera la retención de la cohorte anterior con firstSessionDate de 2020-11-02.

Gráfico de la retención de varias cohortes

Cohortes semanales y uso de cohortes con otras funciones de la API

Para quitar la varianza diaria en el comportamiento del usuario, usa cohortes semanales. En los informes de cohortes semanales, todos los usuarios con firstSessionDate en la misma semana forman la cohorte. Las semanas comienzan el domingo y terminan el sábado. Además, en este informe, segmentamos la cohorte para comparar los usuarios con actividad en Rusia con los usuarios con actividad en México. Esta segmentación usa la dimensión country y un dimensionFilter para considerar solo los dos países.

La solicitud de informe para estas cohortes es la siguiente:

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dimensions": [
    { "name": "cohort" },
    { "name": "cohortNthWeek" },
    { "name": "country" }
  ],
  "metrics": [{ "name": "cohortActiveUsers" }],
  "dimensionFilter": {
    "filter": {
      "fieldName": "country",
      "inListFilter": {
        "values": [ "Russia", "Mexico" ]
      }
    }
  },
  "cohortSpec": {
    "cohorts": [
      {
        "dimension": "firstSessionDate",
        "dateRange": {
          "startDate": "2020-10-04",
          "endDate": "2020-10-10"
        }
      }
    ],
    "cohortsRange": {
      "endOffset": 5,
      "granularity": "WEEKLY"
    }
  },
}

Para esta solicitud, se muestra una respuesta de informe de ejemplo:

{
  "dimensionHeaders": [
    { "name": "cohort" },
    { "name": "cohortNthWeek" },
    { "name": "country" }
  ],
  "metricHeaders": [
    { "name": "cohortActiveUsers", "type": "TYPE_INTEGER" }
  ],
  "rows": [
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0000" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "105" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0000" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "98" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0001" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "35" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0002" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "24" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0001" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "23" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0004" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "17" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0003" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "15" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0005" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "15" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0002" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "3" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0003" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0004" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "1" }]
    }
  ],
  "metadata": {},
  "rowCount": 11
}

A partir de esta respuesta del informe, se muestra un gráfico para este informe de cohorte. Según este informe, esta propiedad retiene mejor a los usuarios con actividad en México que a los usuarios con actividad en Rusia.

Gráfico de cohortes de comparación de países

Comparaciones

Las comparaciones te permiten evaluar subconjuntos de tus datos en paralelo. Puedes definir comparaciones especificando el comparisons campo en una definición de informe. La función Comparaciones de la API de datos es similar a las comparaciones en el frontend de Google Analytics.

Para obtener documentación detallada de cada campo de la API, consulta la referencia de REST para Comparison.

Cómo crear una comparación

Puedes crear una comparación independiente para cada conjunto de datos que desees comparar. Por ejemplo, si quieres comparar los datos web y de aplicaciones, puedes crear dos comparaciones: una para los datos web y otra para los datos de iOS y Android.

A continuación, se muestra un informe de muestra que define dos comparaciones y muestra los usuarios activos desglosados por país.

La primera comparación denominada "Tráfico de la app" usa el inListFilter para hacer coincidir la dimensión platform con los valores "iOS" y "Android". La segunda comparación denominada "Tráfico web" usa el stringFilter para hacer coincidir la dimensión platform con "web".

  POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
  {
    "comparisons": [
      {
        "name": "App traffic",
        "dimensionFilter": {
          "filter": {
            "fieldName": "platform",
            "inListFilter": {
              "values": [
                "iOS",
                "Android"
              ]
            }
          }
        }
      },
      {
        "name": "Web traffic",
        "dimensionFilter": {
          "filter": {
            "fieldName": "platform",
            "stringFilter": {
              "matchType": "EXACT",
              "value": "web"
            }
          }
        }
      }
    ],
    "dateRanges": [
      {
        "startDate": "2024-05-01",
        "endDate": "2024-05-15"
      }
    ],
    "dimensions": [
      {
        "name": "country"
      }
    ],
    "metrics": [
      {
        "name": "activeUsers"
      }
    ]
  }

Para todas las solicitudes que usan la función de comparaciones, el campo comparison se agrega automáticamente al informe generado. Este campo contiene el nombre de la comparación proporcionada en la solicitud.

A continuación, se muestra un fragmento de muestra de una respuesta que contiene comparaciones:

{
  "dimensionHeaders": [
    {
      "name": "comparison"
    },
    {
      "name": "country"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  "rows": [
    {
      "dimensionValues": [
        {
          "value": "Web traffic"
        },
        {
          "value": "United States"
        }
      ],
      "metricValues": [
        {
          "value": "638572"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Web traffic"
        },
        {
          "value": "Japan"
        }
      ],
      "metricValues": [
        {
          "value": "376578"
        }
      ]
    },
  {
      "dimensionValues": [
        {
          "value": "App traffic"
        },
        {
          "value": "United States"
        }
      ],
      "metricValues": [
        {
          "value": "79527"
        }
      ]
    },

    ...

  ],

...

}