Marketing Automation Module

This module is used to integrate Marketing Automation into the portal.

1 Overview

This module consists of three widgets and one controller. The widgets are the following:

  • MarkaTrackingWidget – Used to track page views.
  • MarkaSuggestionsWidget – Used to asynchronously retrieve and display suggested pages for a user.
  • MarkaPersonaInfoWidget – Used to retrieve and display the current persona of a user.

The controller is called SuggestionsController and handles the work of retrieving and rendering the suggested pages for the MarkaSuggestionsWidget.

Every user needs a unique ID to be identified by Marketing Automation. This ID is generated automatically by this module and stored in a cookie. When a user logs in, the ID from the cookie is stored to the database, if there is no Marketing Automation ID stored there yet, otherwise the ID from the DB is loaded and saved to the cookie to make sure that a registered user has the same ID even when not logged in.

2 Installation

First, make sure that you have set up Marketing Automation (see the installation guide here). You will need the tracker base URL (the URL where the tracker is reachable from the Internet and from the server that runs the portal, e.g. http://marka.gentics.com:8081) for the configuration of the portal.

If you are adding the Marketing Automation module to an existing portal installation, you have to run a database migration. If you are setting up a new portal installation, the DB migration will be run automatically.

In the /frontend/config/main.php file you will find the following configuration for the Marketing Automation module:


'marketingautomation' => array(
    // Module class location
    'class' => 'common.modules.marketingautomation.MarketingAutomationModule',
    // Determines if the MarkaTrackingWidget is enabled (if false, the tracking widget will not render anything 
    // and thus the Marketing Automation tracker will not be contacted by the client).
    'markaTrackingEnabled' => true,
    // Determines if the MarkaSuggestionsWidget is enabled (if false, the suggestions widget will not render anything
    // and will not contact the Marketing Automation tracker).
    'markaSuggestionsEnabled' => true,
    // The base URL of the Marketing Automation tracker.
    'markaTrackerBaseUrl' => 'http://localhost:8081',
    // The name of the cookie, where the user ID used by Marketing Automation is stored.
    'markaCookieName' => 'markaCookie',
    // The number of seconds, after which cached suggested page infos will expire (default is 10 minutes).
    'cacheTime' => 600,
    // An optional array of page attributes, which should be retrieved for each
    // suggested page and passed on to the view in addition to 'name' and 'url'.
    // Note that these attributes are CMS attributes like 'filename' or 
    // 'publishdate', not Marketing Automation attributes. For example:
    // array('folder_id', 'edittimestamp')
    // A value of NULL means that only 'name' and 'url' will be retrieved.
    'suggestionsAdditionalPageAttributes' => NULL,
    // This array is used to configure which iMarkaPageInfosProvider should be used to obtain page infos
    // (for the suggestions) for which Marketing Automation page ID prefix. The entries in the array have to
    // be of the form 'markaIdPrefix' => 'path.of.the.PageInfosProviderClass'
    // Each provider must implement the common.modules.marketingautomation.components.iMarkaPageInfosProvider interface.
    // Note that there can be a problem if there is a prefix, which is itself  
    // a prefix of another prefix, e.g., prefix1: 'a', prefix2: 'ab'. In this case all pageIds that start with
    // 'a' will be passed to the provider for prefix1. To make sure that this scenario works correctly, the provider
    // for prefix2 has to be placed in the array before the provider for prefix1.
    'pageInfosProviders' => array(
        // This is an example for a provider for the 'ab' prefix:
        // 'ab' => 'custom.modules.marketingautomation.components.AbMarkaPageInfosProvider',
        // This is the default provider, to which all page IDs will be passed, which do not go to any of
        // the other providers.
        '' => 'common.modules.marketingautomation.components.ContentRepositoryMarkaPageInfosProvider'
    )
)

The markaBaseUrl needs to be set to the tracker base URL described previously, the other parameters need not necessarily be modified.

The SuggestionsController, which is contacted by the MarkaSuggestionsWidget, retrieves infos about the suggested pages using the content connector. To improve performance, the infos for a page are cached for a certain time. The cacheTime parameter specifies for how many seconds the infos for a page should be cached.

If your network architecture does not allow the Marketing Automation tracker to be reachable from the Internet, you can set up a proxy in Apache. To do this, add the following to your Apache config:


ProxyPass /tracking http://localhost:8081/
<Location /tracking>
        Order allow,deny
        Allow from all
</Location>

After this, set the markaTrackerBaseUrl to http://domain/tracking, where domain is the address, where your system is reachable from the Internet and from the portal.

If tracking is done using the GET method (default – more on this in section MarkaTrackingWidget), any parameter strings (e.g., attribute names), which contain a ‘/’ character will cause problems with an Apache proxy. In the default configuration, Apache will respond for security reasons with a 404 error if a URL path contains encoded slashes. If you are running Apache version 2.3.12 or later, you can set the AllowEncodedSlashes directive to NoDecode in your Apache config to make Apache pass the encoded slashes on to the Marketing Automation tracker. If you are running an older version of Apache or if you do not want to modify AllowEncodedSlashes, you have to modify either the MarkaTrackingWidget_get view or the MarkaTrackingWidget class to replace the slashes with some other character in the strings, which may contain them. The following code will replace slashes with backslashes in the string $param (which works if Apache is running on Linux, on Windows you have to choose a different character):


    if (strpos($param, '/') !== false) {
        $param = str_replace('/', '\\', $param);
    }

To get the display information for the suggested pages, page infos providers are used. Each page infos provider must implement the iMarkaPageInfosProvider interface (see /common/modules/marketingautomation/components/iMarkaPageInfosProvider.php). The default provider (ContentRepositoryMarkaPageInfosProvider) uses the content respository to get the information about the pages. Multiple providers can be configured. To add additional providers, create a class, which implements the iMarkaPageInfosProvider interface and add it to the pageInfosProviders associative array in the configuration (see the comments in the config code above). Marketing Automation page IDs are further described in the parameters of the MarkaTrackingWidget and the creation of a custom page infos provider is described in Custom Page Infos Providers.

3 MarkaTrackingWidget

The MarkaTrackingWidget needs to be included on every page that should be tracked by Marketing Automation.

Example of usage:


<?php
    $this->widget('marketingautomation.widgets.MarkaTrackingWidget', 
        array(
            'pageId' => '4711', 
            'attributes' => array(
                'attr1' => 1.0, 
                'attr2' => 1.0
            ),
            'categories' => array('category1', 'category2'),
            'method' => 'POST'
        )
    );
?>

The following parameters are supported:

  • pageId – The ID of the page that should be tracked. This is not the CMS page ID, but an ID that is only used for Marketing Automation. The possible compositions of this ID depend on the pageInfosProviders, which have been set in the configuration. To work with the default page infos provider for the content repository, the ID must be a string of the following format:
    • for pages without a channel ID: CMSPageID (e.g. ‘1234’ or ‘4923’)
    • for pages with a channel ID: 'c' . ChannelID . '.' . CMSPageID (e.g. ‘c2.1234’ or ‘c8.4923’)
  • attributes – The array (map) of the attributes of the page that should be tracked. The array must map each attribute name to a number, which is greater than or equal to 1.0. Example: array('attr1' => 1.0, 'attr2' => 1.0)
  • categories (optional) – The array of the categories of the page that should be tracked. This is optional and if set, it must be a list of strings, e.g. array('category1', 'category2')
  • method (optional) – The method that should be used for tracking. This can be either ‘GET’ or ‘POST’. If ‘GET’ is specified, a tracking pixel will be rendered (an image with style=“display:none;”, which has all tracking information embedded in its src URL) and if ‘POST’ is specified, a POST request will be made using AJAX. If this parameter is not specified, ‘GET’ is used.

For convenience the widget will not produce an error if some (but not all) of the attributes are invalid. Attributes with empty names or non numeric values are removed and if an attribute name contains the ‘.’ character, that character is replaced with an ‘_’ character and if an attribute value is less than 1.0, it is replaced with the value 1. The ‘.’ restriction is because Marketing Automation does not support the ‘.’ character, due to a restriction of ElasticSearch and values less than 1.0 are disallowed, because the Marketing Automation clustering algorithm requires values greater than or equal to 1.0.

4 MarkaSuggestionsWidget

The MarkaSuggestionsWidget is used to display page suggestions for a user on a page. The widget renders a DIV block, which initially only contains some JavaScript, which will make a GET request to the SuggestionsController to asynchronously load page suggestions for the user. The controller will contact the Marketing Automation tracker to retrieve suggestions and then use the content connector and the cache to get the required information for all pages and render them. The rendered links are then sent back to the JavaScript code rendered by the MarkaSuggestionsWidget, which will place the links into the DIV block.

4.1 Usage

Example of usage:


<?php
    $this->widget('marketingautomation.widgets.MarkaSuggestionsWidget',
        array(
            'suggestionsCount' => 4,
            'categories' => array('category1', 'category2'),
            'currentPageId' => '4711',
            'view' => 'MarkaSuggestionsSimpleLinksList'
        )
    );
?>

The following parameters are supported:

  • suggestionsCount – The number of suggestions that should be retrieved.
  • categories (optional) – The array of categories that all returned suggestions must have (they may also have other categories as well). This is optional and if set, it must be a list of strings, e.g. array('category1', 'category2') If this is not set, no category filtering is performed.
  • currentPageId (optional) – The ID of the page, on which this widget is being used. It is a string with the same format as the pageId parameter of the MarkaTrackingWidget. If set, Marketing Automation will make sure that this page is not included in the returned suggestions. If not set, the current page might be included in the suggestions if the current page is being tracked as well and if the tracking request arrives at the server later than the suggestions request (in that case Marketing Automation does not know that the user has already seen this page) or if there are not enough unseen pages for this user (in this case random pages for the user’s persona are added to the suggestions and for these, the pages the user has already seen are not considered).
  • view (optional) – The view that should be used to render the suggestions. This is optional and if not set, the default (‘MarkaSuggestionsSimpleLinksList’) is used, which renders the suggestions as a bulleted list of links and renders nothing if no suggestions are returned by Marketing Automation.

4.2 Custom Views

If you want to customize the way the suggestions are rendered, you can implement a custom view and specify that as the view parameter for the MarkaSuggestionsWidget. Note that the views do not belong to the MarkaSuggestionsWidget, but to the SuggestionsController.

The view is passed the parameter suggestedPages, which is an array of the suggested pages infos in the order they were provided by Marketing Automation (sorted by descending view count). Each of these objects is an associative array that contains the requested page attributes (‘name’ and ‘url’ are always included, further attributes need to be specified as the suggestionsAdditionalPageAttributes parameter in the configuration for the MarketingAutomation module). An example of a suggestedPages array, which is passed to the view would be:


array(
    array('name' => 'Soccer', 'url' => '/sports/Soccer.html'),
    array('name' => 'Basketball', 'url' => '/sports/Basketball.html')
)

If any of the requested attributes was not found for a page or was empty, the entry in the array will exist, but will be NULL.

If there were no suggested pages returned by Marketing Automation, the parameter suggestedPages will be NULL and it is up to the view to either not render anything or to render some default links.

4.3 Custom Page Infos Providers

The default page infos provider (ContentRepositoryMarkaPageInfosProvider) uses the content respository to get information about the suggested pages. If you want to use a different or additional information source, you have to implement a custom page infos provider and add it to the pageInfosProviders associative array in the configuration.

Each page infos provider must implement the iMarkaPageInfosProvider interface (located in /common/modules/marketingautomation/components/iMarkaPageInfosProvider):


interface iMarkaPageInfosProvider
{
    /**
     * Retrieves the requested attributes for the specified Marketing Automation page IDs,
     * which have the prefix that this iMarkaPageInfosProvider handles,
     * and returns an associative array with all page infos found in the repository. Each 
     * Marketing Automation page ID from the markaPageIds array will be associated with one
     * page infos associative array. Each of these page infos arrays contains the requested page attributes
     * (e.g. array('name' => 'Soccer', 'url' => '/sports/Soccer.html') for the
     * corresponding page. If any of the attributes was not found for a page or was empty, the
     * entry in the array will exist, but will be NULL. If no attributes were found for a
     * particular page, there will be no entry for that page ID in the returned array.
     *
     * Note that this function does not interact with the cache in any way. The SuggestionsController
     * will first check if the page infos for a page ID are available in the cache and only if they are not,
     * add it to the array, which is passed to this function. The insertion of page infos into the cache
     * is also handled by the SuggestionsController.
     * 
     * @param array $markaPageIds the array of page IDs with this iMarkaPageInfosProvider's
     * prefix, as returned by Marketing Automation
     * @param array $pageAttributes the page attributes (CMS or repository attributes,
     * not Marketing Automation attributes) that should be retrieved for each page
     * @return array
     */
    public function getPageInfos($markaPageIds, $pageAttributes);
}

The default provider is located at /common/modules/marketingautomation/components/ContentRepositoryMarkaPageInfosProvider.php and can be used as a reference example. The ContentRepositoryMarkaPageInfosProvider default provider handles page IDs with the 'c' prefix and with no prefix. If you add a provider to the configuration, which should not be used as the default provider, it will only handle one prefix. However, if necessary, the default provider can be replaced as well. A custom provider should be created in the directory /custom/modules/marketingautomation/components (this directory does not exist by default).

5 MarkaPersonaInfoWidget

The MarkaPersonaInfoWidget is used to display the current persona of a user. It will display the ID and the name of the persona that the user currently has. Its operation is synchronous, that means it finishes rendering on the server after the response from the Marketing Automation tracker arrives. This widget is not meant to be used in ordinary web pages, but rather for informational or debugging purposes on special web pages.

Usage:


<?php $this->widget('marketingautomation.widgets.MarkaPersonaInfoWidget'); ?>