trialfireinc/tracker

Trialfire tracking module for Magento 2

v1.1.4 2023-04-11 22:39 UTC

Requires

• php: ^7.1.0 || ^8.0.0

OSL-3.0, AFL-3.0

README

This module adds support for Trialfire to Magento 2. In addition to normal behavioural tracking, the following events are also collected:

• Viewed Category
• Viewed Product
• Add to Cart
• Add to Whishlist
• Remove from Cart
• Started Checkout
• Completed Order
• Subscribed Newsletter
• Register an Account

Install

Install from Magento Marketplace

https://marketplace.magento.com/trialfireinc-tracker.html

Install from Command Line

1. Require the trialfireinc/tracker package. A list of version tags is available here.

php composer.phar require trialfireinc/tracker:v1.1.4

1. Enable the module.

bin/magento module:enable Trialfire_Tracker --clear-static-content
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy
bin/magento cache:clean

Configure

The only required configuration is the API key from your project in Trialfire. You can find the API key by logging in to your Trialfire account and navigating to Settings > Tracking Code and API key.

1. Open the Admin page for your store and navigate to Stores > Configuration, then click on the Trialfire tab.

2. Set the Enable Tracking field to Yes, and then input your API key into the API token field.

3. Save the configuration.

4. Flush the Configuration, Block HTML, and Full_Page caches. You can clear the caches from System > Cache Management or use the command bin/magento cache:flush config block_html full_page.

Advanced Configuration

Complete documentation is available here.

Custom Initialization

Customize how Trialfire tracking code is included into the DOM. The default implementation is similar to the following:

var s = document.createElement('script');
s.src = this.assetUrl;
document.head.appendChild(s);
Trialfire.init(this.apiToken);

The value of this for the custom initializer is the following.

{
  // The value of the Asset URL setting in your store's Trialfire configuration.
  assetUrl: '...',

  // The value of the API Token setting in your store's Trialfire configuration.
  apiToken: '...',                  

  /**
   * Call the default initialization logic.
   */
  callDefaultInit: function () ...  

  /**
   * Inject the Trialfire script into the DOM but do not call Trialfire.init().
   */
  injectScript: function () ...
}

To prevent Trialfire from loading on the 'agent' subdomain, input the following JavaScript into the Initialization Code textarea.

// If host does not start with 'agent'.
if (!location.host.startsWith('agent.myshop.com')) {
  // Invoke the default initialization logic.
  this.callDefaulInit();
}

Custom Event Handlers

Customize how Trialfire fires tracking events. The value of this for the custom event handler is the following.

this.event: An object containing information about the event. The contents vary with the event type but are similar to the following.

this.event = {
  $name: 'placeOrder',
  apiToken: '...',
  userId: 1,
  traits: {
    email: '...',
    firstName: '...'
  },
  props: {
    orderId: '...',
    products: [{
      id: '...',
      name: '...',
      sku: '...'
    },{
      ...
    }]
  }
}

this.tfMage: The service which tracks the events. It contains utility methods that you may use in your custom handler.

this.tfMage = {
  /**
   * Calls the default handler for an event.
   */
  callDefaultEventHandler: function (event) ...
};

Example:

To prevent Trialfire from tracking orders on the 'agent' subdomain, input the following JavaScript into the Place Order textarea.

// If host does not start with 'agent'.
if (!location.host.startsWith('agent.myshop.com')) {
  // Invoke the default handler for this event.
  this.tfMage.callDefaultEventHandler(this.event);
}