این یک نمای کلی از قابلیت‌های بیدرنگ گزارش API Method Google Analytics Data API v1 است. برای مرجع دقیق API، به مرجع API مراجعه کنید.
رویدادها چند ثانیه پس از ارسال به Google Analytics در گزارش‌های بلادرنگ ظاهر می‌شوند. گزارش‌های بلادرنگ رویدادها و داده‌های استفاده را برای دوره‌های زمانی از لحظه حال تا 30 دقیقه قبل (تا 60 دقیقه برای ویژگی‌های Google Analytics 360) نشان می‌دهند و می‌توانند برای برنامه‌هایی مانند شمارشگر زنده بازدیدکنندگان در وب‌سایت شما استفاده شوند.
گزارش‌های بلادرنگ از زیرمجموعه‌ای محدود از ابعاد و معیارها در مقایسه با عملکرد اصلی گزارش‌دهی Data API v1 پشتیبانی می‌کنند.
ویژگی های مشترک با گزارش های اصلی
درخواست‌های گزارش هم‌زمان با درخواست‌های گزارش اصلی برای بسیاری از ویژگی‌های مشترک معنایی مشابهی دارند. برای مثال صفحه‌بندی ، فیلترهای ابعاد و ویژگی‌های کاربر ، در گزارش‌های بیدرنگ مانند گزارش‌های اصلی رفتار می‌کنند. لطفاً با نمای کلی عملکرد گزارش هسته Data API v1 آشنا شوید، زیرا بقیه این سند بر روی ویژگی‌های خاص درخواست‌های گزارش بلادرنگ تمرکز خواهد کرد.
درخواست گزارش
برای درخواست گزارش های بلادرنگ، می توانید یک شی RunRealtimeReportRequest بسازید. توصیه می کنیم با این پارامترهای درخواست شروع کنید:
در اینجا یک نمونه درخواست با فیلدهای توصیه شده است.
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runRealtimeReport
{
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }]
}
جاوا
import com.google.analytics.data.v1beta.BetaAnalyticsDataClient;
import com.google.analytics.data.v1beta.Dimension;
import com.google.analytics.data.v1beta.DimensionHeader;
import com.google.analytics.data.v1beta.Metric;
import com.google.analytics.data.v1beta.MetricHeader;
import com.google.analytics.data.v1beta.Row;
import com.google.analytics.data.v1beta.RunRealtimeReportRequest;
import com.google.analytics.data.v1beta.RunRealtimeReportResponse;
/**
* Google Analytics Data API sample application demonstrating the creation of a realtime report.
*
* <p>See
* https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runRealtimeReport
* 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.RunRealtimeReportSample"
* }</pre>
*/
public class RunRealtimeReportSample {
public static void main(String... args) throws Exception {
// TODO(developer): Replace with your Google Analytics 4 property ID before running the sample.
String propertyId = "YOUR-GA4-PROPERTY-ID";
sampleRunRealtimeReport(propertyId);
}
// Runs a realtime report on a Google Analytics 4 property.
static void sampleRunRealtimeReport(String propertyId) throws Exception {
// Initialize client that will be used to send requests. This client only needs to be created
// once, and can be reused for multiple requests. After completing all of your requests, call
// the "close" method on the client to safely clean up any remaining background resources.
try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {
RunRealtimeReportRequest request =
RunRealtimeReportRequest.newBuilder()
.setProperty("properties/" + propertyId)
.addDimensions(Dimension.newBuilder().setName("country"))
.addMetrics(Metric.newBuilder().setName("activeUsers"))
.build();
// Make the request.
RunRealtimeReportResponse response = analyticsData.runRealtimeReport(request);
printRunRealtimeReportResponse(response);
}
}
// Prints results of a runRealReport call.
static void printRunRealtimeReportResponse(RunRealtimeReportResponse response) {
System.out.printf("%s rows received%n", response.getRowsList().size());
for (DimensionHeader header : response.getDimensionHeadersList()) {
System.out.printf("Dimension header name: %s%n", header.getName());
}
for (MetricHeader header : response.getMetricHeadersList()) {
System.out.printf("Metric header name: %s (%s)%n", header.getName(), header.getType());
}
System.out.println("Report result:");
for (Row row : response.getRowsList()) {
System.out.printf(
"%s, %s%n", row.getDimensionValues(0).getValue(), row.getMetricValues(0).getValue());
}
}
}
پایتون
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
Dimension,
Metric,
RunRealtimeReportRequest,
)
from run_report import print_run_report_response
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_realtime_report(property_id)
def run_realtime_report(property_id="YOUR-GA4-PROPERTY-ID"):
"""Runs a realtime report on a Google Analytics 4 property."""
client = BetaAnalyticsDataClient()
request = RunRealtimeReportRequest(
property=f"properties/{property_id}",
dimensions=[Dimension(name="country")],
metrics=[Metric(name="activeUsers")],
)
response = client.run_realtime_report(request)
print_run_report_response(response)
گزارش پاسخ
پاسخ گزارش بلادرنگ درخواست API در درجه اول یک سرصفحه و ردیف است. هدر شامل DimensionHeaders و MetricHeader است که ستون های گزارش را فهرست می کند. هر ردیف از DimensionValues و MetricValues برای ستون های گزارش تشکیل شده است. ترتیب ستون ها در درخواست، سرصفحه و هر سطر سازگار است.
در اینجا یک نمونه پاسخ برای درخواست نمونه بالا آمده است:
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "Japan"
}
],
"metricValues": [
{
"value": "2541"
}
]
},
{
"dimensionValues": [
{
"value": "France"
}
],
"metricValues": [
{
"value": "12"
}
]
}
],
"rowCount": 2
}
ابعاد
ابعاد، داده‌های رویداد را برای وب‌سایت یا برنامه شما توصیف و گروه‌بندی می‌کند. برای مثال، بعد city ، شهری ("پاریس" یا "نیویورک") را نشان می دهد که هر رویداد از آن سرچشمه گرفته است. در یک درخواست گزارش، می توانید ابعاد صفر یا بیشتر را مشخص کنید. برای لیست کاملی از نام‌های ابعاد API موجود در درخواست‌های بلادرنگ، ابعاد Realtime را ببینید.
به عنوان مثال، این درخواست کاربران فعال را در ستون های دو بعدی گروه بندی می کند:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/property/GA4_PROPERTY_ID:runRealtimeReport
{
"dimensions": [
{
"name": "country"
},
{
"name": "city"
}
],
"metrics": [{ "name": "activeUsers" }]
}
جاوا
import com.google.analytics.data.v1beta.BetaAnalyticsDataClient;
import com.google.analytics.data.v1beta.Dimension;
import com.google.analytics.data.v1beta.Metric;
import com.google.analytics.data.v1beta.RunRealtimeReportRequest;
import com.google.analytics.data.v1beta.RunRealtimeReportResponse;
/**
* Google Analytics Data API sample application demonstrating the creation of a realtime report.
*
* <p>See
* https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runRealtimeReport
* 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.RunRealtimeReportWithMultipleDimensionsSample"
* }</pre>
*/
public class RunRealtimeReportWithMultipleDimensionsSample {
public static void main(String... args) throws Exception {
// TODO(developer): Replace with your Google Analytics 4 property ID before running the sample.
String propertyId = "YOUR-GA4-PROPERTY-ID";
sampleRunRealtimeReportWithMultipleDimensions(propertyId);
}
// Runs a realtime report on a Google Analytics 4 property.
static void sampleRunRealtimeReportWithMultipleDimensions(String propertyId) throws Exception {
// Initialize client that will be used to send requests. This client only needs to be created
// once, and can be reused for multiple requests. After completing all of your requests, call
// the "close" method on the client to safely clean up any remaining background resources.
try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {
RunRealtimeReportRequest request =
RunRealtimeReportRequest.newBuilder()
.setProperty("properties/" + propertyId)
.addDimensions(Dimension.newBuilder().setName("country"))
.addDimensions(Dimension.newBuilder().setName(("city")))
.addMetrics(Metric.newBuilder().setName("activeUsers"))
.build();
// Make the request.
RunRealtimeReportResponse response = analyticsData.runRealtimeReport(request);
// Prints the response using a method in RunRealtimeReportSample.java
RunRealtimeReportSample.printRunRealtimeReportResponse(response);
}
}
}
پایتون
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
Dimension,
Metric,
RunRealtimeReportRequest,
)
from run_report import print_run_report_response
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_realtime_report_with_multiple_dimensions(property_id)
def run_realtime_report_with_multiple_dimensions(property_id="YOUR-GA4-PROPERTY-ID"):
"""Runs a realtime report on a Google Analytics 4 property."""
client = BetaAnalyticsDataClient()
request = RunRealtimeReportRequest(
property=f"properties/{property_id}",
dimensions=[Dimension(name="country"), Dimension(name="city")],
metrics=[Metric(name="activeUsers")],
)
response = client.run_realtime_report(request)
print_run_report_response(response)
به عنوان نمونه، یک ردیف در پاسخ گزارش می تواند حاوی موارد زیر باشد. این ردیف به این معنی است که 47 کاربر فعال برای وب سایت یا برنامه شما با رویدادهایی از کیپ تاون، آفریقای جنوبی در 30 دقیقه گذشته وجود دارد.
"rows": [
...
{
"dimensionValues": [
{
"value": "South Africa"
},
{
"value": "Cape Town"
}
],
"metricValues": [
{
"value": "47"
}
]
},
...
],
معیارهای
معیارها اندازه گیری کمی داده های رویداد برای وب سایت یا برنامه شما هستند. در یک درخواست گزارش، می توانید یک یا چند معیار را مشخص کنید. برای فهرست کامل نام‌های سنجش API موجود در درخواست‌ها ، معیارهای بیدرنگ را ببینید.
به عنوان مثال، این درخواست دو معیار گروه بندی شده توسط بعد unifiedScreenName را نشان می دهد:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/property/GA4_PROPERTY_ID:runRealtimeReport
{
"dimensions": [{ "name": "unifiedScreenName" }],
"metrics": [
{
"name": "screenPageViews"
},
{
"name": "conversions"
}
],
}
جاوا
import com.google.analytics.data.v1beta.BetaAnalyticsDataClient;
import com.google.analytics.data.v1beta.Dimension;
import com.google.analytics.data.v1beta.Metric;
import com.google.analytics.data.v1beta.RunRealtimeReportRequest;
import com.google.analytics.data.v1beta.RunRealtimeReportResponse;
/**
* Google Analytics Data API sample application demonstrating the creation of a realtime report.
*
* <p>See
* https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runRealtimeReport
* 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.RunRealtimeReportWithMultipleMetricsSample"
* }</pre>
*/
public class RunRealtimeReportWithMultipleMetricsSample {
public static void main(String... args) throws Exception {
// TODO(developer): Replace with your Google Analytics 4 property ID before running the sample.
String propertyId = "YOUR-GA4-PROPERTY-ID";
sampleRunRealtimeReportWithMultipleMetrics(propertyId);
}
// Runs a realtime report on a Google Analytics 4 property.
static void sampleRunRealtimeReportWithMultipleMetrics(String propertyId) throws Exception {
// Initialize client that will be used to send requests. This client only needs to be created
// once, and can be reused for multiple requests. After completing all of your requests, call
// the "close" method on the client to safely clean up any remaining background resources.
try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {
RunRealtimeReportRequest request =
RunRealtimeReportRequest.newBuilder()
.setProperty("properties/" + propertyId)
.addDimensions(Dimension.newBuilder().setName("unifiedScreenName"))
.addMetrics(Metric.newBuilder().setName(("screenPageViews")))
.addMetrics(Metric.newBuilder().setName("conversions"))
.build();
// Make the request.
RunRealtimeReportResponse response = analyticsData.runRealtimeReport(request);
// Prints the response using a method in RunRealtimeReportSample.java
RunRealtimeReportSample.printRunRealtimeReportResponse(response);
}
}
}
پایتون
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
Dimension,
Metric,
RunRealtimeReportRequest,
)
from run_report import print_run_report_response
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_realtime_report_with_multiple_metrics(property_id)
def run_realtime_report_with_multiple_metrics(property_id="YOUR-GA4-PROPERTY-ID"):
"""Runs a realtime report on a Google Analytics 4 property."""
client = BetaAnalyticsDataClient()
request = RunRealtimeReportRequest(
property=f"properties/{property_id}",
dimensions=[Dimension(name="unifiedScreenName")],
metrics=[Metric(name="screenPageViews"), Metric(name="conversions")],
)
response = client.run_realtime_report(request)
print_run_report_response(response)
به عنوان نمونه، یک ردیف در پاسخ گزارش می تواند حاوی موارد زیر باشد. این ردیف به این معنی است که برای عنوان صفحه (وب) یا نام صفحه (برنامه) main_menu ، 257 بازدید و 72 رویداد تبدیل در 30 دقیقه گذشته وجود داشته است.
"rows": [
...
{
"dimensionValues": [
{
"value": "main_menu"
}
],
"metricValues": [
{
"value": "257"
},
{
"value": "72"
}
]
},
...
],
محدوده دقیقه
در درخواست گزارش بلادرنگ، می‌توانید از فیلد minuteRanges برای تعیین محدوده دقیقه داده‌های رویداد برای خواندن استفاده کنید. حداکثر دو محدوده دقیقه جداگانه را می توان در یک پرس و جو استفاده کرد. اگر مشخصات محدوده دقیقه در یک جستجو وجود نداشته باشد، یک محدوده دقیقه تک برای 30 دقیقه آخر استفاده خواهد شد.
به عنوان مثال، درخواست زیر تعداد کاربران فعال را برای دو محدوده دقیقه جداگانه نشان می دهد:
- محدوده شماره 1: از 4 دقیقه قبل تا لحظه حال شروع می شود.
محدوده شماره 2: از 29 دقیقه قبل تا 25 دقیقه قبل (شامل).
HTTP
POST https://analyticsdata.googleapis.com/v1beta/property/GA4_PROPERTY_ID:runRealtimeReport
{
"metrics": [
{
"name": "activeUsers"
}
],
"minuteRanges": [
{
"name": "0-4 minutes ago",
"startMinutesAgo": 4,
},
{
"name": "25-29 minutes ago",
"startMinutesAgo": 29,
"endMinutesAgo": 25,
}
],
}
جاوا
import com.google.analytics.data.v1beta.BetaAnalyticsDataClient;
import com.google.analytics.data.v1beta.Metric;
import com.google.analytics.data.v1beta.MinuteRange;
import com.google.analytics.data.v1beta.RunRealtimeReportRequest;
import com.google.analytics.data.v1beta.RunRealtimeReportResponse;
/**
* Google Analytics Data API sample application demonstrating the creation of a realtime report.
*
* <p>See
* https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runRealtimeReport
* 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.RunRealtimeReportWithMinuteRangesSample"
* }</pre>
*/
public class RunRealtimeReportWithMinuteRangesSample {
public static void main(String... args) throws Exception {
// TODO(developer): Replace with your Google Analytics 4 property ID before running the sample.
String propertyId = "YOUR-GA4-PROPERTY-ID";
sampleRunRealtimeReportWithMinuteRanges(propertyId);
}
// Runs a realtime report on a Google Analytics 4 property.
static void sampleRunRealtimeReportWithMinuteRanges(String propertyId) throws Exception {
// Initialize client that will be used to send requests. This client only needs to be created
// once, and can be reused for multiple requests. After completing all of your requests, call
// the "close" method on the client to safely clean up any remaining background resources.
try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {
RunRealtimeReportRequest request =
RunRealtimeReportRequest.newBuilder()
.setProperty("properties/" + propertyId)
.addMetrics(Metric.newBuilder().setName(("activeUsers")))
.addMinuteRanges(
MinuteRange.newBuilder().setName("0-4 minutes ago").setStartMinutesAgo(4))
.addMinuteRanges(
MinuteRange.newBuilder()
.setName("25-29 minutes ago")
.setEndMinutesAgo(29)
.setEndMinutesAgo(25))
.build();
// Make the request.
RunRealtimeReportResponse response = analyticsData.runRealtimeReport(request);
// Prints the response using a method in RunRealtimeReportSample.java
RunRealtimeReportSample.printRunRealtimeReportResponse(response);
}
}
}
پایتون
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
Metric,
MinuteRange,
RunRealtimeReportRequest,
)
from run_report import print_run_report_response
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_realtime_report_with_minute_ranges(property_id)
def run_realtime_report_with_minute_ranges(property_id="YOUR-GA4-PROPERTY-ID"):
"""Runs a realtime report on a Google Analytics 4 property. Dimensions
field is omitted in the query, which results in total values of active users
returned for each minute range in the report.
Note the `dateRange` dimension added to the report response automatically
as a result of querying multiple minute ranges.
"""
client = BetaAnalyticsDataClient()
request = RunRealtimeReportRequest(
property=f"properties/{property_id}",
metrics=[Metric(name="activeUsers")],
minute_ranges=[
MinuteRange(name="0-4 minutes ago", start_minutes_ago=4),
MinuteRange(
name="25-29 minutes ago", start_minutes_ago=29, end_minutes_ago=25
),
],
)
response = client.run_realtime_report(request)
print_run_report_response(response)
در زیر نمونه کامل پاسخ برای پرسش زیر آمده است. به بعد dateRange که به‌طور خودکار در نتیجه جستجو در محدوده‌های چند دقیقه‌ای به پاسخ گزارش اضافه می‌شود توجه کنید.
{
"dimensionHeaders": [
{
"name": "dateRange"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "0-4 minutes ago"
}
],
"metricValues": [
{
"value": "16"
}
]
},
{
"dimensionValues": [
{
"value": "25-29 minutes ago"
}
],
"metricValues": [
{
"value": "14"
}
]
}
],
"rowCount": 2,
"kind": "analyticsData#runRealtimeReport"
}