環境

Google Apps Script
Google Analytics 4 Data API: v1beta

最終更新が2024-05-14のData API v1betaを利用しています。

はじめに

Google Analytics 4 (GA4) コンソールのレポートに平均エンゲージメント時間という項目があります。
それをGoogle Analytics 4 Data API + Google Apps Script (GAS) で取得する方法を検索しても出てこなかったため、記事に残します。

平均エンゲージメント時間という指標はない

runReportメソッドを利用して平均エンゲージメント時間のレポートを出力したいです。

利用できる指標（Metrics）とディメンション（Dimension）の一覧はこちら∶

「平均エンゲージメント時間」なので、"average"、"engagement"などのキーワードで検索をかけましたが、ヒットしませんでした。
唯一近かったのはこれ。

API Name	UI Name	Description
userEngagementDuration	User engagement	The total amount of time (in seconds) your website or app was in the foreground of users` devices.

でもこれは合計のエンゲージメント時間であって、平均値ではありません。

そもそも平均エンゲージメント時間はなに？

冒頭の画像にも少しヒントがありました。
以下のヘルプに平均エンゲージメント時間の算出方法が書いてあります。

Average engagement time = (The total length of time your website was in focus or your app was in the foreground across all sessions) / (The total number of active users)

平均エンゲージメント時間 =（すべてのセッションでウェブサイトがフォーカス状態にあったか、アプリがフォアグラウンド表示されていた合計時間）÷（アクティブユーザーの合計数）

つまり、平均時間を出すには、先ほどの合計エンゲージメント時間をアクティブユーザー数で割らないといけません。

平均エンゲージメント時間の取得方法

以上を踏まえて、全体の平均エンゲージメント時間とページパスとスクリーンクラス別の平均エンゲージメント時間を取得するソースコードを紹介します。
最後に解説を載せます。

全体の平均エンゲージメント時間

レポート＞ライフサイクル＞エンゲージメント＞概要の平均エンゲージメント時間を取得する方法です。

PROPERTY_IDは事前に定義したプロパティIDです。

function main() {
  const request = {
    metrics: [
      {
        name: 'averageEngagementTime',
        expression: "userEngagementDuration/activeUsers",
      },
    ],
    dateRanges: [
      {
        startDate: '2024-01-01',
        endDate: '2024-01-10',
      },
    ],
  };
  const response = AnalyticsData.Properties.runReport(request, 'properties/' + PROPERTY_ID);
  Logger.log(`response = ${response}`);
}

出力例

response = {"metadata":{"timeZone":"Asia/Tokyo","currencyCode":"USD"},"kind":"analyticsData#runReport","rows":[{"metricValues":[{"value":"1525"}]}],"metricHeaders":[{"type":"TYPE_FLOAT","name":"averageEngagementTime"}],"rowCount":1}

コンソール上では分秒表記となっていますが、レスポンスは秒単位です。
割り切れない場合もあります。

例）25分25秒

"value":"1525"

例）10分36秒

"value":"635.8796296296296"

ページパスとスクリーンクラス別の平均エンゲージメント時間

レポート＞ライフサイクル＞エンゲージメント＞ページとスクリーンのページパスとスクリーンクラス別の平均エンゲージメント時間を取得する方法です。

PROPERTY_IDは事前に定義したプロパティIDです。

function main() {
  const request = {
    dimensions: [
      {
        name: 'unifiedScreenClass',
      },
    ],
    metrics: [
      {
        name: 'averageEngagementTime',
        expression: "userEngagementDuration/activeUsers",
      },
    ],
    dateRanges: [
      {
        startDate: '2024-01-01',
        endDate: '2024-01-10',
      },
    ],
  };
  const response = AnalyticsData.Properties.runReport(request, 'properties/' + PROPERTY_ID);
  Logger.log(`response = ${response}`);
}

出力例

response = {"metadata":{"currencyCode":"USD","timeZone":"Asia/Tokyo"},"rows":[{"metricValues":[{"value":"715.88888888888891"}],"dimensionValues":[{"value":"/aaa"}]},{"metricValues":[{"value":"626.30769230769226"}],"dimensionValues":[{"value":"/ccc"}]},{"metricValues":[{"value":"493.75"}],"dimensionValues":[{"value":"/eee"}]},{"metricValues":[{"value":"153.77777777777777"}],"dimensionValues":[{"value":"/ddd"}]},{"metricValues":[{"value":"89.666666666666671"}],"dimensionValues":[{"value":"/bbb"}]}],"metricHeaders":[{"type":"TYPE_FLOAT","name":"averageEngagementTime"}],"kind":"analyticsData#runReport","dimensionHeaders":[{"name":"unifiedScreenClass"}],"rowCount":5}

こちらも同様、秒単位の小数が返却されます。

解説

今回の肝はここ。

metrics: [
  {
    name: 'averageEngagementTime',
    expression: "userEngagementDuration/activeUsers",
  },
],

`metrics.name`

通常、metricsのnameに取得したい指標を指定します。
例えば、イベント数を取得したい場合はこうです。

metrics: [
  {
    name: 'eventCount',
  },
],

Metricのリファレンスによると、expressionが指定された場合に限って、任意の文字列を指定できるとのことでした。

If expression is specified, name can be any string that you would like within the allowed character set. For example if expression is screenPageViews/sessions, you could call that metric's name = viewsPerSession.

今回は平均エンゲージメント時間ということで、averageEngagementTimeにしましたが、全く別の文字列でも構いません。
（正規表現の制限がありますので、リファレンスをご参照ください。）
ただ、expressionに指定したuserEngagementDurationをnameにも指定するとエラーが発生します。

GoogleJsonResponseException: API call to analyticsdata.properties.runReport failed with error: userEngagementDuration is used in both a metric's name and the same metric's expression. Please use a different name in metric.name.

`metrics.expression`

じゃあ、expressionはいつ使うかというと、今回のように事前に定義されていないが、指標同士の計算によって導き出せる時です。
平均エンゲージメント時間ならuserEngagementDuration/activeUsers。
ユーザーあたりのイベント数ならeventCount/totalUsers。
GA4を利用する際に割り算を使いたいケースが多いだと思いますが、数式なので割り算以外もできます。
例えば、新規ユーザーを除いたユーザー数はtotalUsers-newUsersです。

さいごに

GASで書きましたが、リクエストオブジェクトに関わる部分なので、
HTTPにもJavaにもPythonにも通じるではないでしょうか。
「平均エンゲージメント時間という指標がない💦💦」と思った方の手助けになりますように。