Google Analytics: GA4 Realtime Report, Create Custom
Google Analytics: GA4 Realtime Report, Create Custom
Creates a TSV report for any Metric from events in the last 30 mins (Google Analytics 4 property). One Realtime Dimension and one Realtime Metric can be specified arbitrarily. Extraction filter is also available. (exact match of the Dimension value).
Configs
  • U: Select HTTP_Authz Setting *
  • A1: Set Property-ID in Google Analytics *#{EL}
  • A2: Set Metric (eg “screenPageViews”) *#{EL}
  • A3: Set Dimension (eg “city”) *#{EL}
  • B3: To filter, Set Name of Filter Dimension (eg “country”)#{EL}
  • B4: To filter, Set Match List in CSV (eg. “Japan,United States”)#{EL}
  • C1: Select NUM that stores Total (update)
  • D1: Set Number of Ranking Size (Default “20”)#{EL}
  • D2: Select STRING that stores Ranking TSV (update)
Script (click to open)
// GraalJS Script (engine type: 2)

//////// START "main()" /////////////////////////////////////////////////////////////////

main();
function main(){ 

////// == Config Retrieving / 工程コンフィグの参照 ==
const strAuthzSetting     = configs.get      ( "AuthzConfU" );   /// REQUIRED
  engine.log( " AutomatedTask Config: Authz Setting: " + strAuthzSetting );
const strPropertyId       = configs.get      ( "StrConfA1" );    /// REQUIRED
  if( strPropertyId     === "" ){
    throw new Error( "\n AutomatedTask ConfigError:" +
                     " Config {A1: PropertyId} must be non-empty \n" );
  }
const strMetric           = configs.get      ( "StrConfA2" );    /// REQUIRED
  if( strMetric         === "" ){
    throw new Error( "\n AutomatedTask ConfigError:" +
                     " Config {A2: Metric} must be non-empty \n" );
  }
const strDimension        = configs.get      ( "StrConfA3" );    /// REQUIRED
  if( strDimension      === "" ){
    throw new Error( "\n AutomatedTask ConfigError:" +
                     " Config {A3: Dimension} must be non-empty \n" );
  }
let   strDimFilter        = configs.get      ( "StrConfB3" );    // NotRequired
let   strDimFilterValues  = configs.get      ( "StrConfB4" );    // NotRequired
  if( strDimFilter === "" && strDimFilterValues === "" ){
    engine.log( " AutomatedTask Config:" +
                " DimensionFilter not applied" );
  }else if( strDimFilter !== "" && strDimFilterValues !== "" ){
    engine.log( " AutomatedTask Config:" +
                " DimensionFilter: " + strDimFilter + " " + strDimFilterValues );
  }else if( strDimFilter === "" ){
    engine.log( " AutomatedTask ConfigWarning:" +
                " DimensionFilter ignored, Config {B3: DimensionName} required" );
  }else if( strDimFilterValues === "" ){
    engine.log( " AutomatedTask ConfigWarning:" +
                " DimensionFilter ignored, Config {B4: MatchList} required" );
  }else{
    throw new Error( "\n AutomatedTask Unexpected Error \n" );
  }
const numPocketTotal      = configs.getObject( "SelectConfC1" ); // NotRequired
let   strRankSize         = configs.get      ( "StrConfD1" );    // NotRequired
  if( strRankSize       === "" ){
      strRankSize         = "20";
  }
  let numRankSize         = strRankSize - 0;
const strPocketRankTsv    = configs.getObject( "SelectConfD2" ); // NotRequired



////// == Data Retrieving / ワークフローデータの参照 ==
// (Nothing. Retrieved via Expression Language in Config Retrieving)



////// == Calculating / 演算 ==

/// request1, prepare body
// Google Analytics > Reporting > Google Analytics Data API (GA4) > runRealtimeReport
// https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runRealtimeReport
let request1Obj = {};
    request1Obj.dimensions = [];
    request1Obj.dimensions[0] = {};
    request1Obj.dimensions[0].name = strDimension;
    request1Obj.metrics = [];
    request1Obj.metrics[0] = {};
    request1Obj.metrics[0].name = strMetric;
    request1Obj.limit = numRankSize;
    if( strDimFilter !== "" && strDimFilterValues !== "" ){
      request1Obj.dimensionFilter = {};
      request1Obj.dimensionFilter.filter = {};
      request1Obj.dimensionFilter.filter.fieldName = strDimFilter;
      request1Obj.dimensionFilter.filter.inListFilter = {};
      request1Obj.dimensionFilter.filter.inListFilter.caseSensitive = true;
      request1Obj.dimensionFilter.filter.inListFilter.values =
                                                      strDimFilterValues.split(",");
    }
    request1Obj.orderBys = [];
    request1Obj.orderBys[0] = {};
    request1Obj.orderBys[0].metric = {};
    request1Obj.orderBys[0].metric.metricName = strMetric;
    request1Obj.orderBys[0].desc = true;
    request1Obj.metricAggregations = [];
    request1Obj.metricAggregations[0] = "TOTAL";

/// request1, prepare header
let request1Uri = "https://analyticsdata.googleapis.com/v1beta/properties/" +
                  strPropertyId + ":runRealtimeReport";
let request1    = httpClient.begin(); // HttpRequestWrapper
    request1    = request1.authSetting( strAuthzSetting ); // with "Authorization: Bearer XX"
    // https://questetra.zendesk.com/hc/en-us/articles/360024574471-R2300#HttpRequestWrapper
    request1    = request1.body( JSON.stringify( request1Obj ), "application/json" );

/// request1, try
const response1     = request1.post( request1Uri ); // HttpResponseWrapper
engine.log( " AutomatedTask ApiRequest1 Start: " + request1Uri );
const response1Code = response1.getStatusCode() + "";
const response1Body = response1.getResponseAsString() + "";
engine.log( " AutomatedTask ApiResponse Status: " + response1Code );
if( response1Code !== "200"){
  throw new Error( "\n AutomatedTask UnexpectedResponseError: " +
                    response1Code + "\n" + response1Body + "\n" );
}

/// response1, parse
const response1Obj = JSON.parse( response1Body );

/* engine.log( response1Body ); // debug
{
  "dimensionHeaders": [
    {
      "name": "city"
    }
  ],
  "metricHeaders": [
    {
      "name": "screenPageViews",
      "type": "TYPE_INTEGER"
    }
  ],
  "rows": [
    {
      "dimensionValues": [
        {
          "value": "Chiyoda City"
        }
      ],
      "metricValues": [
        {
          "value": "3532"
        }
      ]
    },
    { ... },
    {
      "dimensionValues": [
        {
          "value": ""
        }
      ],
      "metricValues": [
        {
          "value": "378"
        }
      ]
    },
    { ... },
    {
      "dimensionValues": [
        {
          "value": "(not set)"
        }
      ],
      "metricValues": [
        {
          "value": "115"
        }
      ]
    }
  ],
  "totals": [
    {
      "dimensionValues": [
        {
          "value": "RESERVED_TOTAL"
        }
      ],
      "metricValues": [
        {
          "value": "12221"
        }
      ]
    }
  ],
  "rowCount": 94,
  "kind": "analyticsData#runRealtimeReport"
}
*/


let strRankTsv = "";
let numTotal = 0;

if( response1Obj.hasOwnProperty("rows") ){
  /// Create TSV by rows
  strRankTsv += strMetric + "\t" + strDimension + "\n";
  for( let i = 0; i < response1Obj.rows.length; i++ ){
    strRankTsv += response1Obj.rows[i].metricValues[0].value + "\t";
    strRankTsv += response1Obj.rows[i].dimensionValues[0].value;
    if( i !== response1Obj.rows.length - 1 ){
      strRankTsv += "\n";
    }
  }

  /// Get TOTAL
  numTotal = response1Obj.totals[0].metricValues[0].value;
}


////// == Data Updating / ワークフローデータへの代入 ==
if( numPocketTotal !== null ){
  engine.setData( numPocketTotal, new java.math.BigDecimal( numTotal ) );
}
if( strPocketRankTsv !== null ){
  engine.setData( strPocketRankTsv, strRankTsv );
}


} //////// END "main()" /////////////////////////////////////////////////////////////////



/*
Notes:
- Requests to the property (data storage) of Google Analytics when the process reaches the Automated Step.
    - You can automate the extraction work of Google Analytics Data. Analytics Reports
- Extracts via "Google Analytics Data API" for GA4 properties.
    - Data API can only be used to access GA4 properties and is not compatible with Universal Analytics.
        - As of 202204, it is a "Beta version", although "no breaking changes are expected".
        - https://developers.google.com/analytics/devguides/reporting/data/v1
    - Make sure that the Mesurement ID to be extracted is `G-XXXXXXXXXX` (GA4 property).
        - GA4 Properties is the latest version of Google Analytics released in October 2020.
        - The Mesurement ID of the UA property is `UA-XXXXXXXX-X`.
        - https://support.google.com/analytics/answer/10089681
    - The following four values can be specified as the Realtime Metric. (As of 202206)
        - "`activeUsers`": Active users (the number of distinct users who visited your site or app).
        - "`conversions`": The count of conversion events.
        - "`eventCount`": The count of events.
        - "`screenPageViews`": Views
        - Official Document: "Realtime Dimensions & Metrics"
            - https://developers.google.com/analytics/devguides/reporting/data/v1/realtime-api-schema
    - The following 16 values can be specified for the Realtime dimension. (as of 202206)
        - "`appVersion`": App version (versionName (Android) or short bundle version (iOS))
        - "`audienceId`": Audience ID
        - "`audienceName`": The given name of an Audience.
        - "`city`": The city from which the user activity originated.
        - "`cityId`": The geographic ID of the city from which the user activity originated, derived from their IP address.
        - "`country`": The country from which the user activity originated.
        - "`countryId`": The geographic ID of the country from which the user activity originated. (ISO 3166-1 alpha-2 standard)
        - "`deviceCategory`": The type of device: Desktop, Tablet, or Mobile.
        - "`eventName`": The name of the event.
        - "`minutesAgo`": The number of minutes ago that an event was collected. 00 is the current minute.
        - "`platform`": The platform on which your app or website ran; for example, web, iOS, or Android.
        - "`streamId`": The numeric data stream identifier for your app or website.
        - "`streamName`": The data stream name for your app or website.
        - "`unifiedScreenName`": The page title (web) or screen name (app) on which the even
        - {User-scoped Custom Dimension}
            - Event-scoped custom dimensions are not currently supported in the Realtime API.
- Refer to the official document for "API Name" (latest information) of metrics and dimensions.
    - Official Document: "Realtime Dimensions & Metrics"
        - https://developers.google.com/analytics/devguides/reporting/data/v1/realtime-api-schema
    - Examples
        - e.g., Number of views (`screenPageViews`) for each device (`deviceCategory`)
        - e.g., Number of conversions (`conversions`) for each country (`country`)
        - e.g., Number of active users (`activeUsers`) for each city (`city`)

APPENDIX
- To place this "Add-on Automated Step" on the design screen of the workflow diagram
    - Import Addon-XML (definition file of this automated step) to Workflow App in advance.
    - The system admins can also make it available in all Workflow Apps. (App-shared Add-on)
    - Manual M415: Adding an Auto-Step to be Used in a Business Process Definition
        - https://questetra.zendesk.com/hc/en-us/articles/360002247792-M415
- To activate the Workflow App including this "Add-on automated Step"
    - Authorize API communications by an authorized user in advance.
    - Enable "Google Analytics Data API" on the Google Cloud Platform
        - APIs and Services: `Google Analytics Data API`
            - https://console.cloud.google.com/project/_/apis/library
        - OFFICIAL DOCUMENT
            - https://cloud.google.com/service-usage/docs/enable-disable
    - Create an "OAuth2.0 client ID" on the Google Cloud Platform
        - Creating credentials:
            - `OAuth Client ID`
        - Application type:
            - `Web application`
        - Name:
            - `Questetra to GA4`
        - Authorized JavaScript origins:
            - `https://your-subdomain.questetra.net`
        - Authorized redirect URI:
            - `https://s.questetra.net/oauth2callback`
        - OFFICIAL DOCUMENT
            - https://cloud.google.com/endpoints/docs/frameworks/java/javascript-client
    - Set "HTTP authentication (OAuth2)" on the Questetra Workflow-App
        - Name:
            - `Questetra-GA4`
        - Authorization Endpoint URL:
            - `https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&prompt=consent`
        - Token Endpoint URL:
            - `https://oauth2.googleapis.com/token`
        - Scope:
            - `https://www.googleapis.com/auth/analytics.readonly`
        - Client ID / Consumer Secret:
            - (see above "OAuth 2.0 client ID")
        - OFFICIAL DOCUMENT
            - https://developers.google.com/identity/protocols/oauth2/web-server#httprest
- In this Add-on Automated Step, "Data API (GA4)" is used to acquire data from Google Analytics.
    - Not "Reporting API V4".
    - Not "Core Reporting API V3".
    - Requests with a response longer than 30 seconds may result in an error.
- Can also filter the ranking list by Dimension Filter (inListFilter).
    - Only data which dimension values​exactly match any of the values will be extracted. (Case Sensitive)
        - `country`: `Canada,Japan`


Notes-ja:
- 案件が自動工程に到達した際、Google アナリティクスのプロパティ(データ格納庫)にリクエストします。
    - GoogleアナリティクスDataの抽出業務を自動化できます。 AnalyticsReports
- GA4プロパティ用の "Google Analytics Data API" を経由して抽出します。
    - GA4プロパティへのアクセスにのみ使用でき、UniversalAnalyticsとは互換性がありません。
        - また、202204時点において、「重大な変更は予想されていない」ものの、"Beta version" です。
        - https://developers.google.com/analytics/devguides/reporting/data/v1
    - GA4の計測IDは `G-XXXXXXXXXX` の書式になります。
        - GA4プロパティは、2020年10月にリリースされた最新版の Google アナリティクスプロパティです。
        - UAプロパティの計測IDは `UA-XXXXXXXX-X` となります。
        - https://support.google.com/analytics/answer/10089681
    - Realtime 指標としては指定できる値は以下の4つです。(202206現在)
        - "`activeUsers`": アクティブユーザー数 (サイトやアプリの訪問者数)
        - "`conversions`": コンバージョンイベントの数
        - "`eventCount`": イベントの数
        - "`screenPageViews`": 表示回数
    - Realtime ディメンションとしては指定できる値は以下の16種です。(202206現在)
        - "`appVersion`": Android の versionName もしくは iOS の Short Bundle Version
        - "`audienceId`": オーディエンスID
        - "`audienceName`": オーディエンス名
        - "`city`": ユーザーアクティビティが発生した都市の名前
        - "`cityId`": ユーザーアクティビティが発生した都市ID(IPアドレスから)
        - "`country`": ユーザーアクティビティが発生した国地域の名前
        - "`countryId`": ユーザーアクティビティが発生した国コード(ISO 3166-1 alpha-2 standard)
        - "`deviceCategory`": デバイス(Desktop, Tablet, or Mobile)
        - "`eventName`": イベント名
        - "`minutesAgo`": イベントの収集時刻(分)[00は現在]
        - "`platform`": プラットフォーム(Web、iOS、Android)
        - "`streamId`": ストリームID
        - "`streamName`": ストリーム名
        - "`unifiedScreenName`": ページタイトル(ウェブ)またはスクリーンネーム(アプリ)
        - (および User-scoped なカスタムディメンション)
            - Event-scoped なカスタムディメンションはサポートされていません。(202206現在)
- 指標やディメンジョンの "API Name"(最新情報)は、公式マニュアルを参照します。
    - 公式マニュアル: "Realtime Dimensions & Metrics"
        - https://developers.google.com/analytics/devguides/reporting/data/v1/realtime-api-schema
    - 組み合わせサンプル
        - 例. デバイス (`deviceCategory`) ごとの表示回数 (`screenPageViews`)
        - 例. 国地域 (`country`) ごとのコンバージョン数 (`conversions`)
        - 例. 都市 (`city`) ごとのアクティブユーザー数 (`activeUsers`)

APPENDIX-ja
- この[アドオン自動工程]を、ワークフロー図の設計画面で配置(利用)できるようにするには
    - 予めアドオンXML(この自動工程の定義ファイル)を、[Workflowアプリ]に追加(アドオン)します。
    - システム管理者は、Workflow基盤の全アプリで配置できるようにすることも可能です。(アプリ共有アドオン)
    - マニュアル M415: 業務プロセス定義で利用可能な自動工程を追加する (Professional edition)
        - https://questetra.zendesk.com/hc/ja/articles/360002247792-M415
- この[アドオン自動工程]を含むワークフローアプリを、運用できるようにするには
    - あらかじめ、権限ユーザによる認可(API通信の許可)が必要です。
    - Google Cloud Platform 側で『Google Analytics Data API』を有効化する
        - APIとサービスの有効化: `Google Analytics Data API`
            - https://console.cloud.google.com/project/_/apis/library
        - 公式マニュアル: サービスの有効化と無効化
            - https://cloud.google.com/service-usage/docs/enable-disable
    - Google Cloud Platform 側で『OAuth2.0クライアントID』を作成する
        - 認証情報の作成:
            - `OAuthクライアントID`
        - アプリケーションの種類:
            - `ウェブ アプリケーション`
        - 名前:
            - `Questetra to GA4`
        - 承認済みのJavaScript生成元:
            - `https://your-subdomain.questetra.net`
        - 承認済みのリダイレクト URI:
            - `https://s.questetra.net/oauth2callback`
        - 公式マニュアル:  https://cloud.google.com/endpoints/docs/frameworks/java/javascript-client
    - Questetra 側で『"HTTP認証"(OAuth2)』を設定する
        - 名前:
            - `Questetra-GA4`
        - 認可エンドポイントURL:
            - `https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&prompt=consent`
        - トークンエンドポイントURL:
            - `https://oauth2.googleapis.com/token`
        - スコープ:
            - `https://www.googleapis.com/auth/analytics.readonly`
        - クライアントID / クライアントシークレット:
            - ( see above "OAuth 2.0 client ID" )
        - 公式マニュアル: https://developers.google.com/identity/protocols/oauth2/web-server#httprest
- この[アドオン自動工程]では、Googleアナリティクスからのデータ取得に "Data API" が利用されています。
    - "Reporting API V4" ではありません。
    - "Core Reporting API V3" ではありません。
    - レスポンスが30秒を超えるようなリクエストは、エラーになる場合があります。
- 完全一致リスト(inListFilter)を設定すれば、ランキングリストの絞り込みが可能です。
    - ディメンションの値がいずれかの値と完全一致するデータだけが抽出されます。(Case Sensitive)
        - `country`: `Canada,Japan`
*/

Download

2022-06-12 (C) Questetra, Inc. (MIT License)
https://support.questetra.com/addons/google-analytics-ga4-realtime-report-create-custom-2022/
The Addon-import feature is available with Professional edition.
Freely modifiable JavaScript (ECMAScript) code. No warranty of any kind.

Notes

  • Requests to the property (data storage) of Google Analytics when the process reaches the Automated Step.
    • You can automate the extraction work of Google Analytics Data. Analytics Reports
  • Extracts via “Google Analytics Data API” for GA4 properties.
    • Data API can only be used to access GA4 properties and is not compatible with Universal Analytics.
    • Make sure that the Mesurement ID to be extracted is G-XXXXXXXXXX (GA4 property).
    • The following four values can be specified as the Realtime Metric. (As of 202206)
    • The following 16 values can be specified for the Realtime dimension. (as of 202206)
      • appVersion“: App version (versionName (Android) or short bundle version (iOS))
      • audienceId“: Audience ID
      • audienceName“: The given name of an Audience.
      • city“: The city from which the user activity originated.
      • cityId“: The geographic ID of the city from which the user activity originated, derived from their IP address.
      • country“: The country from which the user activity originated.
      • countryId“: The geographic ID of the country from which the user activity originated. (ISO 3166-1 alpha-2 standard)
      • deviceCategory“: The type of device: Desktop, Tablet, or Mobile.
      • eventName“: The name of the event.
      • minutesAgo“: The number of minutes ago that an event was collected. 00 is the current minute.
      • platform“: The platform on which your app or website ran; for example, web, iOS, or Android.
      • streamId“: The numeric data stream identifier for your app or website.
      • streamName“: The data stream name for your app or website.
      • unifiedScreenName“: The page title (web) or screen name (app) on which the even
      • {User-scoped Custom Dimension}
        • Event-scoped custom dimensions are not currently supported in the Realtime API.
  • Refer to the official document for “API Name” (latest information) of metrics and dimensions.

Capture

Creates a TSV report for any Metric from events in the last 30 mins (Google Analytics 4 property). One Realtime Dimension and one Realtime Metric can be specified arbitrarily. Extraction filter is also available. (exact match of the Dimension value).

Appendix

See also

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: