Marketing Automation Module

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

1 Overview

This module consists of two widgets:

  • MarkaTrackingWidget – Used to track page views.
  • MarkaSuggestionsWidget – Used to retrieve suggested pages for a user.

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',
    // 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
)

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

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.

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. It 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.

4.1 Usage

Example of usage:


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

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.
  • 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.
  • additionalPageAttributes (optional) – 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', 'editdate')

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.

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 additionalPageAttributes parameter). 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.