symbiote / silverstripe-local-personalisation
Builds a profile of a site user in their browser, to be used for content personalisation
Installs: 136
Dependents: 0
Suggesters: 0
Security: 0
Stars: 3
Watchers: 1
Forks: 2
Open Issues: 0
Language:JavaScript
Type:silverstripe-vendormodule
Requires
- silverstripe/framework: ^4.0
Requires (Dev)
- phpunit/phpunit: ^5.7
- squizlabs/php_codesniffer: ^3.0
This package is auto-updated.
Last update: 2024-10-08 07:37:38 UTC
README
Overview
Builds a profile of a visitor, "tagging" behaviour based on the pages visited, actions performed, location, or device characteristics. Preserves privacy since the profile is stored in the browser only, without relying on server data or logged-in user information.
This module enables marketers and developers to collaborate effectively, by providing both a CMS user interface and an API.
CMS users can define "rule sets" to group one or more "rules". Each rule determines when and how behaviour should be tagged. For example, "if URL contains 'marketing', then add 'interested-in-marketing' tag".
These tags can then be used for matching rules against objects managed in the CMS (such as pages or content blocks), and show/hide them based on in-browser decisions. Alternatively, you can control this behaviour programmatically, enabling sophisticated rule definitions that wouldn't be feasible in a CMS UI.
Because all decision making happens in the browser, you can still serve cached responses with all variations delivered to the browser, but only some variations shown to the visitor.
Example use cases:
- Show location-specific announcements on the homepage
- List featured products from the closest store (via browser geolocation)
- Show topic-specific content blocks based on the pages the visitor has previously viewed
- Show promotions for a specific marketing campaign, based on traffic coming in with a campaign URL parameter
- Hide welcome message if the visitor has seen it before
- Show "Contact helpdesk?" call-to-action if visitors view a FAQ entry for longer than 30 seconds
Limitations:
- All variations are visible to all visitors (for example, this can't be used for targeted promo codes)
- All decision making is visible in the browser (including any built-in bias and dodgy marketing tactics)
Installation
Composer
composer require symbiote/silverstripe-local-personalisation:~1.0
Javascript and CSS
Add the required frontend logic into your main template:
<% require javascript('symbiote/silverstripe-local-personalisation:app/dist/main.js') %>
<% require css('symbiote/silverstripe-local-personalisation:app/dist/main.css') %>
Alternatively, check app/webpack.config.js
on how to compile the requirements into your own frontend bundle.
Metadata
Personalisation rules are loaded as JavaScript metadata.
<script type="application/javascript" src="/__personalisation/rules"></script>
By loading this as a separate route, you avoid inline scripts and make it easier to secure your website with a Content Security Policy. It also helps with caching: Personalisation rules apply immediately on save, even when the page output might be cached (via HTTP caching or static publishing).
Apply the extension
In order for the frontend logic to be triggered, you generally want to apply an extension to at least one content object. This adds a new "Personalisation" tab in the CMS.
Apply on pages:
SilverStripe\CMS\Model\SiteTree: extensions: - Symbiote\Personalisation\PersonalisationExtension
Apply on content blocks:
DNADesign\Elemental\Models\BaseElement: extensions: - Symbiote\Personalisation\PersonalisationExtension
Modify templates
Now add some metadata to the markup for the content object you're rendering:
$p13nClasses
to your class
attribute, and $p13nAttributes
to the element.
Example for the content blocks holder template
(store in themes/mytheme/templates/DNADesign/Elemental/Layout/ElementHolder.ss
):
<div class=" element $SimpleClassName.LowerCase <% if $StyleVariant %> $StyleVariant<% end_if %> <% if $ExtraClass %> $ExtraClass<% end_if %> $p13nClasses.RAW " id="$Anchor" $p13nAttributes.RAW > $Element </div>
Test Operation
You should be ready to define rules now. Check for Profile.js
console messages in your browser
to ensure everything is set up correctly.
Developer Usage
Rules for profile segmentation
Rules are defined in the CMS
They can be triggered for;
- A regex match against content
Manually applying rules
By applying the PersonalisationExtension
to a content object,
you can use $p13nClasses
and $p13nAttributes
in your templates.
Alternatively, you can build the required markers from scratch:
- add the
lp-item css
class - Add the
data-lp-tags
attribute to list (comma separated) the tags applied on the profile to trigger this element - Add the
data-lp-type
attribute to indicate whether to "show" (default) or "hide" the element - Add the
data-lp-times
attribute (optional) to indicate how many times the user's profile has to have been tagged - Add the
data-lp-timeframe
attribute to indicate what timeframe (ie-1 week
) the tagging must have happened
<div class="this-thing lp-item" data-lp-tags="route-detail" data-lp-times="5" data-lp-type="hide">
<h1>What this is</h1>
</div>
Events
The following events are triggered and can be responded to in custom code
local_profile_match_tag
local_profile_apply_rule
local_profile_add_tag
Bind to these as document.addEventListener('local_profile_add_tag', function (eventData) {})
Local Development
Build
The frontend assets are stored in app/
.
You can use yarn
to install dependencies and kick off a build:
cd app/
yarn install
yarn build
Javascript, HTTPS and hot reloading
To fully test the functionality locally, you'll need to run your webserver on HTTPS which is required for geolocation in most browsers now.
When developing the Javascript code for the module, it can be helpful
to get source maps (breakpoints!) and hot reloading. The module already
has a yarn devserver
command. You'll need to extend the webpack.config.js
to work around CORS issues when including it in your page
(see webpack devserver docs).
module.exports = { // ... devServer: { disableHostCheck: true } };
Now you can use the dev server (usually on port 4200
)
with the preferred hostname for your Silverstripe website:
<script src="https://your-hostname:4200/main.js" type="application/javascript"></script>
Caution: In order to use geolocation without HTTPS in Chrome, you need to allow insecure origins.