您可以使用 Google Analytics（分析）Data API v1 生成漏斗报告。借助漏斗探索，您可以直观了解用户为完成任务而采取的步骤，并快速查看用户在每个步骤上的成功或失败情况。
包含核心报告的共享功能
对于许多共享功能，漏斗报告请求与核心报告请求具有相同语义。例如，在“漏斗”报告中，分页、维度过滤条件和用户属性的行为与核心报告相同。本指南将着重介绍漏斗报告功能。要熟悉 Data API v1 的 Core Reporting 功能，请参阅报告基础知识指南以及高级用例指南。
漏斗报告方法
Data API v1 在 runFunnelReport 方法中支持漏斗报告功能。此方法会返回您的 Google Analytics（分析）事件数据的自定义漏斗报告。
选择举报实体
Data API v1 的所有方法都需要在网址请求路径中以 properties/GA4_PROPERTY_ID 的形式指定 Google Analytics（分析）4 媒体资源标识符，例如：
POST https://analyticsdata.googleapis.com/v1alpha/properties/GA4_PROPERTY_ID:runFunnelReport
所生成的报告将根据在指定的 Google Analytics（分析）4 媒体资源中收集的 Google Analytics（分析）事件数据生成。
如果您使用的是 Data API 客户端库之一，则无需手动操作请求网址路径。大多数 API 客户端都会提供一个 property 参数，该参数需要 properties/GA4_PROPERTY_ID 形式的字符串。如需查看有关如何使用客户端库的示例，请参阅快速入门指南。
漏斗报告请求
如需请求漏斗报告，您可以构建一个 RunFunnelReportRequest 对象。我们建议从以下请求参数入手：
dateRanges字段中的有效条目。funnel字段中的有效漏斗规范。
漏斗规范
RunFunnelReportRequest 对象的 funnel 字段中的漏斗规范定义了您要通过描述此漏斗的 steps 来衡量的用户体验历程。
漏斗步骤包含一个或多个条件，用户必须满足这些条件才能被纳入到漏斗历程的相应步骤中。每个步骤的 filterExpression 字段中都可以描述要纳入每个步骤的条件。
每个漏斗过滤器表达式都是两种类型的过滤器的组合：
funnelFieldFilter可用于为维度或指标创建过滤条件。funnelEventFilter用于创建与单个事件名称的事件匹配的过滤条件。如果指定了可选的funnelParameterFilterExpression字段，则只有与单个事件名称和参数过滤器表达式同时匹配的事件子集匹配此事件过滤器。
您可以使用 AND 或 OR 组来组合过滤条件，也可以使用 NOT 表达式进行否定组合。
每个漏斗步骤的报告结果都将根据维度细分，并在 funnelBreakdown 字段中指定。
漏斗报告示例
我们使用 Google Analytics（分析）Data API v1 重现 Google Analytics（分析）界面的漏斗探索模板中提供的默认漏斗报告：
漏斗步骤
上述漏斗配置包含以下步骤：
| # | 步骤名称 | 条件 |
|---|---|---|
| 1 | 首次打开/访问 | 事件名称为 first_open 或 first_visit。 |
| 2 | 以自然方式进行访问的用户 | 有 firstUserMedium 个维度包含“自然”一词。 |
| 3 | 会话开始 | 事件名称为 session_start。 |
| 4 | 浏览过屏幕/网页 | 事件名称为 screen_view 或 page_view。 |
| 5 | 购买 | 事件名称为 purchase 或 in_app_purchase。 |
漏斗的第 1 步（首次打开/访问）包括与网站或应用首次互动后的所有用户，即触发了 first_open 或 first_visit 事件的用户。
为了实现此行为，以下代码段使用 filterExpression 字段指定 FunnelStep 对象。过滤条件表达式字段是一个使用 OR 组将两个 FunnelEventFilter 实体组合在一起构造的 FunnelFilterExpression 对象。
{
"name": "Purchase",
"filterExpression": {
"orGroup": {
"expressions": [
{
"funnelEventFilter": {
"eventName": "first_open"
}
},
{
"funnelEventFilter": {
"eventName": "first_visit"
}
}
]
}
}
}
漏斗的第 2 步（自然访问者）包含第一个“媒介”包含“自然”一词的用户。在下面的代码段中，FunnelFieldFilter 的 fieldName 字段指示过滤器匹配 firstUserMedium 维度。stringFilter 字段包含一个条件，该条件仅包含包含字词“organic”的维度的值。
{
"name": "Organic visitors",
"filterExpression": {
"funnelFieldFilter": {
"fieldName": "firstUserMedium",
"stringFilter": {
"matchType": "CONTAINS",
"caseSensitive": false,
"value": "organic"
}
}
}
}
可以用类似的方式指定其余的漏斗步骤。
细分维度
您可以使用 FunnelBreakdown 对象指定可选的细分维度（本例中为 deviceCategory）：
"funnelBreakdown": {
"breakdownDimension": {
"name": "deviceCategory"
}
}
默认情况下，报告中仅包含细分维度的前 5 个不同的值。您可以使用 FunnelBreakdown 对象的 limit 字段来替换此行为。
完成漏斗报告查询
以下是使用上述所有步骤生成漏斗报告的完整查询：
HTTP
POST https://analyticsdata.googleapis.com/v1alpha/properties/GA4_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"
}
}
]
}
}
}
]
}
}
报告响应
漏斗报告 API 请求的漏斗报告响应由两个主要部分组成，均以 FunnelSubReport 对象的形式返回：漏斗可视化和漏斗表。
漏斗可视化
漏斗报告响应的 funnelVisualization 字段中返回的漏斗可视化，包含漏斗报告的简要概览。顾名思义，这对于快速直观呈现生成的漏斗报告非常有用。
“漏斗可视化”表格的每一行都包含以下部分或全部字段：
漏斗步骤名称（
funnelStepName维度）。活跃用户数（
activeUsers指标）。细分（
segment个维度）。仅当漏斗查询中指定了Segment时才显示。日期（
date个维度）。仅当查询中指定了TRENDED_FUNNEL可视化类型时才存在。“下一个操作”维度（
funnelStepNextAction个维度）。仅当漏斗查询中指定了FunnelNextAction时才显示。
上述示例报告在 Google Analytics（分析）界面中显示“漏斗可视化”部分的方式如下：
漏斗表
漏斗报告响应的 funnelTable 字段中返回的漏斗表是报告的主要部分。表中的每一行都包含以下部分或全部字段：
漏斗步骤名称（
funnelStepName维度）。细分维度。
活跃用户数（
activeUsers指标）。步骤完成率（
funnelStepCompletionRate指标）。步骤放弃次数（
funnelStepAbandonments指标）。步骤放弃率（
funnelStepAbandonmentRate指标）。细分名称（
segment维度）。仅当漏斗查询中指定了Segment时才显示。
与核心报告功能类似，总值会在单独的行中返回，并将 RESERVED_TOTAL 作为细分维度值。
以下是 Google Analytics（分析）界面中显示的漏斗表示例：
原始回复
以下代码段演示了为响应 runFunnelReport 查询而返回的原始数据示例。
根据您的媒体资源收集的数据，上面的示例报告将返回以下报告，显示每个漏斗步骤中包含的活跃用户数。
{
"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"
}
客户端库
以下示例使用运行漏斗查询并输出响应的客户端库。
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());
}
}
}
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)