README

基于statamic网站的存储和处理基于会话的UTM参数的助手。

{{ if { utm:has type="source" value="google" } }}
    <span>{{ utm:get type="medium" }}</span>
{{ /if }}

安装

您可以在Statamic控制面板的“工具 > 扩展”部分搜索此插件并点击“安装”，或者从项目根目录运行以下命令：

composer require suarez/statamic-utm-parameter

可选地，您可以使用以下命令发布此包的配置文件：

php artisan vendor:publish --tag="statamic-utm-parameter-config""

注意：UTM参数是按会话存储的，这意味着它们仅在用户的当前浏览会话期间可用，当用户关闭浏览器或离开您的网站时将被清除。此插件利用内置的Laravel会话管理系统进行存储。

配置

配置文件 config/statamic-utm-parameter.php 允许您控制UTM参数处理的行为。

<?php

return [
  /*
   * Control Overwriting UTM Parameters (default: false)
   *
   * This setting determines how UTM parameters are handled within a user's session.
   *
   * - Enabled (true): New UTM parameters will overwrite existing ones during the session.
   * - Disabled (false): The initial UTM parameters will persist throughout the session.
   */
  'override_utm_parameters' => false,

  /*
   * Session Key for UTM Parameters (default: 'utm')
   *
   * This key specifies the name used to access and store UTM parameters within the session data.
   *
   * If you're already using 'utm' for another purpose in your application,
   * you can customize this key to avoid conflicts.
   * Simply provide your preferred key name as a string value.
   */
    'session_key' => 'utm',

  /*
    * Allowed UTM Parameters (default: ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'utm_campaign_id'])
    *
    * This setting defines the UTM parameters that are allowed within your application.
    *
    * In this array, you can specify a list of allowed UTM parameter names. Each parameter should be listed as a string.
    * Only parameters from this list will be stored and processed in the session.
    * and any parameter without the 'utm_' prefix will be ignored regardless of its inclusion in this list.
    *
    * Example: To only allow the basic UTM parameters (source, medium, and campaign), you could update the array like this:
    *
    * 'allowed_utm_parameters' => [
    *     'utm_source',
    *     'utm_medium',
    *     'utm_campaign',
    * ],
    */
    'allowed_utm_parameters' => [
        'utm_source',
        'utm_medium',
        'utm_campaign',
        'utm_term',
        'utm_content',
        'utm_campaign_id'
    ],
];

使用方法

此插件提供方便的方法来检索、检查和使用Statamic模板中的UTM参数。

Antlers模板

检索所有UTM参数

使用 {{ utm:all }} 获取所有UTM参数的数组。

{{ utm:all }}

检索特定UTM参数

使用 {{ utm:get }} 获取特定UTM参数的值。

{{ utm:get type="term" }}

检查特定UTM参数是否存在

使用 {{ utm:has }} 或 {{ utm:is }} 检查特定UTM参数是否存在。

{{ if { utm:has type="medium" value="newsletter" } }}
    <span>Subscribe to our podcast</span>
{{ /if }}

检查特定UTM参数是否包含特定值

使用 {{ utm:contains }} 检查特定UTM参数是否包含特定值。

{{ if { utm:contains type="campaign" value="summer" } }}
    <p>Summer-Deals</p>
{{ /if }}

清除UTM参数

使用 clear 方法从会话中删除并重置UTM参数。

UtmParameter::clear(); // true

参数类型

以下UTM参数类型受支持

source：流量来源（例如，google，newsletter）。
medium：流量介质（例如，cpc，email）。
campaign：活动名称（例如，spring_sale）。
term：使用的搜索词（例如，running+shoes）。
content：特定内容（例如，ad_variation_1）。

示例

显示所有UTM参数

    <ul>
        {{ foreach array="{ utm:all }"}}
            <li>{{ key }}: {{ value }}</li>
        {{ /foreach }}
    </ul>

显示特定UTM参数

要显示UTM term参数

{{ utm:get type="term" }}

基于UTM参数的条件显示

如果来源是 google，则显示UTM medium参数

{{ if { utm:has type="medium" value="newsletter" } }}
    <span>Subscribe to our podcast</span>
{{ /if }}

{{ if { utm:contains type="campaign" value="summer" } }}
    <p>Summer-Deals</p>
{{ /if }}

完整示例

以下是一个结合所有功能的完整示例

<ul>
    <li>Source: {{ utm:get type="source" }}</li>
    <li>Medium: {{ utm:get type="medium" }}</li>
    <li>Campaign: {{ utm:get type="campaign" }}</li>
    <li>Term: {{ utm:get type="term" }}</li>
    <li>Content: {{ utm:get type="content" }}</li>
</ul>

{{ if { utm:has type="source" value="ecosia" } }}
    <div>Thank you for visiting from Ecosia!</div>
{{ elseif { utm:has type="source" value="newsletter" } }}
    <p>Welcome back, newsletter subscriber!</p>
{{ else }}
    <p>Subscribe to our newsletter!</p>
{{ /if }}

扩展中间件

您可以通过扩展中间件来自定义接受UTM参数的行为。例如，您可以覆盖 shouldAcceptUtmParameter 方法。

首先，使用Artisan创建一个新的中间件

php artisan make:middleware CustomMiddleware

然后，更新新的中间件以扩展UtmParameters并覆盖 shouldAcceptUtmParameter 方法

<?php

namespace App\Http\Middleware;

use Illuminate\Http\Request;
use Suarez\StatamicUtmParameters\Http\Middleware\CheckUtmParameter;

class CustomMiddleware extends CheckUtmParameter
{
    /**
     * Determines whether the given request/response pair should accept UTM-Parameters.
     *
     * @param \Illuminate\Http\Request  $request
     *
     * @return bool
     */
    protected function shouldAcceptUtmParameter(Request $request)
    {
        return $request->isMethod('GET') || $request->isMethod('POST');
    }
}

最后，更新您的 bootstrap/app.php 以使用CustomMiddleware

# bootstrap/app.php
use App\Http\Middleware\CustomMiddleware;

->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        CustomMiddleware::class,
        // other middleware...
    ]);
})

许可证

Statamic UTM-Parameters插件是开源软件，受MIT许可证的许可。

suarez / statamic-utm-parameter

维护者

详细信息