README

此插件将 WordPress 与 AWS Pinpoint 集成，并提供一个可扩展的追踪器。

它还自动与 WP Consent Level API 插件 或 Human Made 维护的 仅客户端版本 集成。至少必须同意 statistics-anonymous 类别才能进行任何追踪，并且需要 statistics 才能追踪个人可识别信息。

用法

在 JavaScript 中

安装插件后，将排队一个分析追踪脚本，它提供了一些客户端函数，您可以使用这些函数

API

Altis.Analytics.onReady( callback <function> )

使用此函数确保分析已加载后再调用 registerAttribute() 或 record()。

Altis.Analytics.updateEndpoint( data <object> )

更新与当前用户关联的数据。使用此功能提供更新的自定义用户属性和指标、用户 ID 和人口统计数据。

重要：如果与 WP Consent API 一起使用，则移除此函数下 User 属性传递的所有数据。您只能在 User.UserId 和 User.UserAttributes 属性下存储个人可识别信息。下文概述的所有其他端点数据应仅用于匿名人口统计数据。

Altis.Analytics.getEndpoint()

返回当前端点数据对象。

Altis.Analytics.record( eventName <string> [, data <object> [, endpoint <object>]] )

记录一个事件。传入的数据应是一个对象，其中包含 attributes 属性和/或 metrics 属性

{
  attributes: {
    name: 'value', // <string>
    // ...
  },
  metrics: {
    name: 1 // <number>
    // ...
  },
}

可选的第三个参数允许您同时更新端点数据，就像调用 Altis.Analytics.updateEndpoint() 一样。这些属性、指标和端点数据可以稍后通过 Elasticsearch 查询。

Altis.Analytics.updateAudiences()

同步页面会话关联的当前受众。您无需手动调用此函数，但每次调用 updateEndpoint()、registerAttribute() 或 registerMetric() 时都会调用此函数。您可以通过挂钩到 updateAudiences 事件来响应此数据的变化。

Altis.Analytics.getAudiences()

检索当前页面会话的受众 ID 数组。

添加全局属性和指标

Altis.Analytics.registerAttribute( name <string>, value <string | callback> )

有时您可能想记录页面上所有事件的动态属性值。此 registerAttribute() 函数允许您这样做。值必须是单个字符串。如果传递了函数作为值，则将在事件记录时评估该值。支持作为返回值的承诺。

Altis.Analytics.registerMetric( name <string>, value <number | callback> )

类似于上面的 registerAttribute()，但用于数字。

事件

Altis.Analytics.on( event <string>, callback <callback> ) : EventListener

附加并返回一个事件监听器。可用的事件及其回调参数如下

• updateEndpoint
  每次当前端点数据更新时都会调用。回调接收端点对象。
  

  Altis.Analytics.on( 'updateEndpoint', function ( endpoint ) {
    console.log( endpoint.Demographic ); // { Platform: 'Mac OS', .... }
  } );
  

• record：每次记录事件时都会调用。回调接收 pinpoint 事件对象。
  

  Altis.Analytics.on( 'record', function ( event ) {
    console.log( event.Attributes, event.event_type ); // { referer: '', ... }, 'pageView'
  } );
  

• updateAudiences
  每次更新受众时都会调用。回调接收受众 ID 数组。
  

  Altis.Analytics.on( 'updateAudiences', function ( audiences ) {
    console.log( audiences ); // [ 1, 2, 3, ... ]
  } );
  

Altis.Analytics.off( 事件监听器 <EventListener> )

移除由 Altis.Analytics.on() 返回的事件监听器。

常量

ALTIS_ANALYTICS_ELASTICSEARCH_URL

允许您直接定义Elasticsearch服务器URL。

ALTIS_ANALYTICS_LOG_QUERIES

将其定义为true以启用将查询记录到错误日志中。

ALTIS_ANALYTICS_FALLBACK_CAPS

默认情况下，Altis Analytics将授予任何可以编辑页面的角色编辑受众的能力。您可以通过显式地从角色中移除这些能力（即 'edit_audiences' => false），但在某些情况下，您可能希望完全移除此回退。

将其定义为false以禁用能力回退到页面能力。

ALTIS_ANALYTICS_PINPOINT_BUCKET_ARN

如果您将Pinpoint Kinesis Firehose设置为将数据备份到S3，定义此常量允许定期从备份中清理数据。

ALTIS_ANALYTICS_PINPOINT_BUCKET_REGION

Kinsesis Firehose S3存储桶的分区（如果已配置）。

过滤器

该插件提供了一些钩子，让您控制与事件一起记录的默认端点数据和属性。

altis.analytics.consent_enabled <bool>

如果已安装并激活了WP Consent API插件或其变体，并且通过检查常量 WP_CONSENT_API_URL 是否定义，则默认为true。

altis.analytics.data.endpoint <array>

允许您提供服务器端数据，用于更新与访客相关的端点，并带有自定义属性和人口统计数据。主要用于为登录会话提供额外数据，如基于IP的位置数据。

altis.analytics.data.attributes <array>

允许您提供服务器端数据，用于记录页面上的所有事件。如果您需要根据页面上下文查询记录，则非常有用。

altis.analytics.data.metrics <array>

类似于 altis.analytics.data.attributes 过滤器，但允许您根据服务器端数据传递度量。

altis.analytics.data <array>

过滤传递给客户端的整个数组。

altis.analytics.elasticsearch.url <string>

过滤Elasticsearch服务器URL。

altis.analytics.noop <bool>

从此过滤器返回 false 将阻止任何事件或更新的端点数据被发送到Pinpoint。内置用法是防止在页面预览中记录事件。

altis.analytics.max_index_age <int>

过滤保留实时统计数据的最长天数。默认天数是90天，之后数据被删除。这对于简化用户的隐私非常重要。

在需要保留信息更长时间的情况下，如页面查看次数，可以在数据库中计算、更新和存储洞察力和汇总分析数据。

altis.analytics.max_s3_backup_age <int>

过滤保留备份数据的最长天数。默认天数是90天，按照AWS Pinpoint的规则，之后数据被删除。这对于简化用户的隐私非常重要。此值没有上限，但是您应该确保在用户选择跟踪时向用户解释任何长期数据存储。

altis.analytics.exclude_bots <bool>

默认为true，但可以关闭以允许跟踪可以运行JavaScript的机器人，请注意这将影响您的数据。

您可以通过检查 attributes.isBot 值是否存在来检查记录的事件是否由机器人创建。

altis.analytics.elasticsearch.timeout <int> 过滤从Elasticsearch获取响应的秒数。默认值为 20 秒。最小值为 5 秒，最大值为 30 秒。

函数

Altis\Analytics\Utils\query( array $query, array $params = [] ) : array

使用在 $query 中提供的Elasticsearch Query DSL查询分析数据。$params 将作为查询字符串参数添加到Elasticsearch请求URL中。

Altis\Analytics\Utils\get_elasticsearch_url() : string

获取Elasticsearch服务器URL。

Altis\Analytics\Utils\milliseconds() : 整数

获取自Unix纪元以来的当前时间的毫秒数。

Altis\Analytics\Utils\merge_aggregations( array $current, array $new, string $bucket_type = '' ) : array

合并Elasticsearch查询返回的聚合工具函数。这是必要的，以保持您的分析数据的存储，因为Elasticsearch索引可能会被旋转或丢失。

查询数据

可以从Elasticsearch查询数据，提供了一种强大的工具，用于过滤和聚合记录。如果您使用Altis，请求将自动签名。

建议使用Altis\Analytics\Utils\query()函数。

事件记录的解剖结构

用户会话覆盖了从打开网站到关闭网站之间的所有事件记录。对于记录的每个事件，根据范围记录以下数据。

• event_type：记录的事件类型，例如pageView、click、_session.start或_session.stop。
• event_timestamp：在网站上记录事件的时间戳（毫秒）。
• 属性
  • date：ISO-8601标准的日期字符串。
  • session：跨所有页面视图的唯一ID。
  • pageSession：单个页面视图的唯一ID。
  • url：当前页面URL。
  • hash：当前URL哈希。
  • referer：页面来源。
  • network：当前网络的主要URL。
  • networkId：当前网络的ID。
  • blog：当前网站URL。
  • blogId：当前博客ID。
  • qv_utm_campaign：如果设置，则从查询字符串提供的Urchin Tracker活动。
  • qv_utm_source：如果设置，则从查询字符串提供的Urchin Tracker来源。
  • qv_utm_medium：如果设置，则从查询字符串提供的Urchin Tracker媒体。
  • qv_*：任何查询字符串参数将记录带有前缀qv_。
  • 通过altis.analytics.data.attributes过滤器添加的任何属性。
  • 通过Altis.Analytics.registerAttribute()添加的任何属性或传递给Altis.Analytics.record()的任何属性。
• 度量
  • scrollDepthMax：页面迄今为止的最大滚动深度。1-100之间的百分比值。
  • scrollDepthNow：事件发生时的滚动深度。1-100之间的百分比值。
  • elapsed：自页面视图开始以来经过的毫秒数。
  • day：星期几，1代表星期天，7代表星期六。
  • hour：一天中的小时（24小时制）。
  • month：一年中的月份。
  • 通过Altis.Analytics.registerMetric()添加的任何度量或传递给Altis.Analytics.record()的任何度量。
• 端点
  • Id：端点的唯一UUID。
  • Address：可选的推送通知目标，如电子邮件地址或电话号码。
  • OptOut：此访客已退出的推送通知频道。默认为"ALL"。
  • 属性
    • 与此端点关联的任何自定义属性。
  • 度量
    • sessions：此端点的单独浏览会话数。
    • pageViews：此端点的总页面视图数。
    • 与此端点关联的任何自定义度量。
  • 人口统计信息
    • AppVersion：当前应用程序版本，可以通过altis.analytics.data过滤器提供。
    • Locale：端点的区域代码，从浏览器中派生。
    • Make：当前浏览器/浏览器引擎的制造商，例如"blink"。
    • Model：当前浏览器的型号，例如"Chrome"。
    • ModelVersion：浏览器版本。
    • Platform：设备操作系统。
    • PlatformVersion：操作系统版本。
  • 位置
    • Country：如果已知或可用，则为此端点的国家。
    • City：如果已知或可用，则为此端点的城市。
  • 用户
    • 用户属性
      • 如果已知，则与用户关联的任何自定义属性。
    • UserId：与您的应用程序中的用户关联的ID。对于在不同设备之间链接端点很有用。
• 会话
  • session_id：在子会话期间保持，由页面可见性变化触发。与 _session.start 和 _session.stop 事件一起记录。
  • start_timestamp：子会话开始的时间（毫秒）。与 _session.start 事件一起记录。
  • stop_timestamp：子会话结束的时间（毫秒）。与 _session.stop 事件一起记录。
  • duration：子会话的持续时间（毫秒）。与 _session.stop 事件一起记录。

页面时间统计示例

<?php
$result = Altis\Analytics\Utils\query( [
  // Don't return any hits to keep the response size small.
  'size' => 0,
  // Restrict the results to a single page we're interested in.
  'query' => [
    'bool' => [
      'filter' => [
        [ 'term' => [ 'attributes.url.keyword' => 'https://example.com/page' ] ]
      ]
    ]
  ],
  // Aggregate data sets
  'aggs' => [
    'sessions' => [
      // Create buckets by page session ID so all records in each bucket belong
      // to a single user and page session.
      'terms' => [
        'field' => 'attributes.pageSession.keyword',
        // Use data from the top 100 unique page sessions.
        // By default terms aggregations return the top 10 hits.
        'size' => 100
      ],
      // Sub aggregations.
      'aggs' => [
        // Get the time on page by summing all session.duration values for the page session.
        'time_on_page' => [
          'sum' => [ 'field' => 'session.duration' ]
        ]
      ]
    ],
    // Create a stats aggregation for all the time on page values found above.
    'stats' => [
      'stats_bucket' => [
        'buckets_path' => 'sessions>time_in_page'
      ]
    ]
  ],
  // Order by latest events.
  'order' => [ 'event_timestamp' => 'desc' ]
] );

输出将类似于以下内容

{
  "took": 15,
  "timed_out": false,
  "_shards": {
    "total": 5,
    "successful": 5,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": 329,
    "max_score": 0
  },
  "aggregations": {
    "sessions": {
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 0,
      "buckets": [
        { "...": "..." }
      ]
    },
    "stats": {
      "count": 92,
      "min": 0,
      "max": 4963998,
      "avg": 78251.14130434782,
      "sum": 7199105
    }
  }
}

您可以使用 filter_path 查询参数进一步减小返回响应的大小。例如，如果我们只对统计聚合感兴趣，可以设置 filter_path=-aggregations.sessions 以从响应中删除它。

受众

受众是基于与他们的分析数据相关的条件定义的用户类别。

受众允许创建条件以缩小事件查询或端点，但也可以用于确定客户端的影响。

映射事件数据

要启用在受众编辑器中使用任何事件记录数据，需要使用 Altis\Analytics\Audiences\register_field() 函数将其映射到可读的标签。

use function Altis\Analytics\Audiences\register_field;

add_action( 'init', function () {
  register_field(
    'endpoint.Location.Country', // The Elasticsearch field to query.
    __( 'Country' ), // A label for the field.
    __( 'The visitor country.' ) // Optional description for the field.
    [ // Optional field arguments
      'options' => '\\Altis\\Analytics\\Utils\\get_countries', // A callback to provide prepopulated list of options.
      'disable_free_text' => false, // Whether to allow free text to be used or to restrict to available options.
    ]
  );
} );

在上面的示例中，第一个参数 endpoint.Location.Country 代表要查询的事件记录字段。其他示例包括 attributes.qv_utm_campaign 或 endpoint.User.UserAttributes.custom 等。

第二个参数是受众字段的可读标签，第三个是在字段 UI 下方显示的可读描述。

第四个参数是可选的参数数组，可以包括

• options 是一个回调，返回一个有效选项列表，该列表将补充该字段的现有数据。
• disable_free_text 是一个布尔值，用于允许/限制用户设置自定义字符串而不是从列表中选择。

所需基础设施

使用此插件需要特定的基础设施设置

• AWS Pinpoint 项目
  • 配置为指向以下 Kinesis Firehose 的事件流
  • 关联的 Cognito 身份池 ID
• AWS Kinesis Firehose
  • 备份到 AWS S3 存储桶
  • 将数据发送到名为 analytics 的 AWS Elasticsearch 实例的索引

构建过程

要从直接克隆使用插件，您需要运行构建步骤

npm install
npm run build

要使用开发服务器，请执行以下操作

npm run start

配置

您必须定义以下常量

define( 'ALTIS_ANALYTICS_PINPOINT_ID', '...' );
define( 'ALTIS_ANALYTICS_PINPOINT_REGION', '...' );
define( 'ALTIS_ANALYTICS_COGNITO_ID', '...' );
define( 'ALTIS_ANALYTICS_COGNITO_REGION', '...' );

自定义端点

如果您想在本地上进行测试，可以使用以下常量来覆盖服务端点

define( 'ALTIS_ANALYTICS_PINPOINT_ENDPOINT', 'your-pinpoint-endpoint.com' );
define( 'ALTIS_ANALYTICS_COGNITO_ENDPOINT', 'your-cognito-endpoint.com' );

humanmade/local-pinpoint 和 humanmade/local-cognito docker 镜像提供了 AWS Pinpoint API 的本地版本，仅限于必要的功能。

docker pull humanmade/local-pinpoint
docker run -d \
  --name local-pinpoint \
  -e ELASTICSEARCH_HOST=<your elasticsearch instance url> \
  -p 3000 \
  humanmade/local-pinpoint
docker pull humanmade/local-cognito
docker run -d \
  --name local-cognito \
  -p 3000:3001 \
  humanmade/local-cognito

然后可以将上述端点常量指向 http://localhost:3000 和 http://localhost:3001 分别。

由 Human Made 使用 ❤️ 制作