README

入门模块允许您定义用户应实现的目标。目标仅是一个标签，表示用户是否已完成。

定义目标后，转到场景构建器，创建一个包含“目标”元素的场景。此元素可以配置以下属性

• 哪些目标需要完成才能触发“成功”分支。
• CRM 应多久检查一次目标是否完成。
• CRM 应等待多长时间（超时）才放弃目标并触发“失败”分支。

安装模块

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

composer require remp/crm-onboarding-module

启用模块

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

extensions:
	- Crm\OnboardingModule\DI\OnboardingModuleExtension

添加后，为新模块生成 ACL。

php bin/command.php user:generate_access
php bin/command.php api:generate_access
php bin/command.php application:seed

此时，您（超级管理员）应能够通过“人员”-“入门目标管理员”菜单（/onboarding/onboarding-goals-admin/）定义新目标，并且内部 API 令牌应有权访问公开的 API 端点。

如果您需要其他角色访问目标定义，您可以在“人员”-“管理员权限”页面（/users/admin-group-admin/）为角色分配访问权限。

完成目标

目标的完成可能因目标类型而异。目前我们计划支持两种类型的目标

• 简单。此类目标必须通过调用 onboarding-goals/complete API 端点来明确完成。
• Beam（尚未提供）。此类目标将 Beam 事件定义为触发器。一旦事件提交给 Beam，CRM 中的目标将自动为指定用户完成。

具有活动入门目标用户的细分

命令 php bin/command.php application:seed 自动为入门目标生成细分。

• 生成的是配置和 SQL 查询；其余部分由 SegmentModule 处理。
• 这些细分是锁定的，用户无法通过 CRM 管理员编辑它们。
• 每个入门目标都有自己的细分。

如果用户

• 是活跃的，
• 有活动入门目标 （在 user_onboarding_goals 表中的条目；未完成或超时）。

注意：用户的入门目标激活应由您的模块处理，或者您可以在 ScenariosModule 中创建场景。场景将为每个进入场景入门目标节点的用户生成条目 （由 Crm\ScenariosModule\Events\OnboardingGoalsCheckEventHandler 处理）。

REMP 活动中的实时细分

如果您在 REMP 活动中使用 CRM 细分，则需要启用处理程序，以在 REMP 活动中更新入门目标细分缓存。否则，您会遇到用户已完成目标，但仍然看到活动横幅的情况 （他是缓存细分的一部分）。

注意：必须安装并启用模块 RempCampaignModule。

将准备好的处理程序添加到您的模块的 services 配置部分

services:
	- Crm\RempCampaignModule\Events\UserOnboardingGoalEventsHandler

并在您的模块中启用对用户入门目标更改的监听器（例如，ExampleModule\ExampleModule.php）

namespace Crm\ExampleModule;

class ExampleModule extends \Crm\ApplicationModule\CrmModule
{
    //...

    public function registerEventHandlers(\League\Event\Emitter $emitter)
    {
        //...

        // catch user onboarding events & handle them in RempCampaign's handler
        $emitter->addListener(
            \Crm\OnboardingModule\Events\UserOnboardingGoalCreatedEvent::class,
            $this->getInstance(\Crm\RempCampaignModule\Events\UserOnboardingGoalEventsHandler::class)
        );
        $emitter->addListener(
            \Crm\OnboardingModule\Events\UserOnboardingGoalCompletedEvent::class,
            $this->getInstance(\Crm\RempCampaignModule\Events\UserOnboardingGoalEventsHandler::class)
        );
        $emitter->addListener(
            \Crm\OnboardingModule\Events\UserOnboardingGoalTimedoutEvent::class,
            $this->getInstance(\Crm\RempCampaignModule\Events\UserOnboardingGoalEventsHandler::class)
        );
        //...
    }

    //...
}

API 文档

所有示例使用 http://crm.press 作为基础域名。请在执行示例之前将主机更改为您使用的域名。

所有示例使用 XXX 作为授权令牌的默认值，请将其替换为实际令牌。

• API令牌。 服务器间通信的标准API密钥。它将调用应用程序作为一个整体进行标识。它们可以在CRM管理中生成（/api/api-tokens-admin/），并且每个API密钥都必须白名单才能访问特定的API端点。默认情况下，API密钥没有访问任何端点的权限。
• 用户令牌。 在登录过程中为每个用户生成，令牌在系统不同部分之间通信时标识单个用户。令牌可以从以下位置读取
  • 来自 n_token cookie（如果用户通过CRM登录）。
  • 来自 /api/v1/users/login 端点 的响应 - 您可以将响应存储到自己的cookie/local存储/session中。

API响应可以包含以下HTTP状态码

如果可能，响应将包含带有解释错误消息的 application/json 编码的有效负载。

POST /onboarding-goals/complete

API调用完成特定用户的 简单 目标。

头部

主体

{
	"goal_code": "demo", // String; required; code of the simple goal
	"user_id": 301109 // Integer; required; ID of user completing the goal
}

示例

curl -X POST \
  http://crm.press/api/v1/onboarding-goals/complete \
  -H 'Content-Type: application/javascript' \
  -H "Authorization: Bearer XXX" \
  -d '{
	"goal_code": "demo",
	"user_id": 301109
}'

$payload = [
    "goal_code" => "demo",
    "user_id" => 301109,
];
$jsonPayload = json_encode($payload);
$context = stream_context_create([
        'http' => [
            'method' => 'POST',
            'header' => "Content-Type: type=application/json\r\n"
                . "Accept: application/json\r\n"
                . "Content-Length: " . strlen($jsonPayload) . "\r\n"
                . "Authorization: Bearer XXX",
            'content' => $jsonPayload,
        ]
    ]
);
$response = file_get_contents("http://crm.press/api/v1/onboarding-goals/complete", false, $context);
// process response (raw JSON string)

响应

{
    "status": "ok"
}

GET /onboarding-goals/list

端点用于列出所有可用的目标。

头部

示例

curl -X GET \
  http://crm.press/api/v1/onboarding-goals/list \
  -H 'Content-Type: application/javascript' \
  -H "Authorization: Bearer XXX"

$context = stream_context_create([
        'http' => [
            'method' => 'GET',
            'header' => "Content-Type: type=application/json\r\n"
                . "Accept: application/json\r\n"
                . "Authorization: Bearer XXX",
        ]
    ]
);
$response = file_get_contents("http://crm.press/api/v1/onboarding-goals/list", false, $context);
// process response (raw JSON string)

响应

{
    "status": "ok",
    "goals": [
        {
            "name": "Demo", // name of the goal (to display)
            "code": "demo", // code of the goal (for backend communication)
            "type": "simple" // type of goal
        },
        // ...
    ]
}