README

本模块提供了SilverStripe与Intercom的集成。

需求

SilverStripe框架4.0或更高版本（3.x版本在1.x分支和标签中提供支持）。与CMS配合良好，但不是必需的。
PHP >=5.6.0

安装

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

composer require silverstripe/intercom

文档

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

许可

请参阅license.md

工作原理

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

配置

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

INTERCOM_APP_ID：Intercom集成设置中的“App ID”。必需。
INTERCOM_PERSONAL_ACCESS_TOKEN：Intercom集成设置中的“Personal Access Token”。必需。
INTERCOM_SECRET_KEY：Intercom安全模式提供的密钥。可选，但强烈推荐。

请注意，如果您向任何人泄露了您的密钥，他们可以冒充您的应用程序用户并与您的支持团队聊天，因此请确保密钥安全！App ID不太敏感，因为它位于您网站的HTML源中。

我建议您启用Intercom的“测试版本”。这将为您提供第二个App 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"
]);

此外，您可以将多个字段放入一个名为“note”的单个字段中，供Intercom中的用户使用。此映射以应 precede 每个字段值的前缀标签为键。

$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的https://github.com/unclecheese/silverstripe-intercom-userforms模块。

维护者

Sam Minnée sam@silverstripe.com

错误追踪器

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

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

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

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

开发和贡献

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

silverstripe / intercom

维护者

详细信息