此页面由 Cloud Translation API 翻译。

工作区-google-analytics

如果您要构建一款可离线运行的应用，了解用户在没有网络连接时如何与您的应用互动，对于优化这种体验至关重要。

Google Analytics（分析）等分析服务提供商需要通过网络连接将数据发送到他们的服务器，这意味着，如果无法连接，这些请求将会失败，且您的分析报告中将缺失这些互动。它们好像永远都没有发生。

Workbox Google Analytics 利用 Service Worker 检测失败请求的功能，为 Google Analytics（分析）用户解决了这一问题。

Google Analytics（分析）通过向 Measurement Protocol 发出的 HTTP 请求接收所有数据，这意味着 Service Worker 脚本可��添加一个提取处理程序来检测发送到 Measurement Protocol 的失败请求。它可以将这些请求存储在 IndexedDB 中，然后在连接恢复后重试。

Workbox Google Analytics（分析）正是这么做的。此外，它还添加了提取处理程序来缓存 analytics.js 和 gtag.js 脚本，使它们也可以离线运行。最后，在重试失败的请求时，Workbox Google Analytics 还会自动设置（或更新）请求载荷中的 qt，以确保 Google Analytics（分析）中的时间戳反映原始用户互动的时间。

启用 Workbox Google Analytics（分析）

如需启用 Workbox Google Analytics（分析），请调用 initialize() 方法：

import * as googleAnalytics from 'workbox-google-analytics';

googleAnalytics.initialize();

这是将失败的请求排入队列并重试向 Google Analytics（分析）发送的唯一代码，也是让 Google Analytics（分析）离线工作的最简单方法。

但是，如果仅使用上述代码，则无法区分重试的请求与第一次尝试成功的请求。这意味着，您将会收到来自线下用户的所有互动数据，但无法得知用户处于离线状态时发生了哪些互动。

要解决此问题，您可以使用下述配置选项之一来修改或注释在重试的请求中发送的数据。

修改要发送的数据

如果您希望能够区分重试的请求与未重试的请求，可以指定 parameterOverrides 或 hitFilter 配置选项。

利用这些选项，您可以修改在重试的请求中发送的 Measurement Protocol 参数。如果您要为每个重试的请求的特定参数设置相同的值，则应使用 parameterOverrides 选项。如果您需要在运行时计算特定参数的值，或者从另一个参数的值衍生出某个参数的值，则应使用 hitFilter 选项。

以下示例展示了如何使用这两个选项。

示例

使用自定义维度跟踪线上和线下互动情况

Google Analytics（分析）没有针对线上和线下互动情况的内置维度。不过，您可以使用名为自定义维度的功能来专门出于此目的创建自己的维度。

如需在 Workbox Google Analytics 中使用自定义维度跟踪 Service Worker 重放的请求，请按以下步骤操作：

在 Google Analytics（分析）中创建新的自定义维度。为其命名一个类似“网络状态”的名称，并将其范围设置为“命中”（因为任何互动都可以是离线互动）。
记下为新创建的维度指定的索引，并将其作为参数名称传递给 Workbox Google Analytics（分析）代码中的 parameterOverrides 配置选项。

例如，如果这是您的第一个自定义维度，其索引将为 1，参数名称为 cd1（如果索引为 8，则其名称将为 cd8）：
```
import * as googleAnalytics from 'workbox-google-analytics';

googleAnalytics.initialize({
  parameterOverrides: {
    cd1: 'offline',
  },
});
```
（可选）由于 parameterOverrides 中的值仅应用于重试（“离线”）请求，因此您可能还需要为所有其他请求设置默认值“online”。虽然这不是绝对必要的，但这样做可以让您的报告更易于阅读。

例如，如果您使用默认的 analytics.js 跟踪代码段安装 Google Analytics（分析），则可以添加 ga('set', 'dimension1', 'online') 行，以便针对 Service Worker 未重放的所有请求使用默认值 'online' 作为“网络状态”自定义维度。
```
<script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-XXXXX-Y', 'auto');

  // Set default value of custom dimension 1 to 'online'
  ga('set', 'dimension1', 'online');

  ga('send', 'pageview');
</script>
```

注意：workbox-google-analytics 使用 Measurement Protocol 参数名称，这与 analytics.js 使用的字段��称不同。例如，对于自定义维度，Measurement Protocol 使用 cdXX（例如 cd1），而 analytics.js 使用 dimensionXX（例如 dimension1）。

使用自定义指标跟踪队列中所用的时间请求

如果您想知道从发生离线互动到恢复连接再到成功重试请求之间��过了多长时间，可以使用自定义指标和 hitFilter 配置选项进行跟踪：

在 Google Analytics（分析）中创建新的自定义指标。为其命名一个类似“离线队列时间”的名称，将其范围设置为“命中”，并将其格式设置类型设置为“时间”（以秒为单位）。

使用 hitFilter 选项获取 qt 参数的值，并将其除以 1000（将其转换为秒）。然后，将该值设置为包含新建指标索引的参数。如果这是您的第一个自定义指标，参数名称将为 'cm1'：

import * as googleAnalytics from 'workbox-google-analytics';

googleAnalytics.initialize({
  hitFilter: (params) => {
    const queueTimeInSeconds = Math.round(params.get('qt') / 1000);
    params.set('cm1', queueTimeInSeconds);
  },
});

测试 Workbox Google Analytics（分析）

由于 Workbox Google Analytics（分析）使用后台同步重放事件，因此测试可能不太直观。如需了解详情，请参阅测试 Workbox 后台同步。

类型

GoogleAnalyticsInitializeOptions

属性

cacheName

字符串（可选）
parameterOverrides

对象（可选）
hitFilter

void 可选属性

hitFilter 函数如下所示：
```
(params: URLSearchParams) => {...}
```
- params
  
  URLSearchParams

方法

initialize()

workbox-google-analytics.initialize(
  options?: GoogleAnalyticsInitializeOptions,
)

参数

选项

GoogleAnalyticsInitializeOptions 可选