Personalization

JavaScript API event notifications

Personalization provides event notifications for decision handling. Whenever an event triggers, the notification can enable custom JavaScript to use that trigger to provide more features.

Note

The acquiaLiftStageCollection event will broadcast after the /decide request returns and regardless of whether personalized content exists.

You can trigger the following events:

Event

Description

acquiaLiftDecision

Triggers when a decision is received and processed. The content may still be in the rendering process, but data is available and processing is complete

acquiaLiftContentAvailable

Triggers when a decision’s content has been rendered by the browser and is available for manipulations or query

acquiaLiftContentCustomizable

Triggers when AcquiaLiftPublicApi.customize() is called: contains all the decisions and their contents in customizable slots.

acquiaLiftClickThrough

Triggers when decision content is clicked

acquiaLiftRuleUpdate

Triggers when content is added to or updated in a slot

acquiaLiftStageCollection

Triggers after each /decide request returns and regardless of whether personalized content exists.

Details

For acquiaLiftDecision, acquiaLiftContentAvailable, and acquiaLiftClickThrough, each event has a detail property, which can include the following available information about the decision:

Detail

Description

decision_campaign_id

The unique ID of the rule’s campaign

decision_campaign_name

The descriptive name of the rule’s campaign

decision_content_id

The ID of the content displayed

decision_content_name

The title of the content displayed

decision_policy

The decision policy used to make the decision

decision_rule_ab_variation

The name of the AB test rule’s chosen variation

decision_rule_ab_variation_id

The ID of the AB test rule’s chosen variation

decision_rule_id

The ID of the rule used to replace content

decision_rule_name

The name of the rule used to replace content

decision_rule_segment_id

The ID of the segment on which the rule triggers

decision_rule_segment_name

The name of the segment on which the rule triggers

decision_rule_type

The type of rule used. Examples include ab for A/B and target for targeting

decision_slot_id

The ID for the slot where content was replaced

decision_slot_name

The name of the slot where content was replaced

decision_view_mode

The ID of the layout of the content displayed

For acquiaLiftContentCustomizable, each event has the following properties.

Detail

Description

contents

An array of content pieces, with each content piece containing base_url, html, and id. base_url is the content publishing website’s base URL; html is the content markup, and id is the id of the content.

slot_css_selector

As configured in the slot, the CSS selector to find the slot, if it exists, on the page.

Examples

You can use the following code examples to provide more customization on your website:

Example: decision event

window.addEventListener('acquiaLiftDecision', function(e) {
console.log('received decision event for ' + e.detail.decision_slot_id + ' slot');
});

In the previous example, acquiaLiftDecision is the event, and decision_slot_id is the detail property. Both variables are replaceable by other values, as explained in the following sections.

To customize your personalized content pieces, use code like the following:

// Define a callback function for "acquiaLiftDecision" event.
window.addEventListener('acquiaLiftDecision', function(e) {
   // e.detail has decision's information. If the decision isn't our target "My Carousel Slot", early exit.
   if (e.detail.decision_slot_name !== 'My Carousel Slot') {
      return;
   }
   // For example, you can select all content pieces within a slot, and wrap each one of them by a <div>.
   jQuery('[data-lift-slot="' + e.detail.decision_slot_id + '"] > *').wrap('<div style="border: 1px solid red;" class="my-carousel-item"></div>');
});

If your website uses custom JavaScript (such as slideshows, modal windows, or custom lists), you may need code to both listen for the returned decision and reinitialize your JavaScript library. The following example uses the Chosen library:

window.addEventListener('acquiaLiftDecision', function(e) {
console.log('received decision event for ' + e.detail.decision_slot_id + ' slot');
console.log("Loaded");

$selectItems = jQuery('.form-item select');
$selectItems.delay(1000).chosen({
   disable_search_threshold: 5,
   no_results_text: "No Results Found.",
   width: "100%"
}).prop('disabled', false).trigger("chosen:updated");
});

Example: Other ways to reinstantiate JavaScript on a Personalized element

Alternative approaches depending on the JS APIs available to the customer site.

window.addEventListener('acquiaLiftDecision', function(event) {
  /*
    First, check that this is the correct slot to work on.
    The event detail contains the slot id and name:
    - `event.detail.decision_slot_id`
    - `event.detail.decision_slot_name`

   In the example below, the slot was named 'My Slot' when it was created.
  */
  if (event.detail.decision_slot_name === 'My Slot') {
    /*
      Next, select the HTML element that is the slot.

      This shows two ways to select the slot's HTML element:
      - using vanilla JS
      - using jQuery
    */
    // Vanilla JS method to select the slot's HTML.
    const slotElement = document.querySelector(`[data-lift-slot="${event.detail.decision_slot_id}"]`);

    // Using jQuery to select the slot's HTML.
   const slotElementJQ = $(`[data-lift-slot="${event.detail.decision_slot_id}"]`);

    /*
      Finally, act on the slot HTML element.
      The JS code to apply will be some API method.
      JS libraries do not all operate the same way.

      Some examples are show below.
    */

    // An example of APIs that act directly on HTML elements:
    someApiMethod(slotElement);

    // Example for Slick, with an options object to define the carousel's properties:
    slotElementJQ.slick(options);
   }
 });

Simplified approach:

window.addEventListener('acquiaLiftDecision', function(event) {
  /*
    First, check that this is the correct slot to work on.
    The event detail contains the slot id and name:
    - `event.detail.decision_slot_id`
    - `event.detail.decision_slot_name`

    In the example below, the slot was named 'My Slot' when it was created.
  */
  if (event.detail.decision_slot_name === 'My Slot') {
    /*
      Next, select the HTML element that is the slot.
    */
    const slotElement = document.querySelector(`[data-lift-slot="${event.detail.decision_slot_id}"]`);

    /*
      Finally, act on the slot HTML element.
      JS libraries do not all operate the same way, consult their documentation.
    */
  }
});

Example: acquiaLiftContentCustomizable event

window.addEventListener('acquiaLiftContentCustomizable', function(event) {
// Console to show the customizable decision content.
console.log('acquiaLiftContentCustomizable', event.detail);
});

To customize your personalized content pieces using decision data, use code like the following:

window.addEventListener('acquiaLiftContentCustomizable', function(event) {
// Console to show the customizable decision content.
console.info('acquiaLiftContentCustomizable', event.detail);
// Process decisions.
var decisions = event.detail;
Object.keys(decisions).forEach(function(slotId) {
   // Process a decision.
   var decision = decisions[slotId];
   var html = decision.contents.reduce(function(html, content) { return html + content.html }, '');
   var slotElement = document.querySelector(decision.slot_css_selector);

   if (!slotElement) {
      console.warn('Decision on slot "' + slotId + '" has HTML "' + html + '", but slot is not on the page.');
      return;
   }

   // Empty out the element.
   while (slotElement.hasChildNodes()) {
      slotElement.removeChild(slotElement.lastChild);
   }

   // Set the customizable content to the target element's innerHTML.
   slotElement.innerHTML = html;
});
});

Example: acquiaLiftRuleUpdate event

When a slot is updated with new or updated content, this event triggers, calling the AcquiaLiftPublicApi.customize function to broadcast decisions.

window.addEventListener("acquiaLiftRuleUpdate", function(){
AcquiaLiftPublicApi.customize();
});