README

简介

此模块添加了通过服务器端使用Google的测量协议版本1发送点击到Google Analytics的功能：https://developers.google.com/analytics/devguides/collection/protocol/v1

模块当前允许发送以下点击

• 页面浏览量
• 事件
• 计时

这是通过构造GET请求并使用Guzzle将请求发送到Google Analytics端点来实现的。

需求

• SilverStripe CMS ^4.0
• Guzzle ^6.3

安装

通过composer安装模块

composer require internetrix/silverstripe-ga-measurement-protocol

配置 & 设置

1. 在config中设置以下变量以供Internetrix\GaMeasurementProtocol\Model\GAHit使用
   • useProductionGAProperty: 如果您想使用生产跟踪ID，则将其设置为true。如果要发送到预发布，则设置为false。
   • stagingTrackingID: 预发布/测试属性的Google Analytics UA跟踪ID。预期格式：'UA-XXXXXXXX-X'
   • productionTrackingID: 生产属性的Google Analytics UA跟踪ID。预期格式：'UA-XXXXXXXX-X'

示例YML配置

Internetrix\GaMeasurementProtocol\Model\GAHit:
  useProductionGAProperty: true
  stagingTrackingID: 'UA-XXXXXXXX-X'
  productionTrackingID: 'UA-XXXXXXXX-X'
  useTestingEndpoint: false

可选：另一个有用的配置变量是useTestingEndpoint，在配置中将它设置为true，这对于调试/测试很有用

Internetrix\GaMeasurementProtocol\Model\GAHit:
  useTestingEndpoint: true

通过将useTestingEndpoint设置为true，在发送点击时，模块将请求发送到Google的验证服务器。

由于Google的GA测量协议不返回HTTP错误代码，通过向测量协议验证服务器发送请求，您可以测试响应。如果当前SS环境设置为dev，它还将输出响应到浏览器/终端。

有关Google的测量协议验证服务器的更多信息，请参阅此处：https://developers.google.com/analytics/devguides/collection/protocol/v1/validating-hits

向生产Google Analytics属性发送点击

要向生产属性发送点击，必须满足以下所有条件。否则，点击将始终发送到预发布属性/调试端点。

• 条件1 - SilverStripe SS_ENVIRONMENT_TYPE变量必须设置为live
• 条件2 - 在配置中useProductionGAProperty必须设置为true
• 条件3 - 在配置中useTestingEndpoint必须设置为false

生成ClientID

重要：发送GA点击时，始终确保已设置点击类型，并且提供了一个唯一的客户端ID。此模块包含一个名为setClientID的函数，可以帮助开发人员添加客户端ID。该函数的第一个参数告诉函数在创建客户端ID时是否检索_ga cookie。第二个参数允许开发人员为点击覆盖客户端ID。

此函数可以使用以下方式使用

• 选项1：使用_ga cookie检索相同的ClientID（由前端共享）

  • $pageHit->setClientID(true);

• 选项2：生成一个全新的唯一客户端ID。如果选择此选项，则开发人员应保存唯一的客户端ID并重复使用，以便Google Analytics能够识别同一用户

  • $pageHit->setClientID(false);

• 选项3：覆盖并设置GA Client ID为开发者任意定义的值

  • $pageHit->setClientID(false, '<CUSTOM-CLIENT-ID>');

使用示例

GAHit.php中的PHPDocs包含解释每种事件所需参数的链接。否则，请参阅官方Google Analytics测量协议文档

示例1：向GA发送页面浏览击打

必需参数

• HitType = pageview
• 通过调用$hit->setClientID设置GA Client ID。有关更多详细信息，请参阅上面的生成ClientID部分
• 包含（文档主机名 + 文档路径 +（可选）文档标题）或者设置文档位置URL
• 通过调用$hit->setUserAgent()设置User-Agent，否则Google Analytics可能会将击打分类为机器人垃圾邮件

$hit = GAHit::create();
$hit->setHitType(GAHit::PAGEVIEW);
$hit->setClientID(true);
$hit->setUserAgent();
 
// Option 1
$hit->setPageviewParameters('https://example.com.au', '/foo', 'Test Page');
// OR Option 2
$hit->setDocumentLocationURL('https://example.com.au/foo', 'Test Page');

// Send hit to Google Analytics
$hit->sendHit();

示例2：向GA发送事件击打

必需参数

• HitType = event
• 通过调用$hit->setClientID设置GA Client ID。有关更多详细信息，请参阅上面的生成ClientID部分
• 通过调用$hit->setUserAgent()设置User-Agent，否则Google Analytics可能会将击打分类为机器人垃圾邮件
• 事件类别和事件操作是必需参数。事件标签和事件值是可选的。通过调用$hit->setEventParameters('category', 'action', 'label', $value)设置这些参数

$hit = GAHit::create();
$hit->setHitType(GAHit::EVENT);
$hit->setClientID(true);
$hit->setUserAgent();
$hit->setEventParameters('TestCategory', 'TestAction', 'TestLabel', 1);
$hit->setDocumentLocationURL('www.example.com.au/foo');

// (optional) Set as non-interaction hit if required
$hit->setNonInteractionHit();

// Send hit to Google Analytics
$hit->sendHit();

示例3：向GA发送计时击打

        $hit = GAHit::create();
        $hit->setHitType(GAHit::TIMING);
        $hit->setClientID(true);
        $hit->setTimingParameters($category, $userTimingVariable, $timingTime, $optionalParameters);
        $hit->setDocumentLocationURL('www.example.com.au');
        
        // Send hit to Google Analytics
        $hit->sendHit();

必需参数

• HitType = timing
• 通过调用$hit->setClientID设置GA Client ID。有关更多详细信息，请参阅上面的生成ClientID部分
• 通过调用$hit->setUserAgent()设置User-Agent，否则Google Analytics可能会将击打分类为机器人垃圾邮件
• 计时类别、计时变量和计时时间是必需的。通过调用$hit->setTimingParameters($category, $userTimingVariable, $timingTime, $optionalParameters)设置这些参数

添加自定义维度、自定义度量以及/或将额外参数添加到击打

要将自定义维度、自定义度量等额外参数添加到击打，使用addParameters方法，其中$parameters应该是一个数组，以参数名作为键，以参数值作为数组值

// Adding a Custom Dimension (with dimension index 1) and setting it to the value 'Sports'
$parameters['cd1'] = 'Sports'; 

// Adding a Custom Metric (with metric index of 1) and setting it to the int alue 47
$parameters['cm1'] = 47'; 

// Add custom dimension / metric to the hit
$hit->addParameters($parameters);

待办事项

• 添加对其他类型击打的支持，例如事务等。

许可证

有关更多信息，请参阅许可证文件