您可以使用 Google Analytics (分析) Data API v1 產生漏斗報表。「漏斗探索」會透過視覺圖表，呈現使用者完成某件事所採取的步驟，迅速瞭解使用者完成或不完成各個步驟的情況。
與核心報表共用的功能
對於許多共用功能，漏斗報表要求採用的語意與核心報表要求的語意相同。舉例來說，分頁、維度篩選器和使用者屬性在漏斗報表中的運作方式與核心報表相同。本指南著重於漏斗報表功能。如要熟悉 Data API 第 1 版的核心報表功能，請參閱報表基本指南和進階用途指南。
漏斗報表方法
Data API v1 支援 runFunnelReport 方法中的漏斗報表功能。這個方法會傳回 Google Analytics (分析) 事件資料的自訂漏斗報表。
選取檢舉實體
所有 Data API v1 方法都需要在網址要求路徑內指定 Google Analytics (分析) 4 資源 ID，格式為 properties/GA4_PROPERTY_ID，例如：
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 (分析) UI 中漏斗探索範本中提供的預設漏斗報表：
漏斗步驟
上述漏斗設定包含以下步驟：
| # | 步驟名稱 | 條件 |
|---|---|---|
| 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 欄位包含條件，僅納入包含「自然」一詞的維度值。
{
"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 (分析) UI 顯示上述範例報表「漏斗視覺呈現」部分的方式：
漏斗表格
「漏斗表格」在漏斗報表回應的 funnelTable 欄位中傳回的程序，代表報表的主要部分。資料表中的每一列都包含下列部分或所有欄位：
漏斗步驟名稱 (
funnelStepName維度)。細分維度：
活躍使用者人數 (
activeUsers個指標)。步驟完成率 (
funnelStepCompletionRate指標)。步驟放棄計數 (
funnelStepAbandonments指標)。步驟放棄率 (
funnelStepAbandonmentRate指標)。區隔名稱 (
segment維度)。只有在漏斗查詢中指定Segment時才會顯示。
與 Core Reporting 功能類似，總值會在單獨的資料列中傳回，並以 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)