Visão geral

Com a API Data v1 do Google Analytics, você pode gerar relatórios de funil. Com a análise detalhada de funil, você pode conferir as etapas que os usuários seguem até concluir uma tarefa e quais delas estão funcionando.

Recursos compartilhados com os relatórios principais

As solicitações de relatórios de funil têm a mesma semântica das solicitações de relatórios principais para vários recursos compartilhados. Por exemplo, a paginação, os filtros de dimensão e as propriedades do usuário se comportam da mesma forma nos relatórios de funil e nos principais. Este guia se concentra nos recursos de relatórios de funil. Para se familiarizar com a funcionalidade de relatórios principais da API Data v1, leia o guia de noções básicas sobre relatórios e o guia de casos de uso avançados.

Método de geração de relatórios de funil

A API Data v1 oferece suporte aos recursos de geração de relatórios de funil no método runFunnelReport. Esse método retorna um relatório de funil personalizado dos seus dados de eventos do Google Analytics.

Selecionar uma entidade de relatório

Todos os métodos da API Data v1 exigem que o identificador da propriedade do Google Analytics seja especificado em um caminho de solicitação de URL no formato de properties/GA_PROPERTY_ID, como:

  POST  https://analyticsdata.googleapis.com/v1alpha/properties/GA_PROPERTY_ID:runFunnelReport

O relatório resultante será gerado com base nos dados de eventos do Google Analytics coletados na propriedade especificada.

Se você estiver usando uma das bibliotecas de cliente da API Data, não será necessário manipular manualmente o caminho do URL da solicitação. A maioria dos clientes de API fornece um parâmetro property que deve ser preenchido com uma string no formato properties/GA_PROPERTY_ID. Consulte o guia de início rápido para exemplos de como usar as bibliotecas de cliente.

Solicitação de relatório de funil

Para solicitar um relatório de funil, crie um objeto RunFunnelReportRequest. Recomendamos começar com estes parâmetros de solicitação:

  • Uma entrada válida no campo dateRanges.

  • Uma especificação de funil válida no campo funnel.

Especificação do funil

Uma especificação de funil no campo funnel de um objeto RunFunnelReportRequest define a jornada do usuário que você quer medir ao descrever steps do funil.

As etapas do funil contêm uma ou mais condições que os usuários precisam atender para serem incluídas nessa etapa da jornada do funil. As condições de inclusão em cada etapa podem ser descritas no campo filterExpression de cada etapa.

Cada expressão de filtro de funil é uma combinação de dois tipos de filtros:

  • funnelFieldFilter cria um filtro para uma dimensão ou métrica.

  • funnelEventFilter cria um filtro que corresponde a eventos de um único nome de evento. Se um campo funnelParameterFilterExpression opcional for especificado, apenas o subconjunto de eventos que corresponder ao nome do evento único e às expressões do filtro de parâmetro vai corresponder a esse filtro de evento.

Os filtros podem ser combinados usando grupos AND, OR e negados usando uma expressão NOT.

Os resultados do relatório de cada etapa do funil serão divididos com base na dimensão e especificados no campo funnelBreakdown.

Exemplo de relatório de funil

O exemplo a seguir usa a API Data v1 do Google Analytics para reproduzir o relatório de funil padrão fornecido no modelo de análise detalhada de funil da interface da Web do Google Analytics:

Exemplo de interface do Relatório de funil

Etapas do funil

A configuração do funil anterior contém as seguintes etapas:

# Nome da etapa Condição
1 Primeiro acesso/visita O nome do evento é first_open ou first_visit.
2 Visitantes orgânicos A dimensão firstUserMedium contém o termo "orgânica".
3 Início de sessão O nome do evento é session_start.
4 Visualização de tela/página O nome do evento é screen_view ou page_view.
5 Compra O nome do evento é purchase ou in_app_purchase.

A Etapa 1 (primeiro acesso/visita) do funil inclui todos os usuários após a primeira interação com um site ou aplicativo, como aqueles que acionaram os eventos first_open ou first_visit.

Para implementar esse comportamento, o snippet a seguir especifica um objeto FunnelStep com um campo filterExpression.

O campo de expressão de filtro é um objeto FunnelFilterExpression criado pela combinação de duas entidades FunnelEventFilter usando um grupo OR.

  {
    "name": "Purchase",
    "filterExpression": {
      "orGroup": {
        "expressions": [
          {
            "funnelEventFilter": {
              "eventName": "first_open"
            }
          },
          {
            "funnelEventFilter": {
              "eventName": "first_visit"
            }
          }
        ]
      }
    }
  }

A etapa 2 (visitantes orgânicos) do funil inclui usuários cujo primeiro mídia inclui o termo "orgânico". No snippet abaixo, o campo fieldName de FunnelFieldFilter instrui o filtro a corresponder à dimensão firstUserMedium. O campo stringFilter contém uma condição para incluir apenas os valores da dimensão que contêm o termo "orgânico".

  {
    "name": "Organic visitors",
    "filterExpression": {
      "funnelFieldFilter": {
        "fieldName": "firstUserMedium",
        "stringFilter": {
          "matchType": "CONTAINS",
          "caseSensitive": false,
          "value": "organic"
        }
      }
    }
  }

As etapas restantes do funil podem ser especificadas de maneira semelhante.

Dimensão detalhada

Uma dimensão de detalhamento opcional (deviceCategory neste exemplo) pode ser especificada usando um objeto FunnelBreakdown:

  "funnelBreakdown": {
    "breakdownDimension": {
      "name": "deviceCategory"
    }
  }

Por padrão, apenas os cinco primeiros valores distintos da dimensão de detalhamento são incluídos no relatório. É possível usar o campo limit do objeto FunnelBreakdown para substituir esse comportamento.

Consulta de relatório de funil completo

Esta é uma consulta completa que gera um Relatório de funil:

HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/GA_PROPERTY_ID:runFunnelReport
{
  "dateRanges": [
    {
      "startDate": "30daysAgo",
      "endDate": "today"
    }
  ],
  "funnelBreakdown": {
    "breakdownDimension": {
      "name": "deviceCategory"
    }
  },
  "funnel": {
    "steps": [
      {
        "name": "First open/visit",
        "filterExpression": {
          "orGroup": {
            "expressions": [
              {
                "funnelEventFilter": {
                  "eventName": "first_open"
                }
              },
              {
                "funnelEventFilter": {
                  "eventName": "first_visit"
                }
              }
            ]
          }
        }
      },
      {
        "name": "Organic visitors",
        "filterExpression": {
          "funnelFieldFilter": {
            "fieldName": "firstUserMedium",
            "stringFilter": {
              "matchType": "CONTAINS",
              "caseSensitive": false,
              "value": "organic"
            }
          }
        }
      },
      {
        "name": "Session start",
        "filterExpression": {
          "funnelEventFilter": {
            "eventName": "session_start"
          }
        }
      },
      {
        "name": "Screen/Page view",
        "filterExpression": {
          "orGroup": {
            "expressions": [
              {
                "funnelEventFilter": {
                  "eventName": "screen_view"
                }
              },
              {
                "funnelEventFilter": {
                  "eventName": "page_view"
                }
              }
            ]
          }
        }
      },
      {
        "name": "Purchase",
        "filterExpression": {
          "orGroup": {
            "expressions": [
              {
                "funnelEventFilter": {
                  "eventName": "purchase"
                }
              },
              {
                "funnelEventFilter": {
                  "eventName": "in_app_purchase"
                }
              }
            ]
          }
        }
      }
    ]
  }
}

Denunciar resposta

A resposta do relatório de funil de uma solicitação de API de relatório de funil consiste em duas partes principais, ambas retornadas como um objeto FunnelSubReport: Visualização de funil e Tabela de funil.

Visualização de funil

A visualização do funil, retornada no campo funnelVisualization da resposta do relatório de funil, contém uma visão geral de alto nível do relatório de funil. Isso é útil, como o nome indica, para uma visualização rápida do relatório de funil gerado.

Cada linha da tabela de visualização de funil contém alguns ou todos os seguintes campos:

  • Nome da etapa do funil (dimensão funnelStepName).

  • Contagem de usuários ativos (métrica activeUsers).

  • Segmento (dimensão segment). Aparece apenas se Segment for especificado na consulta de funil.

  • Data (dimensão date). Aparece apenas se o tipo de visualização TRENDED_FUNNEL foi especificado na consulta.

  • Dimensão da próxima ação (funnelStepNextAction). Aparece apenas se o FunnelNextAction for especificado na consulta de funil.

Confira como a interface da Web do Google Analytics mostra a seção de visualização do funil do exemplo de relatório deste guia:

Cabeçalhos do relatório de funil: exemplo

Tabela do funil

A tabela de funil, retornada no campo funnelTable da resposta do relatório de funil, representa a parte principal do relatório. Cada linha da tabela contém alguns ou todos os seguintes campos:

  • Nome da etapa do funil (dimensão funnelStepName).

  • Dimensão detalhada.

  • Contagem de usuários ativos (métrica activeUsers).

  • Taxa de conclusão de etapa (métrica funnelStepCompletionRate).

  • Contagem de desistências de etapa (métrica funnelStepAbandonments).

  • Taxa de desistências por etapa (métrica funnelStepAbandonmentRate).

  • Nome do segmento (dimensão segment). Aparece apenas se Segment for especificado na consulta de funil.

Os valores totais são retornados em uma linha separada com RESERVED_TOTAL como um valor de dimensão de detalhamento.

Confira um exemplo da tabela de funil exibida na interface da Web do Google Analytics:

Tabela do Relatório de funil: exemplo

Resposta bruta

O snippet a seguir demonstra um exemplo de dados brutos retornados em resposta à consulta runFunnelReport.

Dependendo dos dados coletados pela sua propriedade, o relatório de exemplo vai mostrar o número de usuários ativos incluídos em cada etapa do funil.

{
  "funnelTable": {
    "dimensionHeaders": [
      {
        "name": "funnelStepName"
      },
      {
        "name": "deviceCategory"
      }
    ],
    "metricHeaders": [
      {
        "name": "activeUsers",
        "type": "TYPE_INTEGER"
      },
      {
        "name": "funnelStepCompletionRate",
        "type": "TYPE_INTEGER"
      },
      {
        "name": "funnelStepAbandonments",
        "type": "TYPE_INTEGER"
      },
      {
        "name": "funnelStepAbandonmentRate",
        "type": "TYPE_INTEGER"
      }
    ],
    "rows": [
      {
        "dimensionValues": [
          {
            "value": "1. First open/visit"
          },
          {
            "value": "RESERVED_TOTAL"
          }
        ],
        "metricValues": [
          {
            "value": "4621565"
          },
          {
            "value": "0.27780178359495106"
          },
          {
            "value": "3337686"
          },
          {
            "value": "0.72219821640504889"
          }
        ]
      },
      {
        "dimensionValues": [
          {
            "value": "1. First open/visit"
          },
          {
            "value": "desktop"
          }
        ],
        "metricValues": [
          {
            "value": "4015959"
          },
          {
            "value": "0.27425279989163237"
          },
          {
            "value": "2914571"
          },
          {
            "value": "0.72574720010836768"
          }
        ]
      },
      {
        "dimensionValues": [
          {
            "value": "1. First open/visit"
          },
          {
            "value": "mobile"
          }
        ],
        "metricValues": [
          {
            "value": "595760"
          },
          {
            "value": "0.29156035987646034"
          },
          {
            "value": "422060"
          },
          {
            "value": "0.70843964012353966"
          }
        ]
      },
      {
        "dimensionValues": [
          {
            "value": "1. First open/visit"
          },
          {
            "value": "tablet"
          }
        ],
        "metricValues": [
          {
            "value": "33638"
          },
          {
            "value": "0.205571080325822"
          },
          {
            "value": "26723"
          },
          {
            "value": "0.79442891967417806"
          }
        ]
      },

...

    ],
    "metadata": {
      "samplingMetadatas": [
        {
          "samplesReadCount": "9917254",
          "samplingSpaceSize": "1162365416"
        }
      ]
    }
  },

  "funnelVisualization": {
    "dimensionHeaders": [
      {
        "name": "funnelStepName"
      }
    ],
    "metricHeaders": [
      {
        "name": "activeUsers",
        "type": "TYPE_INTEGER"
      }
    ],
    "rows": [
      {
        "dimensionValues": [
          {
            "value": "1. First open/visit"
          }
        ],
        "metricValues": [
          {
            "value": "4621565"
          }
        ]
      },

...

    ],
    "metadata": {
      "samplingMetadatas": [
        {
          "samplesReadCount": "9917254",
          "samplingSpaceSize": "1162365416"
        }
      ]
    }
  },
  "kind": "analyticsData#runFunnelReport"
}

Bibliotecas de cliente

Consulte o guia de início rápido para saber como instalar e configurar as bibliotecas de cliente.

Confira exemplos de uso de bibliotecas de cliente que executam uma consulta de funil e mostram a resposta.

Java

import com.google.analytics.data.v1alpha.AlphaAnalyticsDataClient;
import com.google.analytics.data.v1alpha.DateRange;
import com.google.analytics.data.v1alpha.Dimension;
import com.google.analytics.data.v1alpha.DimensionHeader;
import com.google.analytics.data.v1alpha.FunnelBreakdown;
import com.google.analytics.data.v1alpha.FunnelEventFilter;
import com.google.analytics.data.v1alpha.FunnelFieldFilter;
import com.google.analytics.data.v1alpha.FunnelFilterExpression;
import com.google.analytics.data.v1alpha.FunnelFilterExpressionList;
import com.google.analytics.data.v1alpha.FunnelStep;
import com.google.analytics.data.v1alpha.FunnelSubReport;
import com.google.analytics.data.v1alpha.MetricHeader;
import com.google.analytics.data.v1alpha.Row;
import com.google.analytics.data.v1alpha.RunFunnelReportRequest;
import com.google.analytics.data.v1alpha.RunFunnelReportResponse;
import com.google.analytics.data.v1alpha.SamplingMetadata;
import com.google.analytics.data.v1alpha.StringFilter;
import com.google.analytics.data.v1alpha.StringFilter.MatchType;

/**
 * Google Analytics Data API sample application demonstrating the creation of a funnel report.
 *
 * <p>See
 * https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/runFunnelReport
 * for more information.
 *
 * <p>Before you start the application, please review the comments starting with "TODO(developer)"
 * and update the code to use correct values.
 *
 * <p>To run this sample using Maven:
 *
 * <pre>{@code
 * cd google-analytics-data
 * mvn compile exec:java -Dexec.mainClass="com.google.analytics.data.samples.RunFunnelReportSample"
 * }</pre>
 */
public class RunFunnelReportSample {

  public static void main(String... args) throws Exception {
    /**
     * TODO(developer): Replace this variable with your Google Analytics 4 property ID before
     * running the sample.
     */
    String propertyId = "YOUR-GA4-PROPERTY-ID";
    sampleRunFunnelReport(propertyId);
  }

  /**
   * Runs a funnel query to build a report with 5 funnel steps.
   *
   * <ol>
   *   <li>First open/visit (event name is `first_open` or `first_visit`).
   *   <li>Organic visitors (`firstUserMedium` dimension contains the term "organic").
   *   <li>Session start (event name is `session_start`).
   *   <li>Screen/Page view (event name is `screen_view` or `page_view`).
   *   <li>Purchase (event name is `purchase` or `in_app_purchase`).
   * </ol>
   *
   * The report configuration reproduces the default funnel report provided in the Funnel
   * Exploration template of the Google Analytics UI. See more at
   * https://support.google.com/analytics/answer/9327974
   */
  static void sampleRunFunnelReport(String propertyId) throws Exception {

    // Using a default constructor instructs the client to use the credentials
    // specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
    try (AlphaAnalyticsDataClient analyticsData = AlphaAnalyticsDataClient.create()) {
      RunFunnelReportRequest.Builder requestBuilder =
          RunFunnelReportRequest.newBuilder()
              .setProperty("properties/" + propertyId)
              .addDateRanges(DateRange.newBuilder().setStartDate("30daysAgo").setEndDate("today"))
              .setFunnelBreakdown(
                  FunnelBreakdown.newBuilder()
                      .setBreakdownDimension(Dimension.newBuilder().setName("deviceCategory")));

      // Adds each step of the funnel.
      requestBuilder
          .getFunnelBuilder()
          .addSteps(
              FunnelStep.newBuilder()
                  .setName("First open/visit")
                  .setFilterExpression(
                      FunnelFilterExpression.newBuilder()
                          .setOrGroup(
                              FunnelFilterExpressionList.newBuilder()
                                  .addExpressions(
                                      FunnelFilterExpression.newBuilder()
                                          .setFunnelEventFilter(
                                              FunnelEventFilter.newBuilder()
                                                  .setEventName("first_open")))
                                  .addExpressions(
                                      FunnelFilterExpression.newBuilder()
                                          .setFunnelEventFilter(
                                              FunnelEventFilter.newBuilder()
                                                  .setEventName("first_visit"))))));
      requestBuilder
          .getFunnelBuilder()
          .addSteps(
              FunnelStep.newBuilder()
                  .setName("Organic visitors")
                  .setFilterExpression(
                      FunnelFilterExpression.newBuilder()
                          .setFunnelFieldFilter(
                              FunnelFieldFilter.newBuilder()
                                  .setFieldName("firstUserMedium")
                                  .setStringFilter(
                                      StringFilter.newBuilder()
                                          .setMatchType(MatchType.CONTAINS)
                                          .setCaseSensitive(false)
                                          .setValue("organic")))));
      requestBuilder
          .getFunnelBuilder()
          .addSteps(
              FunnelStep.newBuilder()
                  .setName("Session start")
                  .setFilterExpression(
                      FunnelFilterExpression.newBuilder()
                          .setFunnelEventFilter(
                              FunnelEventFilter.newBuilder().setEventName("session_start"))));

      requestBuilder
          .getFunnelBuilder()
          .addSteps(
              FunnelStep.newBuilder()
                  .setName("Screen/Page view")
                  .setFilterExpression(
                      FunnelFilterExpression.newBuilder()
                          .setOrGroup(
                              FunnelFilterExpressionList.newBuilder()
                                  .addExpressions(
                                      FunnelFilterExpression.newBuilder()
                                          .setFunnelEventFilter(
                                              FunnelEventFilter.newBuilder()
                                                  .setEventName("screen_view")))
                                  .addExpressions(
                                      FunnelFilterExpression.newBuilder()
                                          .setFunnelEventFilter(
                                              FunnelEventFilter.newBuilder()
                                                  .setEventName("page_view"))))));
      requestBuilder
          .getFunnelBuilder()
          .addSteps(
              FunnelStep.newBuilder()
                  .setName("Purchase")
                  .setFilterExpression(
                      FunnelFilterExpression.newBuilder()
                          .setOrGroup(
                              FunnelFilterExpressionList.newBuilder()
                                  .addExpressions(
                                      FunnelFilterExpression.newBuilder()
                                          .setFunnelEventFilter(
                                              FunnelEventFilter.newBuilder()
                                                  .setEventName("purchase")))
                                  .addExpressions(
                                      FunnelFilterExpression.newBuilder()
                                          .setFunnelEventFilter(
                                              FunnelEventFilter.newBuilder()
                                                  .setEventName("in_app_purchase"))))));

      // Make the request.
      RunFunnelReportResponse response = analyticsData.runFunnelReport(requestBuilder.build());
      printRunFunnelReportResponse(response);
    }
  }

  /** Prints results of a runFunnelReport call. */
  static void printRunFunnelReportResponse(RunFunnelReportResponse response) {
    System.out.println("Report result:");
    System.out.println("=== FUNNEL VISUALIZATION ===");
    printFunnelSubReport(response.getFunnelVisualization());

    System.out.println("=== FUNNEL TABLE ===");
    printFunnelSubReport(response.getFunnelTable());
  }

  /** Prints the contents of a FunnelSubReport object. */
  private static void printFunnelSubReport(FunnelSubReport funnelSubReport) {
    System.out.println("Dimension headers:");
    for (DimensionHeader dimensionHeader : funnelSubReport.getDimensionHeadersList()) {
      System.out.println(dimensionHeader.getName());
    }
    System.out.println();

    System.out.println("Metric headers:");
    for (MetricHeader metricHeader : funnelSubReport.getMetricHeadersList()) {
      System.out.println(metricHeader.getName());
    }
    System.out.println();

    System.out.println("Dimension and metric values for each row in the report:");
    for (int rowIndex = 0; rowIndex < funnelSubReport.getRowsCount(); rowIndex++) {
      Row row = funnelSubReport.getRows(rowIndex);
      for (int fieldIndex = 0; fieldIndex < row.getDimensionValuesCount(); fieldIndex++) {
        System.out.printf(
            "%s: '%s'%n",
            funnelSubReport.getDimensionHeaders(fieldIndex).getName(),
            row.getDimensionValues(fieldIndex).getValue());
      }
      for (int fieldIndex = 0; fieldIndex < row.getMetricValuesCount(); fieldIndex++) {
        System.out.printf(
            "%s: '%s'%n",
            funnelSubReport.getMetricHeaders(fieldIndex).getName(),
            row.getMetricValues(fieldIndex).getValue());
      }
    }
    System.out.println();

    System.out.println("Sampling metadata for each date range:");
    for (int metadataIndex = 0;
        metadataIndex < funnelSubReport.getMetadata().getSamplingMetadatasCount();
        metadataIndex++) {
      SamplingMetadata samplingMetadata =
          funnelSubReport.getMetadata().getSamplingMetadatas(metadataIndex);
      System.out.printf(
          "Sampling metadata for date range #%d: samplesReadCount=%d, samplingSpaceSize=%d%n",
          metadataIndex,
          samplingMetadata.getSamplesReadCount(),
          samplingMetadata.getSamplingSpaceSize());
    }
  }
}

PHP

use Google\Analytics\Data\V1alpha\Client\AlphaAnalyticsDataClient;
use Google\Analytics\Data\V1alpha\DateRange;
use Google\Analytics\Data\V1alpha\Dimension;
use Google\Analytics\Data\V1alpha\FunnelBreakdown;
use Google\Analytics\Data\V1alpha\FunnelEventFilter;
use Google\Analytics\Data\V1alpha\FunnelFieldFilter;
use Google\Analytics\Data\V1alpha\FunnelFilterExpression;
use Google\Analytics\Data\V1alpha\FunnelFilterExpressionList;
use Google\Analytics\Data\V1alpha\FunnelStep;
use Google\Analytics\Data\V1alpha\Funnel;
use Google\Analytics\Data\V1alpha\FunnelSubReport;
use Google\Analytics\Data\V1alpha\RunFunnelReportRequest;
use Google\Analytics\Data\V1alpha\RunFunnelReportResponse;
use Google\Analytics\Data\V1alpha\StringFilter;
use Google\Analytics\Data\V1alpha\StringFilter\MatchType;

/**
 * Runs a funnel query to build a report with 5 funnel steps.
 *
 * Step 1: First open/visit (event name is `first_open` or `first_visit`).
 * Step 2: Organic visitors (`firstUserMedium` dimension contains the term "organic").
 * Step 3: Session start (event name is `session_start`).
 * Step 4: Screen/Page view (event name is `screen_view` or `page_view`).
 * Step 5: Purchase (event name is `purchase` or `in_app_purchase`).
 *
 * The report configuration reproduces the default funnel report provided in the Funnel
 * Exploration template of the Google Analytics UI. See more at
 * https://support.google.com/analytics/answer/9327974
 *
 * @param string $propertyId Your GA-4 Property ID
 */
function run_funnel_report(string $propertyId)
{
    // Create an instance of the Google Analytics Data API client library.
    $client = new AlphaAnalyticsDataClient();

    // Create the funnel report request.
    $request = (new RunFunnelReportRequest())
        ->setProperty('properties/' . $propertyId)
        ->setDateRanges([
            new DateRange([
                'start_date' => '30daysAgo',
                'end_date' => 'today',
            ]),
        ])
        ->setFunnelBreakdown(
            new FunnelBreakdown([
                'breakdown_dimension' =>
                    new Dimension([
                        'name' => 'deviceCategory'
                    ])
            ])
        )
        ->setFunnel(new Funnel());

    // Add funnel steps to the funnel.

    // 1. Add first open/visit step.
    $request->getFunnel()->getSteps()[] = new FunnelStep([
        'name' => 'First open/visit',
        'filter_expression' => new FunnelFilterExpression([
            'or_group' => new FunnelFilterExpressionList([
                'expressions' => [
                    new FunnelFilterExpression([
                        'funnel_event_filter' => new FunnelEventFilter([
                            'event_name' => 'first_open',
                        ])
                    ]),
                    new FunnelFilterExpression([
                        'funnel_event_filter' => new FunnelEventFilter([
                            'event_name' => 'first_visit'
                        ])
                    ])
                ]
            ])
        ])
    ]);

    // 2. Add organic visitors step.
    $request->getFunnel()->getSteps()[] = new FunnelStep([
        'name' => 'Organic visitors',
        'filter_expression' => new FunnelFilterExpression([
            'funnel_field_filter' => new FunnelFieldFilter([
                'field_name' => 'firstUserMedium',
                'string_filter' => new StringFilter([
                    'match_type' => MatchType::CONTAINS,
                    'case_sensitive' => false,
                    'value' => 'organic',
                ])
            ])
        ])
    ]);

    // 3. Add session start step.
    $request->getFunnel()->getSteps()[] = new FunnelStep([
        'name' => 'Session start',
        'filter_expression' => new FunnelFilterExpression([
            'funnel_event_filter' => new FunnelEventFilter([
                'event_name' => 'session_start',
            ])
        ])
    ]);

    // 4. Add screen/page view step.
    $request->getFunnel()->getSteps()[] = new FunnelStep([
        'name' => 'Screen/Page view',
        'filter_expression' => new FunnelFilterExpression([
            'or_group' => new FunnelFilterExpressionList([
                'expressions' => [
                    new FunnelFilterExpression([
                        'funnel_event_filter' => new FunnelEventFilter([
                            'event_name' => 'screen_view',
                        ])
                    ]),
                    new FunnelFilterExpression([
                        'funnel_event_filter' => new FunnelEventFilter([
                            'event_name' => 'page_view'
                        ])
                    ])
                ]
            ])
        ])
    ]);

    // 5. Add purchase step.
    $request->getFunnel()->getSteps()[] = new FunnelStep([
        'name' => 'Purchase',
        'filter_expression' => new FunnelFilterExpression([
            'or_group' => new FunnelFilterExpressionList([
                'expressions' => [
                    new FunnelFilterExpression([
                        'funnel_event_filter' => new FunnelEventFilter([
                            'event_name' => 'purchase',
                        ])
                    ]),
                    new FunnelFilterExpression([
                        'funnel_event_filter' => new FunnelEventFilter([
                            'event_name' => 'in_app_purchase'
                        ])
                    ])
                ]
            ])
        ])
    ]);

    // Make an API call.
    $response = $client->runFunnelReport($request);

    printRunFunnelReportResponse($response);
}

/**
 * Print results of a runFunnelReport call.
 * @param RunFunnelReportResponse $response
 */
function printRunFunnelReportResponse(RunFunnelReportResponse $response)
{
    print 'Report result: ' . PHP_EOL;
    print '=== FUNNEL VISUALIZATION ===' . PHP_EOL;
    printFunnelSubReport($response->getFunnelVisualization());

    print '=== FUNNEL TABLE ===' . PHP_EOL;
    printFunnelSubReport($response->getFunnelTable());
}

/**
 * Print the contents of a FunnelSubReport object.
 * @param FunnelSubReport $subReport
 */
function printFunnelSubReport(FunnelSubReport $subReport)
{
    print 'Dimension headers:' . PHP_EOL;
    foreach ($subReport->getDimensionHeaders() as $dimensionHeader) {
        print $dimensionHeader->getName() . PHP_EOL;
    }

    print PHP_EOL . 'Metric headers:' . PHP_EOL;
    foreach ($subReport->getMetricHeaders() as $metricHeader) {
        print $metricHeader->getName() . PHP_EOL;
    }

    print PHP_EOL . 'Dimension and metric values for each row in the report:';
    foreach ($subReport->getRows() as $rowIndex => $row) {
        print PHP_EOL . 'Row #' . $rowIndex . PHP_EOL;
        foreach ($row->getDimensionValues() as $dimIndex => $dimValue) {
            $dimName = $subReport->getDimensionHeaders()[$dimIndex]->getName();
            print $dimName . ": '" . $dimValue->getValue() . "'" . PHP_EOL;
        }
        foreach ($row->getMetricValues() as $metricIndex => $metricValue) {
            $metricName = $subReport->getMetricHeaders()[$metricIndex]->getName();
            print $metricName . ": '" . $metricValue->getValue() . "'" . PHP_EOL;
        }
    }

    print PHP_EOL . 'Sampling metadata for each date range:' . PHP_EOL;
    foreach ($subReport->getMetadata()->getSamplingMetadatas() as $metadataIndex => $metadata) {
        printf('Sampling metadata for date range #%d: samplesReadCount=%d' .
            'samplingSpaceSize=%d%s',
            $metadataIndex, $metadata->getSamplesReadCount(), $metadata->getSamplingSpaceSize(), PHP_EOL);
    }
}

Python

from google.analytics.data_v1alpha import AlphaAnalyticsDataClient
from google.analytics.data_v1alpha.types import (
    DateRange,
    Dimension,
    Funnel,
    FunnelBreakdown,
    FunnelEventFilter,
    FunnelFieldFilter,
    FunnelFilterExpression,
    FunnelFilterExpressionList,
    FunnelStep,
    RunFunnelReportRequest,
    StringFilter,
)


def run_sample():
    """Runs the sample."""
    # TODO(developer): Replace this variable with your Google Analytics 4
    #  property ID before running the sample.
    property_id = "YOUR-GA4-PROPERTY-ID"
    run_funnel_report(property_id)


def run_funnel_report(property_id="YOUR-GA4-PROPERTY-ID"):
    """Runs a funnel query to build a report with 5 funnel steps.
      Step 1: First open/visit (event name is `first_open` or `first_visit`).
      Step 2: Organic visitors (`firstUserMedium` dimension contains the term
      "organic").
      Step 3: Session start (event name is `session_start`).
      Step 4: Screen/Page view (event name is `screen_view` or `page_view`).
      Step 5: Purchase (event name is `purchase` or `in_app_purchase`).

    The report configuration reproduces the default funnel report provided in
    the Funnel Exploration template of the Google Analytics UI.
    See more at https://support.google.com/analytics/answer/9327974
    """
    client = AlphaAnalyticsDataClient()

    request = RunFunnelReportRequest(
        property=f"properties/{property_id}",
        date_ranges=[DateRange(start_date="30daysAgo", end_date="today")],
        funnel_breakdown=FunnelBreakdown(
            breakdown_dimension=Dimension(name="deviceCategory")
        ),
        funnel=Funnel(
            steps=[
                FunnelStep(
                    name="First open/visit",
                    filter_expression=FunnelFilterExpression(
                        or_group=FunnelFilterExpressionList(
                            expressions=[
                                FunnelFilterExpression(
                                    funnel_event_filter=FunnelEventFilter(
                                        event_name="first_open"
                                    )
                                ),
                                FunnelFilterExpression(
                                    funnel_event_filter=FunnelEventFilter(
                                        event_name="first_visit"
                                    )
                                ),
                            ]
                        )
                    ),
                ),
                FunnelStep(
                    name="Organic visitors",
                    filter_expression=FunnelFilterExpression(
                        funnel_field_filter=FunnelFieldFilter(
                            field_name="firstUserMedium",
                            string_filter=StringFilter(
                                match_type=StringFilter.MatchType.CONTAINS,
                                case_sensitive=False,
                                value="organic",
                            ),
                        )
                    ),
                ),
                FunnelStep(
                    name="Session start",
                    filter_expression=FunnelFilterExpression(
                        funnel_event_filter=FunnelEventFilter(
                            event_name="session_start"
                        )
                    ),
                ),
                FunnelStep(
                    name="Screen/Page view",
                    filter_expression=FunnelFilterExpression(
                        or_group=FunnelFilterExpressionList(
                            expressions=[
                                FunnelFilterExpression(
                                    funnel_event_filter=FunnelEventFilter(
                                        event_name="screen_view"
                                    )
                                ),
                                FunnelFilterExpression(
                                    funnel_event_filter=FunnelEventFilter(
                                        event_name="page_view"
                                    )
                                ),
                            ]
                        )
                    ),
                ),
                FunnelStep(
                    name="Purchase",
                    filter_expression=FunnelFilterExpression(
                        or_group=FunnelFilterExpressionList(
                            expressions=[
                                FunnelFilterExpression(
                                    funnel_event_filter=FunnelEventFilter(
                                        event_name="purchase"
                                    )
                                ),
                                FunnelFilterExpression(
                                    funnel_event_filter=FunnelEventFilter(
                                        event_name="in_app_purchase"
                                    )
                                ),
                            ]
                        )
                    ),
                ),
            ]
        ),
    )
    response = client.run_funnel_report(request)
    print_run_funnel_report_response(response)


def print_funnel_sub_report(funnel_sub_report):
    """Prints the contents of a FunnelSubReport object."""
    print("Dimension headers:")
    for dimension_header in funnel_sub_report.dimension_headers:
        print(dimension_header.name)

    print("\nMetric headers:")
    for metric_header in funnel_sub_report.metric_headers:
        print(metric_header.name)

    print("\nDimensions and metric values for each row in the report:")
    for row_idx, row in enumerate(funnel_sub_report.rows):
        print("\nRow #{}".format(row_idx))
        for field_idx, dimension_value in enumerate(row.dimension_values):
            dimension_name = funnel_sub_report.dimension_headers[field_idx].name
            print("{}: '{}'".format(dimension_name, dimension_value.value))

        for field_idx, metric_value in enumerate(row.metric_values):
            metric_name = funnel_sub_report.metric_headers[field_idx].name
            print("{}: '{}'".format(metric_name, metric_value.value))

    print("\nSampling metadata for each date range:")
    for metadata_idx, metadata in enumerate(
        funnel_sub_report.metadata.sampling_metadatas
    ):
        print(
            "Sampling metadata for date range #{}: samplesReadCount={}, "
            "samplingSpaceSize={}".format(
                metadata_idx, metadata.samples_read_count, metadata.sampling_space_size
            )
        )


def print_run_funnel_report_response(response):
    """Prints results of a runFunnelReport call."""
    print("Report result:")
    print("=== FUNNEL VISUALIZATION ===")
    print_funnel_sub_report(response.funnel_visualization)

    print("=== FUNNEL TABLE ===")
    print_funnel_sub_report(response.funnel_table)