README

这个包在做什么？

此包在请求中搜索跟踪参数。

将跟踪参数存储在cookies中。

然后使用Formatter服务将这些跟踪参数添加到任何URL。

安装

使用composer下载此包。

$ composer require exs/lander-tracking-house-bundle

启用此包

<?php
// app/AppKernel.php

public function registerBundles()
{
    $bundles = array(
        // ...
        new EXS\LanderTrackingHouseBundle\EXSLanderTrackingHouseBundle(),
        // ...
    );
}

配置

cmp、exid和visit参数具有默认值，可通过以下配置键进行配置：

# Default values.
exs_lander_tracking_house:
    default_cmp: ~
    default_exid: 'exid'
    default_visit: 1

使用方法

在任意URL上使用appendTracking Twig过滤器。

如果用户拥有所需的跟踪参数，则会添加跟踪参数。

使用特定格式化器

<a href="{{ 'https://www.foo.tld/bar' | appendTracking('foo') }}" target="_blank">Some link</a>

<a href="{{ url('homepage') | appendTracking('foo') }}" target="_blank">Some link</a>

替换占位符

<a href="{{ url('homepage', {'cmp': '{cmp}', 'exid': '{exid}'}) | appendTracking }}" target="_blank">Some link</a>

<a href="{{ 'https://www.foo.tld/bar?cmp={cmp}&exid={exid}&visit={visit}' | appendTracking }}" target="_blank">Some link</a>

使用getTracking('parameterName') Twig函数获取任何跟踪参数。

    <input type="hidden" name="foo" value="{{ getTracking('foo') }}">

内置提取器

• cmp在请求或cookies中搜索名为cmp的参数。此参数包含cmp的值，并作为内部参数cmp提取。如果未找到，则使用exs_lander_tracking_house.default_cmp配置参数定义默认值。
• cup在请求中搜索名为cup的参数。此参数包含由{cmp}~{exid}~{product_id}组成的字符串，并作为内部参数cmp、exid和product_id提取。
• cu在请求中搜索名为cu的参数。此参数包含由{cmp}~{exid}组成的字符串，并作为内部参数cmp和exid提取。
• cuvp在请求中搜索名为cuvp的参数。此参数包含由{cmp}~{exid}~{visit}~{product_id}组成的字符串，并作为内部参数cmp、exid、visit和product_id提取。
• cuv在请求中搜索名为cuv的参数。此参数包含由{cmp}~{exid}~{visit}组成的字符串，并作为内部参数cmp、exid和visit提取。
• exid在请求或cookies中搜索名为exid、u或uuid的参数（将使用第一个匹配项）。此参数包含exid的值，并作为内部参数exid提取。如果未找到，则使用exs_lander_tracking_house.default_exid配置参数定义默认值。
• product_id在请求中搜索名为p的参数。此参数包含product_id的值，并作为内部参数product_id提取。
• uvp在请求中搜索名为uvp的参数。此参数包含由{exid}~{visit}~{product_id}组成的字符串，并作为内部参数exid、visit和product_id提取。
• uv在请求中搜索名为uv的参数。此参数包含由{exid}~{visit}组成的字符串，并作为内部参数exid和visit提取。
• visit在请求或cookies中搜索名为visit的参数。此参数包含visit的值，并作为内部参数visit提取。如果未找到，则使用exs_lander_tracking_house.default_visit配置参数定义默认值。

内置格式化器

• cup 将使用内部参数 cmp、exid 和 product_id 来附加由 {cmp}~{exid}~{product_id} 组成的 cup 参数。
• cu 将使用内部参数 cmp 和 exid 来附加由 {cmp}~{exid} 组成的 cu 参数。
• cuvp 将使用内部参数 cmp、exid、visit 和 product_id 来附加由 {cmp}~{exid}~{visit}~{product_id} 组成的 cuvp 参数。
• cuv 将使用内部参数 cmp、exid 和 visit 来附加由 {cmp}~{exid}~{visit} 组成的 cuv 参数。
• uvp 将使用内部参数 exid、visit 和 product_id 来附加由 {exid}~{visit}~{product_id} 组成的 uvp 参数。
• uv 将使用内部参数 exid 和 visit 来附加由 {exid}~{visit} 组成的 uv 参数。

添加提取器

该捆绑包使用提取器服务从请求、cookie中查找和获取跟踪参数，或者定义默认值。

这些服务必须实现 EXS\LanderTrackingHouseBundle\Service\TrackingParameterManager\TrackingParameterQueryExtracterInterface 和/或 EXS\LanderTrackingHouseBundle\Service\TrackingParameterManager\TrackingParameterCookieExtracterInterface 和/或 EXS\LanderTrackingHouseBundle\Service\TrackingParameterManager\TrackingParameterInitializerInterface。

所有这些方法都必须返回一个找到的跟踪参数的键/值数组，这些参数将被保存在cookie中。

示例

1. 为新的参数 foo 创建提取器类

<?php

namespace My\SomeBundle\Service;

use Symfony\Component\HttpFoundation\ParameterBag;
use EXS\LanderTrackingHouseBundle\Service\TrackingParameterManager\TrackingParameterCookieExtracterInterface;
use EXS\LanderTrackingHouseBundle\Service\TrackingParameterManager\TrackingParameterQueryExtracterInterface;
use EXS\LanderTrackingHouseBundle\Service\TrackingParameterManager\TrackingParameterInitializerInterface;

class FooExtracter implements TrackingParameterCookieExtracterInterface, TrackingParameterQueryExtracterInterface, TrackingParameterInitializerInterface
{
    public function extractFromQuery(ParameterBag $query)
    {
        $trackingParameters = [];

        if (null !== $foo = $query->get('foo')) {
            $trackingParameters['foo'] = $foo;
        }

        return $trackingParameters;
    }
    
    public function extractFromCookies(ParameterBag $cookies)
    {
        $trackingParameters = [];

        if (null !== $foo = $cookies->get('foo')) {
            $trackingParameters['foo'] = $foo;
        }

        return $trackingParameters;
    }
    
    public function initialize()
    {
        return [
            'foo' => 123,
        ];
    }
}

需要注意的重要事项： 从 extractFromQuery()、extractFromCookies() 和 initialise() 返回的数组中的所有键都将存储为cookie。

在下面的示例中，一个名为 foo 的cookie将被存储，其值来自查询或在cookie中找到的值，或者定义默认值。

2. 使用 exs_tracking.parameter_extracter 标签声明服务

services:
    exs_tracking.foo_extracter:
        class: 'My\SomeBundle\Service\FooExtracter'
        tags:
            - { name: 'exs_tracking.parameter_extracter' }

如果有多个提取器定义了 initialise() 方法，我们可以指定一个优先级，以确定使用哪个默认值（值越高优先级越高）。

services:
    exs_tracking.foo_extracter:
        class: 'My\SomeBundle\Service\FooExtracter'
        tags:
            - { name: 'exs_tracking.parameter_extracter', priotiry: 100 }

添加格式化器

该捆绑包使用格式化器服务来获取要附加到url的参数。

这些服务必须实现 EXS\LanderTrackingHouseBundle\Service\TrackingParameterManager\TrackingParameterFormatterInterface。

它们必须实现一个 format() 方法，该方法将接收一个包含从请求中找到的所有跟踪参数的 ParameterBag。

它还需要返回一个包含所有格式化参数的键/值数组，这些参数将附加到url上。

这些服务也必须带有 exs_tracking.parameter_formatter 标签。

参见 EXS\LanderTrackingHouseBundle\Service\TrackingParameterManager\CmpTrackingParameterFormatter 以获取格式化器的示例。

按照惯例，格式化器服务的名称为 exs_tracking.xxxsomethingxxx_formatter。

示例

1. 创建实现 EXS\LanderTrackingHouseBundle\Service\TrackingParameterManager\TrackingParameterFormatterInterface 的格式化器类

<?php

namespace My\SomeBundle\Service;

use Symfony\Component\HttpFoundation\ParameterBag;
use EXS\LanderTrackingHouseBundle\Service\TrackingParameterManager\TrackingParameterFormatterInterface;

class FooFormatter implements TrackingParameterFormatterInterface
{
    public function format(ParameterBag $trackingParameters)
    {
        return [
            'foo' => $trackingParameters->get('foo'),
        ];
    }
}

2. 使用 exs_tracking.parameter_formatter 标签声明服务

services:
    exs_tracking.foo_formatter:
        class: 'My\SomeBundle\Service\FooFormatter'
        tags:
            - { name: 'exs_tracking.parameter_formatter' }

3. 使用

如前所述，我们只需使用Twig过滤器 appendParameter 作用于任何url，如果定义了 foo 参数，它将被添加。

    <a href="{{ 'http://www.test.tld/' | appendParameter('foo') }}">Some link</a>
    <!-- or -->
    <a href="{{ 'http://www.test.tld/?foo={foo}' | appendParameter}}">Some link</a>