README

此模块提供了 SilverStripe 对 Intercom 的集成。

要求

SilverStripe 框架 4.0 或更高版本（在 1.x 分支和标签中支持 3.x）。与 CMS 一起工作得很好，但不是必需的。
PHP >=5.6.0

安装

使用 composer 安装模块，就像安装所有您喜欢的模块一样！

composer require silverstripe/intercom

文档

您可以在 docs 文件夹中找到详细文档。

许可

查看 license.md

工作原理

Intercom 的集成非常简单：在 </body> 标签之前添加几行 JavaScript。该模块通过其自己的 RequestFilter 添加。

配置

模块将在您的 .env 文件中使用以下全局常量。您应该设置这些：

INTERCOM_APP_ID：Intercom 集成设置中的“应用 ID”。必需。
INTERCOM_PERSONAL_ACCESS_TOKEN：Intercom 集成设置中的“个人访问令牌”。必需。
INTERCOM_SECRET_KEY：Intercom 安全模式给出的密钥。可选，但强烈推荐。

注意，如果您将密钥透露给任何人，他们可以冒充您的应用用户并与您的支持团队聊天，因此请确保其安全！应用程序 ID 的敏感性较低，因为它在您网站的 HTML 源代码中。

我建议您启用 Intercom 的“测试版本”。这将为您提供第二个应用 ID，您应该在测试和开发环境中使用它。

您的应用程序可以自定义以下属性发送的信息

SilverStripe\Intercom\IntercomScriptTags:
  anonymous_access: true
  company_property: Organisation
  company_fields:
    name: Title
    plan: AccountPlan
  user_fields:
    favourite_colour: FavouriteColour

anonymous_access：如果为 true，则集成代码将为匿名访客提供。此用于 Intercom Acquire。
always_anonymous：如果为 true，则集成代码将不会填充当前用户的详细信息。允许更好的缓存。此用于 Intercom Acquire。
company_property：指向成员组织的属性
company_fields：将 Intercom 字段名称映射到组织属性以传递的映射
user_fields：将 Intercom 字段名称映射到成员属性以传递的映射

有时才显示 Intercom

SilverStripe\Intercom\IntercomScriptTags 类有一个配置值，enabled，如果设置为 false，将禁用任何 Intercom 脚本标签的包含。

如果您只想有时显示 Intercom，您可以在页面加载期间随时更新此配置值，使用以下命令。例如，您可以选择只在某些页面上显示 Intercom，或者为某些用户显示。

\SilverStripe\Intercom\IntercomScriptTags::config()->enabled = false;

使用方法

跟踪事件

您可以使用 Intercom::trackEvent() 方法跟踪事件。事件将针对当前用户进行跟踪。

use SilverStripe\Core\Injector\Injector;
use SilverStripe\Intercom\Intercom;

$intercom = Injector::inst()->get(Intercom::class);
$intercom->trackEvent('test-event', array(
    'something' => 'a value',
    'other-one' => 'moar data',
));

您还可以明确指定此事件应针对哪个用户进行跟踪

use SilverStripe\Core\Injector\Injector;
use SilverStripe\Intercom\Intercom;
use SilverStripe\Security\Member;

$member = Member::get()->byID(34);
$intercom = Injector::inst()->get(Intercom::class);
$intercom->trackEvent('test-event', array(
    'something' => 'a value',
    'other-one' => 'moar data',
), $member);

$client->trackEvent("test-event", [
    "something" => "a value",
    "other-one" => "moar data",
], Member::get()->byID(34));

请注意，您目前无法跟踪匿名访客的事件；如果您尝试这样做，将抛出一个 LogicException。

通过 API 同步用户

有时，等到用户登录后更新他们的 Intercom 数据还不够。例如，如果您想使用 Intercom 发送电子邮件，您可能希望在发送第一封电子邮件之前更新 Intercom 数据库。

为此，您可以将 dev/tasks/IntercomBulkLoadTask 设置为在 cronjob 上运行。默认情况下，它将同步所有 Member 对象。如果您想同步更少的 Member 列表，您可以在 Intercom 类上设置 user_list 配置选项。这应该是 %$ServiceName 的形式，其中 ServiceName 是一个 Injector 服务的名称。

SilverStripe\Intercom\Intercom:
  user_list: %$AllPlatformUsers
SilverStripe\Core\Injector\Injector:
  AllPlatformUsers:
    factory: AllUserListFactory

在上面的示例中，我们使用一个名为 AllUserListFactory 的自定义工厂类来定义 Member DataList。它需要有一个名为 create() 的方法，该方法返回一个 Member 的 DataList。

use SilverStripe\Security\Member;

/**
 * Factory for generating a DataList of all platform users
 */
class AllUserListFactory
{
    public function create($class, $params)
    {
        return Member::get()->filter(['Some' => 'Value']);
    }
}

与表单集成

要从表单发送数据到 Intercom，您可以使用 SilverStripe\Intercom\IntercomFormExtension。

SilverStripe\Forms\Form:
  extensions:
    - SilverStripe\Intercom\IntercomFormExtension

这将向 Form 类提供几个可链式方法，帮助您将表单字段映射到 Intercom 字段。

$form
    ->addIntercomUserFieldMapping([
		'FullName' => 'name',
		'EmailAddress' => 'email'
	])
	->addIntercomCompanyFieldMapping([
		'CompanyName' => 'name'
	])
	->sendToIntercom();

对于自定义属性，在字段名称前加上 $。

$form->addIntercomUserFieldMapping([
    "FavouriteColour" => "\$favourite_color"
]);

此外，您可以将各种字段放入一个用于 Intercom 用户的“note”中。此映射的键是应出现在每个字段值之前的标签。

$form
    ->addIntercomNoteMapping([
		'SoftwareVersion' => 'The user is running version:'
	])
	->setIntercomNoteHeader('More information about this user');

上面的代码将创建一个类似以下内容的 note：

<p>More information about this user</p>
<ul>
    <li>The user is running version: ${SoftwareVersion}</li>
</ul>

与 Userforms 集成

请参阅 Uncle Cheese 的 silverstripe-intercom-userforms 模块。

维护者

Sam Minnée sam@silverstripe.com

错误追踪器

错误在此存储库的问题部分中跟踪。在提交问题之前，请查看现有问题以确保您的问题独特。

如果问题看起来像是一个新错误

创建一个新的问题
描述重现您问题的步骤和预期结果。单元测试、屏幕截图和屏幕录制可以帮助您。
尽可能详细地描述您的环境：SilverStripe 版本、浏览器、PHP 版本、操作系统、安装的任何 SilverStripe 模块。

请直接向模块维护者报告安全问题。请勿在错误追踪器中提交安全问题。

开发和贡献

如果您想为模块做出贡献，请确保您提交一个pull请求并与模块维护者进行讨论。

sminnee / silverstripe-intercom

维护者

详细信息