README

安装模块

我们建议使用 Composer 进行安装和更新管理。

composer require remp/crm-salesfunnel-module

启用模块

将已安装的扩展添加到您的 app/config/config.neon 文件中。

extensions:
	- Crm\SalesFunnelModule\DI\SalesFunnelModuleExtension

配置

默认情况下，我们会为每个销售漏斗的短路径进行注册（例如，对于具有 URL 键 sample 的销售漏斗，路径为 http://crm.press/sample）。您可以通过在配置文件中添加以下设置来关闭 slugs 的注册。

sales_funnel:
	funnel_routes: false

销售漏斗仍然可以通过长路径访问（例如，http://crm.press/sales-funnel/sales-funnel-frontend/show?funnel=sample）。

计划命令

请将以下命令添加到您的计划程序

sales-funnel:distributions。每个销售漏斗预先计算通过它支付的用户的数据。这些计算用于提供漏斗详细信息的统计和分布。统计数据会实时更新，但建议每天运行一次。

使用销售漏斗

销售漏斗模块提供了一种以完全独立于应用程序其余部分的方式向用户提供订阅类型产品的方式。

您可以在 CRM 管理员（/sales-funnel/sales-funnels-admin/）中找到可用的销售漏斗列表并创建新的漏斗。

要创建新的销售漏斗，您需要填写几个字段（加粗为必填项）

名称。在 CRM 管理员列表和统计中显示的销售漏斗名称。
激活。标志，表示窗口是否对用户可用。
URL 键。窗口可用的 slug。所有漏斗都在自定义路径上可用 - 例如，具有 URL 键 sample 的示例漏斗将在 http://crm.press/sales-funnel/sales-funnel-frontend/show?funnel=sample 和 http://crm.press/sample 上可用（如果允许 slugs，请参阅配置）。
仅限登录用户。标志，限制访问仅限于已登录用户。
仅限未登录用户。标志，限制访问仅限于未登录用户。
分段。选择分段，限制访问仅限于特定分段的成员。
从。日期约束，允许漏斗仅在指定日期之后可用。
到。日期约束，允许漏斗仅在指定日期之前可用。
漏斗 HTML 内容。漏斗的 HTML 内容（需要提供顶部到底部的 HTML；下面有说明）
漏斗无访问 HTML。如果用户由于指定的约束无法访问窗口，则显示的 HTML。如果没有提供 HTML，则显示默认的 funnel-no-access。
漏斗错误屏幕 HTML。如果有任何类型的验证错误，显示的 HTML。如果没有提供 HTML，则显示默认的 funnel-error。

创建漏斗后，还有更多选项可以在创建的漏斗详细资料中进行配置

订阅类型。每个漏斗都有一个允许的订阅类型列表。允许的订阅类型数组作为twig变量提供给HTML内容模板，以便进一步使用。只有白名单中的订阅类型才允许在漏斗中提交，否则验证将返回错误。
支付网关。每个漏斗都有一个允许的支付网关列表。允许的网关数组作为twig变量提供给HTML内容模板，以便进一步使用。只有白名单中的网关才允许在漏斗中提交，否则验证将返回错误。

漏斗的HTML内容可以是任何东西，从非常简单的HTML表单到调用后端API并引导用户通过多步体验的微型JS应用程序。漏斗支持Twig模板，并提供在模板中使用的变量。

funnel：代表sales_funnels表行的实例（作为Nette\DB\Table\ActiveRow实现）
isLogged：标志，表示用户是否已登录。应利用此标志显示登录表单。
gateways：代表gateways表行的数组。应利用此数组，结合Twig的if语句显示/隐藏白名单网关。
```
{% if gateways['paypal'] is defined %}
  <div class="row"></div>
{% endif %}
```
subscriptionTypes：代表subscription_types表行的数组。应利用此数组，结合Twig的if语句显示/隐藏白名单订阅类型。
```
{% if subscriptionTypes['web_month'] is defined %}
  <div class="row"></div>
{% endif %}
```
addresses：包含所有存储的用户地址的数组。
meta：播种到sales_funnel_meta表的漏斗元数据。
jsDomain：用于与cookies一起工作的JavaScript域名。
actualUserSubscription：对实际用户订阅的引用——作为Nette\DB\Table\ActiveRow实现的subscriptions表行。
referer：用于访问销售漏斗的引用参数。主要从referer查询字符串参数加载。如果未提供，则使用HTTP引用。
values：如果页面已重新加载，则提交的值的数组。
errors：上一次提交生成的错误数组。

您可以使用/忽略这些变量中的任何一个。它们提供有关用户的信息，供您决定用户应看到什么。

Twig还提供了一个翻译过滤器trans，可以在模板中翻译字符串或封装漏斗之间的重复文本或消息。

<label>{{ 'internal.salesfunnel.gateway.cardpay.label'|trans }}</label>
{# This will work if you're using an Internal module with the existing translation key 'internal.salesfunnel.gateway.cardpay.label' in your translations #}

销售漏斗的最终输出应该是POST请求到/sales-funnel/sales-funnel-frontend/submit——通过HTML表单或通过AJAX请求。POST参数应包含

funnel_url_key：创建销售漏斗时定义的漏斗的URL键。可以从{{ funnel.url_key }}变量中填充。
auth：标志0 / 1，表示CRM是否应尝试使用电子邮件和密码对用户进行身份验证。
email：如果进行身份验证，用户应提供其电子邮件地址。
password：如果进行身份验证，用户应提供其密码。
subscription_type：用户选择的购买订阅类型的代码（不是ID）。
payment_gateway：用户选择的支付网关的代码。
additional_amount：除了标准订阅类型价格之外应包含在付款中的额外金额。用于捐赠。
additional_type：标志，表示additional_amount是否应在通过周期性网关进行的付款中包含在未来的收费中。允许的值是single / recurrent。
address_id：如果用户在销售漏斗中提供地址，则可以提交地址ID，该地址将被存储在付款中并在创建的订阅中。如果需要强制执行非标准送货地址，则很有用。
custom：键值对（即custom[key]=value），将被存储在付款备注字段中作为文本。
allow_redirect：标志指定响应是否应包含重定向头或仅包含带有支付网关URL的JSON响应。如果您不想将用户从CRM中重定向，但只想通过AJAX提交值并在模态窗口的iframe中显示支付网关，则非常有用。

如果表单有效，后端将为用户创建新的未完成付款，并且服务器响应将包含重定向到支付网关的链接。

示例漏斗

该模块提供了一个单一代码示例漏斗，该漏斗包含非常基础的基于bootstrap的设计和简单的javascript处理程序，用于询问和验证用户的电子邮件/密码。

当模块启用时，您可以通过运行php bin/command.php application:seed来生成此漏斗，它将出现在您域的/sample URL上。您（并且应该）还可以在CRM管理员中找到您的漏斗（/sales-funnel/sales-funnels-admin/），因为您仍然需要为此新创建的漏斗启用订阅类型和网关才能正确工作。

如果您只想查看漏斗的示例实现，您可以在这里找到它。

事件和处理程序

PaymentItemContainerReadyEvent

此事件在SalesFunnelFrontedPresenter::renderSubmit之后发出，此时PaymentItemContainer已初始化并填充了基本支付项目（例如SubscriptionTypePaymentItem），但在创建支付之前。

所有注册此事件监听器的处理程序都可以访问整个PaymentItemContainer。它可以在创建支付并在客户被重定向到支付提供者之前添加支付项目。

示例模块实现

例如，您的销售漏斗包含一个具有名称specific_donation的特定捐赠输入字段，并且您想将其添加到支付中。

创建处理程序Crm\ExampleModule\Events\PaymentItemContainerReadyEventHandler

<?php

namespace Crm\ExampleModule\Events;

use Crm\PaymentsModule\PaymentItem\DonationPaymentItem;
use League\Event\AbstractListener;
use League\Event\EventInterface;

class PaymentItemContainerReadyEventHandler extends AbstractListener
{
    public function handle(EventInterface $event)
    {
        $paymentData = $event->getPaymentData();
        if (isset($paymentData['specific_donation']))
        {
            $paymentItemContainer = $event->getPaymentItemContainer();
            $paymentItemContainer->addItem(
                new DonationPaymentItem(
                    $name = 'Specific donation',
                    $price = $paymentData['specific_donation'],
                    $vat = 0
                )
            );
        }
    }
}

并在ExampleModule\ExampleModule.php中初始化监听器

  public function registerEventHandlers(\League\Event\Emitter $emitter)
{
  //...
  $emitter->addListener(
    \Crm\SalesFunnelModule\Events\PaymentItemContainerReadyEvent::class,
    $this->getInstance(\Crm\ExampleModule\Events\PaymentItemContainerReadyEventHandler::class)
  );
  //...

由销售漏斗创建的新支付现在将包含特定捐赠，如果销售漏斗收到此字段。

销售漏斗twig变量和片段

注册

当使用销售漏斗时，您还可以传递自定义变量或使用由ApplicationModule Crm\ApplicationModule\Repositories\SnippetsRepository提供的片段功能。

要使用此功能，您需要在sales_funnel.dataprovider.twig_variables数据提供者路径中注册实现SalesFunnelVariablesDataProviderInterface的自定义数据提供程序。

$dataProviderManager->registerDataProvider(
    'sales_funnel.dataprovider.twig_variables',
    $this->getInstance(SalesFunnelTwigVariablesDataProvider::class)
);

数据提供程序示例

final class SalesFunnelTwigVariablesDataProvider implements SalesFunnelVariablesDataProviderInterface
{
    // add ability to load snippets, check docblock for further info
    use SalesFunnelTwigSnippetLoaderTrait;

    public function provide(array $params): array
    {
        if (!isset($params[self::PARAM_SALES_FUNNEL])) {
            throw new DataProviderException('missing [' . self::PARAM_SALES_FUNNEL . '] within data provider params');
        }
        
        $salesFunnel = $params[self::PARAM_SALES_FUNNEL];

        $returnParams = [];
        
        // adding custom twig variable
        $returnParams['your_custom_twig_variable'] = 'your_custom_twig_variable';
        
        // load snippets (feature provided by ApplicationModule)
        $snippetsToLoad = ['header', 'footer', 'sales-funnel-common-header'];
        $returnParams += $this->loadSnippets($salesFunnel, $loadSnippets);
        
        return $returnParams;
    }
}

在销售漏斗中的使用

片段的名称被更改为带有前缀snippet的驼峰式。因此sales-funnel-common-header变为

  {{ snippetSalesFunnelCommonHeader|raw }}

变量可以按提供的方式进行访问。因此your_custom_twig_variable将是

{% if your_custom_twig_variable %}
  <h1>{{ your_custom_twig_variable }}</h1>
{% endif %}

销售漏斗中iframe的弃用

弃用

由于现代化和在使用iframe作为销售漏斗包装器时的多个问题（例如iOS设备上的滚动和焦点问题），我们停止使用iframe来渲染销售漏斗。

现在已标记为弃用的方法和/路由

Crm\SubscriptionsModule\Presenters\SubscriptionsPresenter#renderNew()
- 服务URLhttp://crm.press/subscriptions/subscriptions/new
Crm\SalesFunnelModule\Presenters\SalesFunnelFrontendPresenter#renderDefault()
- 服务URLhttp://crm.press/sales-funnel/sales-funnel-frontend/?funnel=url_key

⚠️ 它们将在CRM版本4.0中被删除（或重构）。

解决方案

如果您使用 Subscriptions:Subscriptions:new 作为默认路由，我们建议您更新您的配置 默认路由（请参考应用类别中的https://crm.press/admin/config-admin/），将其更改为 SalesFunnel:SalesFunnel:newPopup。此方法将直接从配置中的 默认销售漏斗（请参考销售漏斗类别）加载并渲染默认销售漏斗，而不使用iframe。

您可以直接在自定义模块中为您的销售漏斗注册路由。例如

use Crm\SalesFunnelModule\DI\Config;
use Crm\SalesFunnelModule\Models\SalesFunnelsCache;

class DemoModule extends CrmModule
{
    // ...

    public function registerRoutes(RouteList $router)
    {
        // to avoid iframes for all sales funnels of Demo instance
        if ($this->config->getFunnelRoutes()) {
            foreach ($this->salesFunnelsCache->all() as $salesFunnel) {
                $router->prepend(new Route(
                    "<funnel {$salesFunnel->url_key}>",
                    'SalesFunnel:SalesFunnelFrontend:show'
                ));
            }
        }
    }

    // ...
}