Tracking Fusion Signals

Appkit provides support for the Fusion REST Signals API, allowing user clicks and the creation of annotations (bookmarks, topics etc) to be recorded and tracked.

Incorporate signals

This section describes how to incorporate Fusion Signals activity tracking into your Appkit application.

1. Add the Fusion Signals dependency

Signals tracking in Fusion requires the Fusion Signals module. To enable this module, insert these within the dependencies tag of your pom.xml:

<dependency>
    <groupId>twigkit</groupId>
    <artifactId>twigkit.activity.tracker</artifactId>
    <version>${project.parent.version}</version>
</dependency>


<dependency>
    <groupId>twigkit</groupId>
    <artifactId>twigkit.message.service.fusion.producer</artifactId>
    <version>${project.parent.version}</version>
</dependency>

2. Add fusion.conf to activity tracking resources

To access this module when Appkit starts up, create a fusion.conf file in resources/conf/message/service/fusion.conf. In that file, configure the query-profile. This is the REST-API endpoint that will ingest signal data into a signals collection. For example:

query-profile: my-query-profile
signals-index-pipeline: _signals_ingest
commit: true
async: true

Fusion Signals config

Here, image_catalog is the name of a primary collection that will be used to generate an auxiliary collection consisting of activity tracking data.

When accessing Fusion using a service account, the credentials will be pulled from the configuration given in the services/api/fusion.conf file, which should contain these parameters to enable basic authentication:

impersonate: true
userName: joebloggs
password: Enc(<encoded password>)

For more information about how authentication is used when accessing the Fusion Signals endpoint, see the Authentication section below.

Several optional parameters are also provided as shown. The first, signals-index-pipeline, can be used to define an index pipeline that will to be used to convert the raw JSON signal data into a set of Solr documents. As stated in the Fusion Signals API documentation, if no pipeline is defined, then the preconfigured _signals_ingest pipeline will be used. Both the remaining two parameters, commit and async, are booleans. If commit is set to true, a Solr commit will occur at the end of indexing allowing a persistent record of the activity to be kept. If async is set to true, signals will be indexed in asynchronous mode. In this mode, an autoCommit is issued with each signal and failures are not reported. The default is false.

Creating a collection for signals tracking

Using the Fusion UI, when a primary data collection is created, this also creates a collection for the signals. By default, the name of this signals collection is by <primary collection>_signals, where <primary collection> should be substituted with the name of the primary data collection. After data has been indexed and ingested into the primary collection, the Appkit Fusion Signals module can be used to populate the signals collection.

Tracking user clicks and annotations

Currently, Appkit will send information on user clicks that trigger URL requests as well as when a user creates an annotation, for example, a bookmark or comment.

A signal event of type click will include, amongst other things, information about the URL that was clicked as well as the number of times that URL was clicked.

A signal event of type annotation will include, amongst other things, information about the annotation target, the collection, and the creator.

For a full list of properties that are stored, refer to the signals collection associated with your application.

Authentication

Service account impersonation requires credentials for the service account and these are stored in the Fusion platform configuration. These credentials will be pulled from the configuration given in the services/api/fusion.conf file.

If the credentials for a service account are not provided or cannot be found, a check will be made to see if a Fusion session cookie is available. Typically, this will be present when the user is known to the Fusion server and the Session API has been set up accordingly.