يتيح لك الإصدار 1 من Google Analytics Data API إنشاء تقارير مسارات الإحالات الناجحة. يتيح لك استكشاف خطوات المستخدمين إمكانية عرض الخطوات التي يتّخذها المستخدمون لإكمال مهمة والاطّلاع بسرعة على مدى نجاحهم أو فشلهم في كل خطوة.

الميزات المشتركة مع التقارير الأساسية

تتسم طلبات إعداد تقارير مسارات الإحالات الناجحة بالدلالات نفسها مع طلبات التقارير الأساسية للعديد من الميزات المشتركة. على سبيل المثال، التقسيم على صفحات، تعمل فلاتر السمات وخصائص المستخدمين بالطريقة نفسها في تقارير مسارات الإحالات الناجحة مثل التقارير الأساسية. يركِّز هذا الدليل على ميزات إعداد تقارير مسار الإحالة الناجحة. للتعرّف على الوظيفة الأساسية لإعداد التقارير في الإصدار 1 من Data API، يُرجى قراءة دليل أساسيات إعداد التقارير ودليل حالات الاستخدام المتقدّمة.

طريقة إعداد تقارير مسار الإحالة الناجحة

يتيح الإصدار الأول من Data API إعداد تقارير مسارات الإحالات الناجحة في طريقة runFunnelReport. تعرِض هذه الطريقة تقرير مسار إحالة ناجحة مخصَّصًا لبيانات أحداث "إحصاءات Google".

اختيار كيان لإعداد التقارير

تتطلّب جميع طرق الإصدار 1 من Data API تحديد معرّف الموقع على "إحصاءات Google 4" داخل مسار طلب عنوان URL على شكل properties/GA4_PROPERTY_ID، مثل:

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

سيتم إنشاء التقرير الناتج استنادًا إلى بيانات أحداث "إحصاءات Google" التي يتمّ جمعها في موقع "إحصاءات Google 4" المحدّد.

وإذا كنت تستخدم إحدى مكتبات برامج واجهة برمجة التطبيقات للبيانات، لن يكون هناك داعٍ لمعالجة مسار عنوان URL للطلب يدويًا. توفّر معظم برامج واجهات برمجة التطبيقات مَعلمة property التي تتوقع سلسلة على شكل properties/GA4_PROPERTY_ID. راجِع دليل البدء السريع للاطّلاع على أمثلة على استخدام مكتبات العملاء.

طلب تقرير مسار الإحالة الناجحة

لطلب تقرير مسار إحالة ناجحة، يمكنك إنشاء عنصر RunFunnelReportRequest. نوصي بالبدء بمعلمات الطلب التالية:

• إدخال صالح في الحقل dateRanges.

• مواصفات مسار إحالة ناجحة صالحة في حقل funnel.

مواصفات مسار الإحالة الناجحة

إنّ مواصفات مسار الإحالة الناجحة في الحقل funnel لعنصر RunFunnelReportRequest تحدّد رحلة المستخدِم التي تريد قياسها من خلال وصف steps لمسار الإحالة الناجحة هذا.

تحتوي الخطوات في مسار الإحالة الناجحة على شرط واحد أو أكثر يجب أن يستوفيه المستخدمون لكي يتم تضمينهم في هذه الخطوة من رحلة مسار الإحالة الناجحة. يمكن وصف شروط التضمين في كل خطوة في الحقل filterExpression من كل خطوة.

يمثّل كل تعبير فلتر لمسار الإحالة الناجحة مزيجًا من نوعَين من الفلاتر:

• تُنشئ funnelFieldFilter فلترًا لسمة أو مقياسًا.

• تُنشئ funnelEventFilter فلترًا يطابِق الأحداث الخاصة باسم حدث واحد. في حال تحديد حقل funnelParameterFilterExpression اختياري، تتطابق فقط المجموعة الفرعية من الأحداث التي تتطابق مع اسم الحدث الفردي وتعبيرات فلتر المعلَمات مع فلتر الأحداث هذا.

يمكن دمج الفلاتر باستخدام المجموعات AND وOR، بالإضافة إلى إزالتها باستخدام تعبير NOT.

سيتم تقسيم نتائج التقرير لكل خطوة في مسار الإحالة الناجحة استنادًا إلى السمة، وسيتم تحديدها في الحقل funnelBreakdown.

مثال على تقرير مسار الإحالة الناجحة

لنستخدم الإصدار 1 من Data API على "إحصاءات Google" لإعادة إنتاج تقرير مسار الإحالة الناجحة التلقائي المقدَّم في نموذج استكشاف خطوات المستخدمين في واجهة مستخدم "إحصاءات Google":

الخطوات في مسار الإحالة الناجحة

تتضمّن إعدادات مسار الإحالة الناجحة الموضّحة أعلاه الخطوات التالية:

الخطوة 1 (أول فتح/زيارة) لمسار الإحالة الناجحة تشمل جميع المستخدمين بعد تفاعلهم الأول مع موقع إلكتروني أو تطبيق، أي المستخدمين الذين بدأوا أحداث first_open أو first_visit.

لتنفيذ هذا السلوك، يحدّد المقتطف أدناه عنصر FunnelStep مع حقل filterExpression. حقل تعبير الفلتر هو كائن FunnelFilterExpression تم إنشاؤه من خلال الجمع بين كيانَين FunnelEventFilter باستخدام مجموعة OR.

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

الخطوة 2 (الزوّار من نتائج البحث المجانية) من مسار الإحالة الناجحة تشمل المستخدمين الذين يشتمل وسيط الأول على عبارة "نتائج البحث المجانية". في المقتطف أدناه، يوجِّه الحقل fieldName في FunnelFieldFilter الفلتر لمطابقة السمة firstUserMedium. يحتوي الحقل stringFilter على شرط لتضمين قيم السمة التي تحتوي على المصطلح "مجاني" فقط.

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

يمكن تحديد الخطوات المتبقية في مسار الإحالة الناجحة بطريقة مشابهة.

سمة التصنيف التفصيلي

يمكن تحديد سمة تصنيف اختياري (deviceCategory في هذا المثال) باستخدام كائن FunnelBreakdown:

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

لا يتم تضمين سوى أول 5 قيم مميزة لسمة التصنيف التفصيلي تلقائيًا في التقرير. يمكنك استخدام الحقل limit للكائن FunnelBreakdown لإلغاء هذا السلوك.

طلب تقرير مسار الإحالة الناجحة الكامل

في ما يلي طلب بحث كامل يؤدي إلى إنشاء تقرير مسار إحالة ناجحة باستخدام جميع الخطوات الموضّحة أعلاه:

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"
                }
              }
            ]
          }
        }
      }
    ]
  }
}

الردّ على التقرير

يتكوّن استجابة تقرير مسار الإحالة الناجحة لطلب بيانات من واجهة برمجة التطبيقات لتقرير مسار الإحالة الناجحة من جزأين رئيسيَّين يتم عرضهما ككائن FunnelSubReport، وهما التمثيل البصري للمسار وجدول مسار الإحالة الناجحة.

التمثيل البصري للمسار

يحتوي التمثيل البصري لمسار الإحالة الناجحة، الذي يظهر في حقل funnelVisualization من استجابة تقرير مسار الإحالة الناجحة، على نظرة عامة عالية المستوى على تقرير مسار الإحالة الناجحة. وهذا مفيد، كما يشير الاسم، للحصول على مؤثرات عرض سريعة لتقرير مسار الإحالة الناجحة الذي تم إنشاؤه.

يحتوي كل صف من صفوف جدول "التمثيل البصري للمسار" على بعض أو كل الحقول التالية:

• اسم الخطوة في مسار الإحالة الناجحة (سمة واحدة (funnelStepName))

• عدد المستخدِمين النشطين (مقياس واحد (activeUsers))

• الشريحة (سمة واحدة (segment)) لا يتم عرضها إلا إذا تم تحديد Segment في طلب بحث مسار الإحالة الناجحة.

• التاريخ (سمة واحدة (date)) لا يتم العرض إلا إذا تم تحديد نوع التصور TRENDED_FUNNEL في طلب البحث.

• سمة الإجراء التالي (سمة واحدة (funnelStepNextAction)) لا يتم عرضه إلا إذا تم تحديد FunnelNextAction في طلب بحث مسار الإحالة الناجحة.

هذه هي الطريقة التي ستعرض بها واجهة مستخدم Google Analytics قسم "التمثيل البصري للمسار" في نموذج التقرير الذي تمت مناقشته أعلاه:

جدول مسار الإحالة الناجحة

ويمثّل جدول مسار الإحالة الناجحة، الذي يتم عرضه في الحقل funnelTable من استجابة تقرير مسار الإحالة الناجحة، الجزء الرئيسي من التقرير. يحتوي كل صف من صفوف الجدول على بعض أو كل الحقول التالية:

• اسم الخطوة في مسار الإحالة الناجحة (سمة واحدة (funnelStepName))

• سمة التصنيف التفصيلي.

• عدد المستخدِمين النشطين (مقياس واحد (activeUsers))

• معدّل إكمال الخطوة (مقياس واحد (funnelStepCompletionRate))

• عدد مرات العزوف عن الخطوات (مقياس واحد (funnelStepAbandonments))

• معدّل التراجع عن الخطوات (مقياس واحد (funnelStepAbandonmentRate))

• اسم الشريحة (سمة واحدة (segment)) لا يتم عرضها إلا إذا تم تحديد Segment في طلب بحث مسار الإحالة الناجحة.

على غرار وظيفة "إعداد التقارير الأساسية"، يتم عرض القيم الإجمالية في صف منفصل يحتوي على RESERVED_TOTAL كقيمة لسمة تصنيف تفصيلي.

في ما يلي مثال على "جدول مسار الإحالة الناجحة" المعروض في واجهة مستخدم "إحصاءات Google":

الردّ الأولي

يوضح المقتطف أدناه مثالاً على البيانات الأولية التي يتم عرضها استجابةً لطلب بحث 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"
}

مكتبات العملاء

راجِع دليل البدء السريع للحصول على شرح حول كيفية تثبيت مكتبات العملاء وضبطها.

في ما يلي أمثلة على استخدام مكتبات العملاء التي تشغِّل طلب بحث في مسار الإحالة الناجحة وتطبع الرد.

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());
    }
  }
}
RunFunnelReportSample.java

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)



run_funnel_report.py