Developers
Help CenterCommunityStatus

Zone configuration for MPA

Zone configuration for MPA

Suggest Edits

You have installed the Personalization Library. Next, you want to set up the zones of your MPA website to display the personalized content or recommendations. Let's see in this topic how you can achieve this goal.

MPA Zone configuration using Stable version (v1.5.0)
MPA Zone configuration using Latest version

📘

The code snippets, including the function names, method names, variables, etc., provided in this topic are for guidance, and the channel developer can modify them as per their channel-specific implementation.
As a best practice, the updates to Personalization Library should first be validated in a non-Production environment before upgrading the Production website.

Prerequisites

  • Ensure that you have specified the appropriate version URL in the Personalization Library text box in Exchange Capture. For more information, see Install Personalization Library for MPA
  • The channel must have the Acoustic Exchange scripts and the scripts for an analytics library embedded. For more information about how to configure Acoustic Exchange and an analytics library of your choice (such as Adobe Analytics, Google Analytics or Digital Analytics), see Acoustic Exchange Configuration.

MPA Zone configuration with Stable version (v1.5.0)

Create a <script> tag, either in the parmname HEAD tag or in the BODY tag of the MPA page that has the zones to be personalized. Inside this script tag, add the following code snippets as described below.

  1. Create an object personalizationObject to load the Personalization Library. The acoustic object is created by Acoustic Exchange.
const personalizationObject = acoustic.personalization.JsWRTP.create();
  1. Next, write a function displayContent that takes in two parameters:
  • ContentID = ID of the personalized content (for example, an image) that will be displayed.
  • domOutlet = Outlet ID (usually the div id) of the page that has the registered zone.

Inside the displayContent, add IF-ELSE blocks with the code to render personalized content, and if it fails, the default content.

function displayContent(contentId, domOutlet) {  
   if (contentId == 'DCIDNF404') {
   //Add rendering logic code to display the default content
   domOutlet.style.opacity = 1;
   } else {  
   //Add rendering logic code to display the personalized content
   domOutlet.style.opacity = 1;
  }
}
  • The error code DCIDNF404 is returned when no published rules are available or when none of the
    published rules match the visitor behavior on the channel. In such case, Acoustic Personalization
    does not return any personalized content. The channel must handle this scenario by specifying a
    default content to be displayed. For more information about error codes, see Personalization Library
    error codes
  • The code domOutlet.style.opacity = 1; is for handling the content flicker on channel. You can choose to handle the content flicker using a different approach. For more information about content flicker, see Handling the content flicker.
  1. Next, write the function processContent. This function takes in the parameters zoneID and OutletID declared earlier and processes them.
function processContent(zoneId, outletId) {
   const outletArea = personalizationObject.getZoneArea(outletId);                                
   let contentId    = personalizationObject.getContentId(zoneId);
   displayContent(contentId, outletArea); 
  }
  1. Next, add the OnReady function as shown below.
personalizationObject.onReady(()=>{
    // Repeat this line of code for each new zone to be personalized.  
    processContent("<<Zone ID>>", "<<outlet>>");
      });
  • Replace ZONE ID with the registered zone ID.
  • Replace OUTLET with the outlet ID (usually the div id) of the page that has the registered zone.

So, your complete code structure would look similar to the following code snippet.

<script type="text/javascript">
  function init() {
    if (acoustic != undefined || acoustic != {}) { 
      const personalizationObject = acoustic.personalization.JsWRTP.create();

      function displayContent(contentId, domOutlet) {  
         console.log('ContentId in HTML file:', contentId);
         if (contentId == 'DCIDNF404') {
         //Add rendering logic code to display the default content
         domOutlet.style.opacity = 1;
         } else {  
         //Add rendering logic code to display the personalized content
         domOutlet.style.opacity = 1;
         }
      }
      function processContent(zoneId, outletId) {
         const outletArea = personalizationObject.getZoneArea(outletId);
         let contentId    = personalizationObject.getContentId(zoneId);
         displayContent(contentId, outletArea); 
         }
      personalizationObject.onReady(()=>{
      processContent("<<Zone ID>>", "<<outlet>>");
      });
    } else {
       console.log("Error in loading the personalization library.");
     }
 }
 window.onload = init;
</script>

MPA Zone configuration with Latest version

You can use this procedure for personalization library versions 2.0.0, 2.1.0, and 2.2.0.

  1. Open the HTML webpage that contains the zone you want to be personalized. Add a 
<script type="text/javascript">
    //Step 2 goes here
</script>
  1. Within this script tag, initialize the Personalization Library. You do this to import the Personalization Library objects.
var init = (function () {
  //Add step 3 here
});
  1. In this step, you add a check to ensure that the Personalization Library is loaded successfully and you can access the acoustic object. Otherwise, you will see error message in the console log.

📘

Tip

If you cannot retrieve the acoustic object, it means that Personalization Library is not installed successfully in your environment. In this case, perform the steps to install Personalization Library.

if (acoustic != undefined || acoustic != {}) {
   //Add steps 4 to 8 here
} else {
    console.log("Error in loading Personalization Library.");
}
  1. Create an object personalizationObject. You do this to access the Personalization Library functions.
var personalizationObject = acoustic.personalization.PersonalizationLibrary.create();
  1. Create a DOM element validator. This validator checks whether the zone to be personalized exists on the HTML page. If the zone is not a valid HTML element, you will see an error message.
var validateDOMElement = function (outlet) {
    var outletDiv = document.getElementById(outlet);  
    if (!(outletDiv instanceof Node)) {
        console.log(outlet, " is not a valid HTML element.");
        return null;
    }
    return outletDiv;
};
  1. Next, you add a SWITCH case handler. In this handler, you add the processing logic for various content types. The following content types are currently supported: 
var personalizationHandler = function(result, targetArea)
 {
    switch(result.type) {
        //Use to display product recommendations on the zone
        case "recommendation": 
            displayRecommendations(result, targetArea);
            break;
        //Use to display personalized content from the specified web URL
        case "custom-url":
            displayCustomUrl(result, targetArea);
            break;
        //Use to fetch personalized content from the specified web page
        case "custom-html":
            displayCustomHtml(result, targetArea);
            break;
        //Use to fetch personalized content as HTML from Acoustic Content
        case "wch-url":
            displayWchUrl(result, targetArea);
            break;
        //Use to fetch personalized content as a URL from Acoustic Content
        case "wch-html":
            displayWchHtml(result, targetArea);
            break;
        //Use to display the default content
        case "":
            displayDefaultContent(result, targetArea);
            break;
        }
}

Helper functions to support content types

The SWITCH case handler we just added in turn calls the relevant helper functions that support content types such as default content, HTML, URL, and recommendations. For reference, the following code snippet provides the definitions of these helper functions. These helper functions are located inside the personalizationHandler() function. 

var displayDefaultContent = function (result, targetArea) {
    // Display the default content
    targetArea.style.opacity = 1;
}

var displayCustomUrl = function (content, targetArea) {
    var contentId = content.value
    if (contentId && contentId !== 'CONNF404' && targetArea) {
        // Display the personalized content
        targetArea.style.opacity = 1;
    } else {
        displayDefaultContent(content, targetArea);
    }
}
var displayWchUrl = function (content, targetArea) {
    var contentId = content.value
    if (contentId && contentId !== 'CONNF404' && targetArea) {
        // Display the personalized content
        targetArea.style.opacity = 1;
    } else {
        displayDefaultContent(content, targetArea);
    }
}

var displayCustomHtml = function (content, targetArea) {
    var contentId = content.value
    if (contentId && contentId !== 'CONNF404' && targetArea) {
        // Display the personalized content
        targetArea.style.opacity = 1;
    } else {
        displayDefaultContent(content, targetArea);
    }
}
var displayWchHtml = function (content, targetArea) {
    var contentId = content.value
    if (contentId && contentId !== 'CONNF404' && targetArea) {
        // Display the personalized content
        targetArea.style.opacity = 1;
    } else {
        displayDefaultContent(content, targetArea);
    }
}

var displayRecommendations = function (products, targetArea) {
    var recommendations = products.value;
    if (recommendations && recommendations !== 'CONNF404' && targetArea) {
        // Display the personalized recommendations
    } else {
        // Display the default recommendations
        displayDefaultContent(products, targetArea);
    }
}
  1. Add the onReady callback function. This function ensures that the Personalization Library has loaded the required files and is ready for processing.
personalizationObject.onReady(function() {

 // Add step 8 here
 
});
  1. Configure the personalized zones. You do this to see the personalized content on the zones. You can use any of the two approaches described here.

  • Approach 1: Using custom attributes
    Use this approach if you want to dynamically access the defined values from the HTML. This approach requires you to make changes to the div tag of the zone.

  • Approach 2: Without Using custom attributes
    Use this approach when you want to make minimal changes to the div tags of your website. In this case, Personalization business logic manages the complete processing.

Approach 1: Using custom attributes

In the onReady callback, add the code to specify the attributes and their values to be fetched dynamically.

personalizationObject.onReady(function(){
    var zones = document.querySelectorAll('[custom-pzn]');
    zones.forEach(function(value) {
        var zoneObj = {
            "zoneId": value.getAttribute('custom-pzn-zone-reg-id'), 
            "targetArea": value.getAttribute('custom-pzn-target-area'), 
            "num": value.getAttribute('custom-pzn-product-number')
        };
        
        var validElement = validateDOMElement(zoneObj.targetArea)
        if(validElement) {
            personalizationObject.getContent(zoneObj)
            .then(function(result) {
                personalizationHandler(result, validElement) 
            });
          }
    });
});

Changes to HTML file using Approach 1: Open the HTML file of your MPA zone on which you want to show content personalization or product recommendations. Add the following snippet to it. 

<div>
    <div id="<ZONE_ID>" wrtp-recommended-zone="<ZONE_ID>"
    custom-pzn
		custom-pzn-zone-reg-id="<ZONE_ID>"
		custom-pzn-target-area="<ZONE_ID>[CAN_BE_SAME_AS_<ZONE_ID>]"
		custom-pzn-product-number="<NUMBER_OF_PRODUCTS_REQUIRED>[OPTIONAL]">
    </div>
</div>
  • Replace ZONE ID with the registered zone ID.
  • Replace ZONE_AREA with the outlet ID (usually the div id) of the page that has the registered zone.
  • Replace <<NUMBER_OF_PRODUCTS_REQUIRED(OPTIONAL)>> with the maximum number of recommended products to be displayed on the zone. For example: "10"
    This is an optional parameter.

Approach 2: Without using custom attributes

Use this approach to access the values from the business logic. 

personalizationObject.onReady(function(){
   var zones = [
                    {
                        "zoneId": "ZONE_ID_1",
                        "targetArea": "ELEMENT_ID_2",
                        "num": "NUMBER_OF_PRODUCTS_[OPTIONAL]"
                    },
                    {
                        "zoneId": "ZONE_ID_2",
                        "targetArea": "ELEMENT_ID_2",
                        "num": "NUMBER_OF_PRODUCTS_[OPTIONAL]"
					},
                ]
                zones.forEach(function(zoneObj) {
                    
                    var validElement = validateDOMElement(zoneObj.targetArea)
                    if(validElement) {
                        personalizationObject.getContent(zoneObj)
                        .then(function(result){
                            personalizationHandler(result, validElement) 
                        });
                      }
                }); 
});

Changes HTML file: Locate the HTML file of your MPA zone on which you want to show content personalization or product recommendations. Add the following snippet to it. 

<div>
    <div id="<<ZONE_ID>>" wrtp-recommended-zone="<<ZONE_ID>>">
    <!-- Replace <<Zone_ID>> with the registered zone ID-->
    </div>
</div>

You have configured the zone of your MPA to display either personalized content or product recommendations.

Example code

So, your complete code would look similar to the following code snippet. This example uses Approach 1 for configuring the personalized zones.

// Step 1
<script type="text/javascript">
// Step 2
var init = (function () {
// Step 3
// get the personalization object
if (acoustic != undefined || acoustic != {}) {
// Step 4
// access the personalization object
var personalizationObject = acoustic.personalization.PersonalizationLibrary.create();
// Step 5
// Create a DOM Element validator for the identified zones in the client application
var validateDOMElement = function (outlet) {
    var outletDiv = document.getElementById(outlet);  
    if (!(outletDiv instanceof Node)) {
        console.log(outlet, " is not a valid HTML element.");
        return null;
    }
    return outletDiv;
};
  
  // Helper functions for personalizationHandler
  
  var displayDefaultContent = function (result, targetArea) {
    // Display the default content
    targetArea.style.opacity = 1;
}

var displayCustomUrl = function (content, targetArea) {
    var contentId = content.value
    if (contentId && contentId !== 'CONNF404' && targetArea) {
        // Display the personalized content
        targetArea.style.opacity = 1;
    } else {
        displayDefaultContent(content, targetArea);
    }
}
var displayWchUrl = function (content, targetArea) {
    var contentId = content.value
    if (contentId && contentId !== 'CONNF404' && targetArea) {
        // Display the personalized content
        targetArea.style.opacity = 1;
    } else {
        displayDefaultContent(content, targetArea);
    }
}

var displayCustomHtml = function (content, targetArea) {
    var contentId = content.value
    if (contentId && contentId !== 'CONNF404' && targetArea) {
        // Display the personalized content
        targetArea.style.opacity = 1;
    } else {
        displayDefaultContent(content, targetArea);
    }
}
var displayWchHtml = function (content, targetArea) {
    var contentId = content.value
    if (contentId && contentId !== 'CONNF404' && targetArea) {
        // Display the personalized content
        targetArea.style.opacity = 1;
    } else {
        displayDefaultContent(content, targetArea);
    }
}

var displayRecommendations = function (products, targetArea) {
    var recommendations = products.value;
    if (recommendations && recommendations !== 'CONNF404' && targetArea) {
        // Display the personalized recommendations
    } else {
        // Display the default recommendations
        displayDefaultContent(products, targetArea);
    }
}


// Step 6
// A handler at the client side to process the results
var personalizationHandler = function(result, targetArea)
 {
    switch(result.type) {
        case "recommendation": 
            displayRecommendations(result, targetArea);
            break;
        case "custom-url":
            displayCustomUrl(result, targetArea);
            break;
        case "custom-html":
            displayCustomHtml(result, targetArea);
            break;
        case "wch-url":
            displayWchUrl(result, targetArea);
            break;
        case "wch-html":
            displayWchHtml(result, targetArea);
            break;
        case "":
            displayDefaultContent(result, targetArea);
            break;
        }
}
// Step 7
// Configure personalization
personalizationObject.onReady(function(){

    // Step 8 configure zones (Approach 1)
    var zones = document.querySelectorAll('[custom-pzn]');
    zones.forEach(function(value) {
        var zoneObj = {
            "zoneId": value.getAttribute('custom-pzn-zone-reg-id'), 
            "targetArea": value.getAttribute('custom-pzn-target-area'), 
            "num": value.getAttribute('custom-pzn-product-number')
        };
        
        var validElement = validateDOMElement(zoneObj.targetArea)
        if(validElement) {
            personalizationObject.getContent(zoneObj)
            .then(function(result) {
                personalizationHandler(result, validElement) 
            });
       //Optional code to capture click events
          personalizationObject.collectBehavior("<<elementId>>","<<event>> ","<<zoneId>>");
        }
    });
});
} else {
    console.log("Error in loading the Personalization library.");
}
});
</script>

Next steps

After you have configured the zones of your channel, you can implement the following features:

Capture the click events on zones

You can configure the zones to capture the click events, so as to track the effectiveness of your personalized content. Capturing the click events is essential to generate the performance reports for the personalization.
For more information, see Capture click events

Configure geolocation

Configuring geolocation enables you to display personalized content based on the visitor's geographical location. For more information, see Configure Geolocation

Display header for your recommendation zone

When creating a product recommendations strategy, you can optionally specify the header (title) to be displayed on each zone. This makes it easier for you to communicate the objective of each recommendation strategy to your website visitors. For more information, see Display header for recommendation zone

Updated about 1 year ago