Building report requests

A report request describes what numbers you want and how to break them down. In TTMSFNCCloudGoogleAnalytics you express that through RequestData: a set of metric arrays (the quantities, such as sessions or active users) and dimension arrays (the breakdown, such as date, country, or user type). You populate the categories you need, leave the rest empty, then call RetrieveData. This chapter explains the request model, the metric and dimension categories, and the difference between core reports (over a date range) and realtime reports.

The request model

RequestData exposes one array property per metric or dimension category. Each array is a set of strongly-typed enum values, so the compiler keeps you to valid selections. To request something, assign an array of the relevant enum values; to drop a category from the next request, assign an empty array. Because RequestData keeps its previous selection between calls, reset the categories you are no longer interested in before reissuing a request — otherwise stale metrics and dimensions ride along.

Metrics and dimensions by category

The categories group the Analytics reporting surface into manageable sets. A representative selection:

Category	Metric property	Dimension property
User	`UserMetrics`	`UserDimension`
Session	`SessionMetrics`	`SessionDimension`
Traffic source	`TrafficMetrics`	`TrafficDimension`
Page tracking	`PageMetrics`	`PageDimension`
Event tracking	`EventTrackingMetrics`	`EventTrackingDimension`
Ecommerce	`ECommerceMetrics`	`ECommerceDimension`
Geography	—	`GeoDimension`
Time	—	`TimeDimension`
Realtime	`RealtimeMetrics`	`RealtimeUserDimension`, `RealtimeGeoDimension`, and other `Realtime*Dimension` properties

Additional categories cover internal search, site speed, app tracking, social activity and interactions, user timings, exceptions, advertising, audience, and channel grouping. See the API reference for the complete list of properties and the enum values each accepts.

Core reports over a date range

A core report aggregates historical data between two dates. Populate the metric and dimension categories you want, then call RetrieveData(AStartDate, AEndDate, AMaxResults). The date arguments accept Analytics expressions such as '7daysAgo' and 'today', or explicit 'YYYY-MM-DD' values; AMaxResults caps the number of rows returned.

procedure TForm1.RequestCoreReport;
var
  Metrics: TTMSFNCCloudGoogleAnalyticsSessionMetricsArray;
  TimeDims: TTMSFNCCloudGoogleAnalyticsTimeDimensionArray;
  UserDims: TTMSFNCCloudGoogleAnalyticsUserDimensionArray;
begin
  // Metrics are the numbers; dimensions are the breakdown. Here: sessions per day, per user type.
  SetLength(Metrics, 1);
  Metrics[0] := smSessions;

  SetLength(TimeDims, 1);
  TimeDims[0] := tdDate;

  SetLength(UserDims, 1);
  UserDims[0] := udUserType;

  FAnalytics.RequestData.SessionMetrics := Metrics;
  FAnalytics.RequestData.TimeDimension := TimeDims;
  FAnalytics.RequestData.UserDimension := UserDims;

  // Date range accepts API expressions such as '7daysAgo', 'today', or an explicit 'YYYY-MM-DD'.
  FAnalytics.RetrieveData('7daysAgo', 'today', 1000);
end;

Realtime reports

A realtime report returns activity happening right now and uses the dedicated Realtime* categories. The date range does not apply, so call RetrieveData with no arguments. Realtime reports pair well with a timer that re-issues the request on an interval to drive a live dashboard.

procedure TForm1.RequestRealtimeReport;
var
  Metrics: TTMSFNCCloudGoogleAnalyticsRealtimeMetricsArray;
  UserDims: TTMSFNCCloudGoogleAnalyticsRealtimeUserDimensionArray;
  GeoDims: TTMSFNCCloudGoogleAnalyticsRealtimeGeoDimensionArray;
begin
  SetLength(Metrics, 1);
  Metrics[0] := rtActiveUsers;

  SetLength(UserDims, 1);
  UserDims[0] := rudUserType;

  SetLength(GeoDims, 4);
  GeoDims[0] := rtgdCountry;
  GeoDims[1] := rtgdCity;
  GeoDims[2] := rtgdLatitude;
  GeoDims[3] := rtgdLongitude;

  FAnalytics.RequestData.RealtimeMetrics := Metrics;
  FAnalytics.RequestData.RealtimeUserDimension := UserDims;
  FAnalytics.RequestData.RealtimeGeoDimension := GeoDims;

  // Realtime reports ignore the date range, so the defaults are fine.
  FAnalytics.RetrieveData;
end;

Combining metrics with multiple dimensions

Real reports rarely use a single dimension. The core-report example above already combines a metric (smSessions) with two dimension categories — time (tdDate) and user (udUserType) — so each result row carries the session count for one date and user type. Add more dimension categories the same way: assign each category's array before calling RetrieveData, and the returned rows gain a column per requested metric and dimension, in request order. Keep an eye on the limits described in Reading results and handling errors — Analytics caps how many metrics and dimensions a single request may combine.