README

重要：版本2.1.0（Craft 5）/ 1.5.0（Craft 4）引入了破坏性变更。如果您升级到这个版本，您需要在您的twig模板中显式调用optimumFireEvent。

此插件允许用户在CraftCMS中进行服务器端A/B测试。与客户端测试（例如使用Google Optimize）相比，测试变体在服务器端渲染，从而带来更好的用户体验、性能和增强的灵活性。

一旦设置实验，您可以将数据发送到您的跟踪平台并开始跟踪。默认情况下，事件作为自定义维度发送给Google Analytics 4。您随后可以充分利用分析功能，比较不同指标（例如转化、参与度等）的测试组。

如果您使用的是不同的分析平台，您仍然可以使用此插件进行测试，通过传递自定义的fireEvent闭包。

要求

Craft CMS 4.x或更高版本。如果使用GA跟踪
Google Analytics 4（GA4）账户。
在页面上安装了Google Tag Manager脚本（在浏览器控制台中输入gtag以验证）。

注意：尽管最后两点对于开发不是关键，但为了完整性，建议创建一个虚拟的gtag 函数。

安装

包含包

composer require matfish/craft-optimum

安装插件

php craft plugin/install optimum

使用方法

1. 在控制面板中创建一个实验

单击新的“实验”菜单项，然后单击“新建实验”。一个实验包括以下字段

名称例如 '横幅类型'
处理例如 bannerTypes。这将在两个地方使用
1. 在命名变体模板的文件夹时使用。
2. 作为设置GA4自定义维度的参数名
启用？ - 是否当前激活实验。这可以用来暂停或永久停止实验
变体 - 实验的不同变体。例如，如果您正在测试不同的英雄横幅，您将在此处设置它们的参考。一个“原始”变体已预先设置，代表控制组，即您的当前代码。其处理程序名称不能修改，也不能删除。每个变体包括三个字段
- 名称：可读的名称。这将被发送到GA4作为值（例如“宽横幅”）
- 处理：用于在twig中命名变体模板（例如“wideBanner”）
- 权重：相对权重（概率），以百分比表示（例如40）。所有变体权重的总和必须加起来等于100%
开始时间：可选字段以延迟实验。如果为空，则实验立即开始（假设“启用？”处于开启状态）。
结束时间：默认设置为30天后。

2. 在twig中创建变体

方法A：多态

将您希望测试的代码部分（您的“原始”变体）用{% optimum 'experimentHandle' %}标签包裹，如下所示

{% optimum 'bannerTypes' %}
   // Original Variant Code
   <img src="original_banner.jpg"/>  
{% endoptimum %}

然后创建与每个变体相对应的模板（除了“原始”），使用以下命名约定：_optimum/{experimentHandle}/{variantHandle}.twig

例如

_optimum/bannerType/wideBanner.twig
_optimum/bannerType/narrowBanner.twig

在每个模板中粘贴您希望测试的变体代码。例如

   // Wide Banner Variant Code
   <img src="wide_banner.jpg" class="wide-banner"/>

注意： 不要在主模板代码中包含变体模板。Optimum 将自动在运行时加载正确的模板。

方法 B：显式变体声明

虽然方法 A 在您想要切换组件时很有用，但有时您可能希望切换页面上的组件位置（例如，测试不同的 CTAs 位置）。使用方法 B，您可以使用第二个参数为变体声明多个 optimum 块。

例如

{% optimum 'cta_position' 'top' %}
   <button>Buy now!</button>
{% endoptimum %}
// Some HTML
{% optimum 'cta_position' 'original' %}
   <button>Buy now!</button>  
{% endoptimum %}
// Some more HTML
{% optimum 'cta_position' 'bottom' %}
   <button>Buy now!</button>
{% endoptimum %}

插件将仅编译相关的变体。

方法 C：仅获取变体值

在某些情况下，不需要创建多个模板，因为随机变体的值可以替换代码中的常量。例如，假设您有一个博客并希望测试每页的不同值。这里是一个针对假设的（《或不是吗？》）recordsPerPage 实验的示例实现。

{% set variant = optimumGetVariant('recordsPerPage') %}
{% set perPage = variant is same as ('original') ? 6 : 9 %} // Or use a switch statement if you have more than 2 variants
{% paginate query.limit(perPage) as pageInfo, pageEntries %}
// Pagination code

4. 触发事件

将实验和变体发送到您的跟踪平台

<script>
{{ optimumFireEvent('bannerTypes') | raw }}
</script>

默认情况下，这将发送事件到 GA4。例如

gtag('event','bannerTypes', {'bannerTypes':'Wide Banner'});

您可以通过指定 trackingPlatform 或通过覆盖 fireEvent 设置来修改跟踪代码。

在您的配置文件夹中创建一个名为 optimum.php 的新文件
添加以下代码

return [
   'trackingPlatform' => 'mixpanel', // currently supports 'mixpanel' and 'ga4'. Default: 'ga4', OR:
   'fireEvent' => function($experiment, $variant) {
        // Your custom tracking code here,e.g:
        return <<<EOD
        myCoolPlatform.track('Experiment Started', 
        {
          'Experiment name': $experiment->name, 
          'Variant name': $variant->name
        })
        EOD;
        // Note that as you have access to the Experiment and Variant objects, you can use either their handle or name in the tracking code.
    }
];

如果您正在使用 Optimum 当前不支持跟踪平台，我们鼓励您分享您的自定义跟踪代码实现。这将帮助我们在未来更新中扩展对更多平台的支持，使整个社区受益。请考虑将您的自定义跟踪代码示例提交到项目仓库或联系维护者。

5. 测试您的变体

现在一切设置完毕，插件将随机选择一个变体并将其持久保存在 cookie 中，以保持每个用户的体验一致。您可以通过将 ?optimum={variant} 查询参数添加到您的 URL 中来测试您的变体（以及原始变体）。例如 ?optimum=wideBanner 或 ?optimum=original。如果该值不对应于任何变体，插件将忽略该参数。

6. 在 GA4 中设置自定义维度（仅当使用 GA4 进行跟踪时）

最后一步是告诉 GA4 将从您的网站发送的事件聚合到一个自定义维度中。

打开 GA，转到您的属性，然后点击 配置->自定义定义
单击 创建自定义维度 按钮
在模态窗口中填写以下详细信息
- 维度名称：描述性名称。可以是您想要的任何内容。
- 作用域：事件
- 事件参数：实验句柄（例如 bannerType）。
单击 "保存"

就这样

所有完成！一旦 GA 收集了足够的数据，您就可以开始比较不同群体/测试组的性能。

如果使用不同的跟踪平台，您需要相应地设置跟踪。

故障排除

在打开问题之前，请确保

已启用 Cookie
测试页面（例如 Blitz）已禁用缓存，因为插件会实时决定要提供哪个变体。
如果使用 GA4 进行跟踪：页面上已安装 GTM（在控制台中输入 gtag 以验证）。
如果您编辑现有的实验（一旦上线，建议不要这样做），您需要删除模板缓存，以便它能够用新的细节重新编译。

注意事项

位于 optimum 标签内的代码具有作用域。定义在包含原始变体（或变体模板）的块内的变量将无法在外部访问。

本地开发

在本地开发时，如果您使用 GA4 跟踪代码，您可能不会安装 gtag，这将导致以下控制台错误

Uncaught ReferenceError: gtag is not defined

虽然忽略此问题进行开发没有问题，但为了完整起见，并查看发送给 GA 的参数，您可以在您的 <head> 部分添加一个虚拟的 gtag 函数。

{% if (getenv('CRAFT_ENVIRONMENT') is same as ('dev')) %}
  <script>
      function gtag() {
        console.log(arguments)
       }
   </script>
{% endif %}

您可以使用相同的方法模拟其他跟踪函数。

许可证

您可以在开发环境中试用 Optimum，时间不限。一旦您的网站上线，您必须为插件购买许可证。许可证可通过 Craft 插件商店购买。

有关更多信息，请参阅 Craft 的商业插件许可证。

matfish / craft-optimum

维护者

详细信息