, (*1)
This module provides SilverStripe integration for Intercom., (*2)
Requirements
- SilverStripe Framework 4.0 or higher (3.x support in
1.x branches and tags). Works nicely with the CMS but it isn't required.
- PHP >=5.6.0
Installation
Install the module with composer, just like all your favourite modules!, (*3)
composer require silverstripe/intercom
Documentation
You can find detailed documentation in the docs folder., (*4)
License
See license.md, (*5)
How it works
Intercom's integration is quite simple: a few lines of JavaScript added just before the </body> tag.
The module adds through its own RequestFilter., (*6)
Configuration
The module will make use of the following global constants in your .env file. You should
set these up:, (*7)
-
INTERCOM_APP_ID: The "App ID" from Intercom's integration settings. Required.
-
INTERCOM_PERSONAL_ACCESS_TOKEN: The "Personal Access Token" from Intercom's integration settings. Required.
-
INTERCOM_SECRET_KEY: The secret key given by Intercom's Secure Mode. Optional, but highly recommended.
Note that if you disclose your secret key to anyone, they could impersonate users of your app and chat to
your support team, so keep it secure! The App ID is less sensitive as it is in the HTML source of your
site., (*8)
I recommend that you enable the "Test Version" of Intercom. This will give you a second App ID that
you should use on your test and development environments., (*9)
Your application can customise the information send with the following properties, (*10)
SilverStripe\Intercom\IntercomScriptTags:
anonymous_access: true
company_property: Organisation
company_fields:
name: Title
plan: AccountPlan
user_fields:
favourite_colour: FavouriteColour
-
anonymous_access: If true, then the integration code will be supplied even for anonmyous visitors.
This is used for Intercom Acquire.
-
always_anonymous: If true, then the integration code will never be populated with the details of the current user. Allows better caching.
This is used for Intercom Acquire.
-
company_property: The property on a member that points to their organisation
-
company_fields: A map of Intercom field name to organisation properties to pass through
-
user_fields: A map of Intercom field name to member properties to pass through
The SilverStripe\Intercom\IntercomScriptTags class has a configuration value, enabled, that
can will disable any inclusion of Intercom script tags if set to false., (*11)
If you wish to show Intercom only sometimes, you can update this configuration value at any time during
your page load, with the following command. For example, you may choose to show Intercom only on certain
pages, or for certain users., (*12)
\SilverStripe\Intercom\IntercomScriptTags::config()->enabled = false;
Usage
Tracking events
You can track events with the Intercom::trackEvent() method. The event will be tracked against the
current user., (*13)
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',
));
You can also explicitly specify which user this event should be tracked against:, (*14)
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));
Note that you can't currently track events for anonymous visitors; a LogicException will be thrown if
you try., (*15)
Synchronising users via the API
Sometimes, it's not enough to wait until users log in to have their Intercom data updated. For example, if
you want to use Intercom to send emails you may want to update the Intercom database before the first email
is sent., (*16)
For this purpose, you can set dev/tasks/IntercomBulkLoadTask to run on a cronjob. By default it will
synchronise all Member objects. If you wish to synchornise a reduced list of Members, you can set the
user_list config option on the Intercom class. This should be of the form %$ServiceName, where ServiceName
is the name of an Injector service., (*17)
SilverStripe\Intercom\Intercom:
user_list: %$AllPlatformUsers
SilverStripe\Core\Injector\Injector:
AllPlatformUsers:
factory: AllUserListFactory
In the preceding example, we're using a custom factory class called AllUserListFactory to define Member DataList.
It needs to have a method called create() that returns a DataList of Members., (*18)
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']);
}
}
To send data to Intercom from a form, you can use SilverStripe\Intercom\IntercomFormExtension., (*19)
SilverStripe\Forms\Form:
extensions:
- SilverStripe\Intercom\IntercomFormExtension
This will provide several chainable methods to the Form class that help you map form fields to
Intercom fields., (*20)
$form
->addIntercomUserFieldMapping([
'FullName' => 'name',
'EmailAddress' => 'email'
])
->addIntercomCompanyFieldMapping([
'CompanyName' => 'name'
])
->sendToIntercom();
For custom attributes, prefix the field name with $., (*21)
$form->addIntercomUserFieldMapping([
"FavouriteColour" => "\$favourite_color"
]);
Additionally, you can stuff assorted fields into a monolithic "note" for the user in Intercom. This map is
keyed with labels that should precede the values for each field., (*22)
$form
->addIntercomNoteMapping([
'SoftwareVersion' => 'The user is running version:'
])
->setIntercomNoteHeader('More information about this user');
The above will create a note similar to:, (*23)
<p>More information about this user</p>
<ul>
<li>The user is running version: ${SoftwareVersion}</li>
</ul>
See the silverstripe-intercom-userforms module by Uncle Cheese., (*24)
Maintainers
Bugtracker
Bugs are tracked in the issues section of this
repository. Before submitting an issue please read over existing issues to ensure yours is unique., (*25)
If the issue does look like a new bug:, (*26)
- Create a new issue
- Describe the steps required to reproduce your issue, and the expected outcome. Unit tests, screenshots
and screencasts can help here.
- Describe your environment as detailed as possible: SilverStripe version, Browser, PHP version,
Operating System, any installed SilverStripe modules.
Please report security issues to the module maintainers directly. Please don't file security issues in the bugtracker., (*27)
Development and contribution
If you would like to make contributions to the module please ensure you raise a pull request and discuss with the module maintainers., (*28)
Wallogit.com
