Documentation
Help CenterCommunityDevelopersAcademyStatus

Quick start for Personalization

Set up personalization for websites built from Multi-Page or Single-Page Application

Suggest Edits

We're ready to help you set up a working implementation of Personalization. In this quick start, you will learn how to:

  • Register your website and zone that you want personalized.
  • Connect and configure the Personalization components with your site.
  • Create a contextual rule to control when an image displays on a page based on browser type.
  • Verify your implementation is working as expected.
  • Find next steps for more advanced configurations.

📘

Scope of quick start guide

By the end of this guide, you won't be able to try every feature Personalization has to offer, but you will have the basic components you need to get started.
If you prefer to follow the full setup instructions instead of a quick start, check out Setting up Personalization

Before you begin:

To complete this guide, you'll need to:

  • Update the code on your website to add rendering logic for Personalization.
  • Have access to an instance of Exchange and Exchange Capture that is registered with Personalization endpoints.

📘

Note:

This quick start guide for MPA focuses on setting up Personalization using the new Exchange Capture UI and Personalization library version 2.3.

Register your website and zone

We’ll start with configuring your website and zone. Everything you need to complete this task is in the Personalization UI.

  1. From the main navigation, click Settings>Implementation Status.

  2. Click Channels and click Register new channel.

  3. Enter a name for the website that you want to register.

  4. Select Web as the channel type.

  5. Select Multi Page Application (MPA) as the website channel type.

  6. Enter your website URL. For example, we used http://citycool or https://citycool.

  7. Click Create. Your channel tenant ID is automatically generated for you and displays in the Channel properties section.

  8. In the Zone registration section, click Register a new zone. A zone is an area on your website that you want to personalize.

  9. Enter a zone name, zone ID, and the short description.

📘

Tip:

If you don't know your zone ID, no worries! You can quickly find it by opening your website and navigating to the page that contains the zone you want to personalize. Open your browser's developer tools to inspect the page for the zone ID.

  1. Click Register and save your changes. You're zone ID is automatically generated and displays in the Zone registration section.

Connect your website to Personalization components

We'll move on to connecting Personalization components with Exchange. By the end of these steps, you'll be able to publish events in Exchange using the channel identifier you recorded in the previous section. You'll also use Exchange to install the Personalization library to your website.

Get the Exchange Capture enablement code

  1. Log in to Exchange. From the main menu, navigate to Tools>Exchange Capture.

  2. Click the Enablement Code icon.

  3. Copy the two lines of code that contain the enablement code. Save these lines of code in a text editor. These lines will be required.

  4. Click Close.

  5. Go to the HTML page that you want to personalize.

  6. Add the following code to the <Head> tag of your page. Make these updates to the code:

    • Replace the Exchange enablement key code in the sample with the one that you copied in an earlier step. This ensures the correct pairing of your Personalization endpoint is used in Exchange.
    • Replace the CHANNEL TENANT ID with the channel tenant ID of your website.
    • Replace the UBX CAPTURE ENABLEMENT KEY with your enablement key. 




      <script>
        window.digitalData = {};
        digitalData.pageInstanceID = "acousticPersonalizationTest";
        var channelID ="CHANNEL TENANT ID";
</script>
<script type="text/javascript" src="//lib-us-3.brilliantcollector.com/common/ubxCapture.js"> 
</script> 
<script type="text/javascript"> ubxCapture.setID("UBX CAPTURE ENABLEMENT KEY"); 
</script>

Deploy the Personalization library
You can deploy the Personalization library by specifying the required library version in Exchange Capture.

  1. From the Exchange menu, go to Tools > Exchange Capture.
  2. From the Partner Enablement's screen, search Acoustic Personalization. If the partner is not enabled, hover over the card and click Enable.
  3. Open the Tag Catalog screen from the side menu. Acoustic Personalization is listed as enabled in the Enabled partners' tab.
  4. Click Configure Tag to add the Acoustic Personalization in the Deployment Group.
    • Complete the following in the Provide details screen:
      • From the Enable Partner drop-down list, select Acoustic Personalization.
      • From the Tag Template drop-down list, select Enable Acoustic Personalization – [Head].
      • Provide a Tag name, for example, MPAPersonalizationTag, and click Next.
    • Complete the following in the Configure tags fields screen:
      • Open Channel Type. Then in the Channel Type field, select Multi-Page Application.
      • Open Library URL. Then from the Method drop-down list, select Constant.
        In the Constant field, add the following library version URL for version 2.3.0. 
        //cdn-personalization-us-1.goacoustic.com/acoustic/prod/lib/acoustic-personalization-2.3.0.js
      • Open Channel Tenant ID. Then, in the Method field, select Constant. In the Constant field, provide the Channel Tenant ID.
      • Open Exchange Event Authentication Key. Once again, select Constant in the Method field.
        In the Constant field, provide the endpoint authentication key for Acoustic Personalization – Publisher. You can find this in the endpoint Details.
  5. Click Next and Submit.

Deploy the Personalization library tag on the Exchange Capture deployment group

  1. From the Exchange menu, go to Tools > Exchange Capture.
  2. From the Deployment Group screen, click Create Deployment Group.
    • Provide details for deployment group such as Name, Category.
    • Select Head in the Container field and click Next.
    • Select Page Identifier.
    • Select contains from the drop-down and provide acousticPersonalizationTest value in the input box.
    • Click Create Group. Your deployment group is shown in Deployment Group List.
  3. Click Add Tag.
    • Select Acoustic Personalization from the Tag Source.
    • Select MPAPersonalizationTag from the Tag.
    • Click Next and then Submit.
  4. Click Deploy. The following two options are available for you to deploy:
    • Deploy to Test – You can use the test tool to test the personalization without deploying it to production.
    • Deploy to Production – You can directly deploy the deployment group on production to see personalization.

📘

Note:

For production deployment, it will take 2 hours. You can use the test tool to see personalization without waiting. For more information, see

Configure Personalization for your website

  1. Navigate to the HTML page(index.html) on your website that you want to personalize.

  2. Add the following javascript code to the HTML page before the closing body tag to configure the personalization. 





<!—- Personalization code //  -->
<script type="text/javascript">
// Step 2
var init = (function () {
// get the personalization object
if (acoustic != undefined || acoustic != {}) {
// access the personalization object
var personalizationObject = acoustic.personalization.PersonalizationLibrary.create();
 
// 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
    var defaultContent = 'https://cdn.britannica.com/17/83817-050-67C814CD/Mount-Everest.jpg';
    targetArea.style.background = "url(" + defaultContent + ") 0px 0px / cover no-repeat";
    targetArea.style.opacity = 1;
}
 
var displayCustomUrl = function (content, targetArea) {
    var contentId = content.value
    if (contentId && contentId !== 'CONNF404' && targetArea) {
        // Display the personalized content
        targetArea.style.background = "url(" + contentId + ") 0px 0px / cover no-repeat";
        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.background = "url(" + contentId + ") 0px 0px / cover no-repeat";
        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.inneHTML= contentId;
         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.inneHTML= contentId;
         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);
    }
}
 
 // 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;
        }
}
 
// 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.");
}
});
 
window.onload = init;
 
</script>
  1. Add the following HTML code to your page.




<div> 
    <div id="WelcomeBannerZone" wrtp-recommended-zone="WelcomeBannerZone" custom-pzn 
custom-pzn-zone-reg-id="WelcomeBannerZone" 
custom-pzn-target-area="WelcomeBannerZone" 
custom-pzn-product-number=""> 
    </div> 
</div>

Add your first rule

Now that you have the website set up, we'll move on to creating your first rule for the area you selected to personalize on your site. For our quick start implementation, we will use a contextual-based rule based on browser type to control what displays on the site. Later, you'll want to integrate your analytics library for behavior-based segments, but it is not required for this guide.

  1. From the Personalization UI, open the main menu and click Zones.

  2. From your zone, click Actions>Create personalization.

  3. Click New rule

  4. Select Rule-based personalization and click Next.

  5. Enter a meaningful rule name. We used contextRule as our rule name.

  6. Enter 0 in the Control group field to apply this rule to everyone.

  7. The No limit radio button is selected by default. Keep this selection.

  8. Set the rule duration. For the Start option, select Specified date and time and enter your start date and time. For the End option, we'll keep the default selection of When unpublished.

  9. You'll see the option to select goals. This is an optional step that we'll skip for now. Click Next to continue.

  10. Review the rule configuration details and click Next.

  11. Add the content that you want to use for this rule in the form of URL or HTML blob.

Verify your implementation

It's time to see your rule in action with a simple check. Open your website across different browsers to verify everything is working as expected.

In Chrome, the content you added to your rule should display in the zone. For example, we tested this guide by seeing if our rule would display a banner image only in Chrome.

In another browser, like Firefox your content should not display. We opened our website in Firefox and the banner image did not display.

Now, it's your turn. Check out your page across different browsers now!

Move on to next steps

Congratulations on a successful implementation. Remember, this quick start was only the beginning.

Before you check out the coolest parts of Personalization, make sure you register your content source on the Implementation Status page. We skipped that step earlier since we it was needed for this quick start.

When you're ready, move on to more advanced configurations to unlock the full potential of Personalization:

Register your website and zone

We’ll start with configuring your website and zone. Everything you need to complete this task is in the Personalization UI.

  1. From the main navigation, click Settings>Implementation Status.

  2. Click Channels and click Register new channel.

  3. Enter a name for the website that you want to register.

  4. Select Web as the channel type.

  5. Select Single Page Application (SPA) as the website channel type.

  6. Enter your website URL. For example, we used http://citycool or https://citycool.

  7. Click Create. Your channel tenant ID is automatically generated for you and displays in the Channel properties section.

  8. In the Zone registration section, click Register a new zone. A zone is an area on your website that you want to personalize.

  9. Enter a zone name, zone ID, and the short description.

📘

Tip

If you don't know your zone ID, no worries! You can quickly find it by opening your website and navigating to the page that contains the zone you want to personalize. Open your browser's developer tools to inspect the page for the zone ID.

  1. Click Register and save your changes. You're zone ID is automatically generated and displays in the Zone registration section.

Connect your website to Personalization components

We'll move on to connecting Personalization components with Exchange. By the end of these steps, you'll be able to publish events in Exchange using the channel identifier you recorded in the previous section. You'll also use Exchange to install the Personalization library to your website.

Get the Exchange Capture enablement code

  1. Log in to Exchange. From the main menu, navigate to Tools>Exchange Capture.

  2. Click the Enablement Code icon.

  3. Copy the two lines of code that contain the enablement code. Save these lines of code in a text editor. These lines will be required.

  4. Click Close.

  5. Go to the HTML page that you want to personalize.

  6. Add the following code to the <Head> tag of your page. Make these updates to the code:

    • Before the setTenantID function, replace the Exchange enablement key code in the sample with the one that you copied in an earlier step. This ensures the correct pairing of your Personalization endpoint is used in Exchange.
    • Replace the CHANNEL TENANT ID with the channel tenant ID of your website.
    • Replace the UBX CAPTURE ENABLEMENT KEY with your enablement key. 


			

<script type="text/javascript" src="//lib-us-3.brilliantcollector.com/common/ubxCapture.js"> 
</script> 
<script>  var channelID ="CHANNEL TENANT ID"; 
ubxCapture.setTenantID("WRTP",channelID);  
</script> 
<script type="text/javascript"> ubxCapture.setID("UBX CAPTURE ENABLEMENT KEY"); 
</script>

Install the Personalization library

In order to display personalized content or product recommendations on the zones of your Single-Page Application (SPA), you need to install the Personalization Library and then add the personalization code to the website zones.

  • To execute the npm commands, you must install Node Package Manager. NPM is included with the recent versions of Node.js. For more information, see Install NPM.
  • You must have access to the Acoustic Artifactory to download the Library package.

Update the npmrc file for authorization

  1. in to Acoustic Artifactory. Click your username and then click Edit Profile.
  2. From the Authentication Settings, copy the API key.
  3. Run curl on the Git bash or on any terminal that allows curl commands using your Acoustic ID credentials. This command creates the .npmrc file using the specified credentials.


	

  curl -u ACOUSTIC_OKTA_ID:API-KEY
 https://artifactory.acoustic.co/artifactory/api/npm/pzn-public-npm-virtual/auth/acoustic >> ~/.npmrc

  1. Navigate to your user profile folder, usually located in the operating system drive.

  2. Open the .npmrc file located in the user profile folder.

    • Windows: The file is located in the USERPROFILE folder of the logged-in user. You can use any text editor such as Notepad to open the file.
    • UNIX: The file is located in the /app directory. You can use any text editor such as vi editor to open the file. The file displays the registry changes. The new value for the registry is:




	@<SCOPE>:registry=https://artifactory.acoustic.co/artifactory/api/npm/pzn-public-npm-virtual/
  //artifactory.acoustic.co/artifactory/api/npm/pzn-public-npm-virtual/:_password=BASE64_PASSWORD
  //artifactory.acoustic.co/artifactory/api/npm/pzn-public-npm-virtual/:username=USERNAME
  //artifactory.acoustic.co/artifactory/api/npm/pzn-public-npm-virtual/:email=<<[email protected]>>
  //artifactory.acoustic.co/artifactory/api/npm/pzn-public-npm-virtual/:always-auth=true

Update the npmrc file for authorization

  1. Run the following command to install the deployed packages with a specific version:

npm install --save @acoustic/[email protected]

📘

Note:

  • The example illustrates the command to install the version 2.2.0.
  • During the installation, you might see some warning messages in the console window. You can safely ignore these warnings as they do not impact the package installation.

  1. Your Personalization library is now installed. You can verify installation by running the following command and checking the library version that displays in the console input:

npm list @acoustic/personalization

Zone configuraton

Update to app.module.ts

  1. Add the following code to import the Personalization library.




	import 
  { 
  PersonalizationLibrary
  }
  from 
  “
  @
  acoustic
  /
  personalization”;
  1. Initialize the Personalization library inside the constructor of the application’s RootModule.




		export class AppModule { 
    constructor() {
        PersonalizationLibrary.create();
    }
}
  1. Add the imported personalization object PersonalizationLibrary into the providers array as shown below. This enables the personalization service to be shared and used across the client application.




		providers: [
   PersonalizationLibrary

Changes to target.component.ts

Identify the component where the personalization/ recommendation is to be added, and make the following updates:

  1. Add the following import to use the personalization object as a service in the target component of the client application.




	import
  {
  PersonalizationLibrary
  } 
  from 
  ‘
  @
  acoustic
  /
  personalization’
  ;
  1. Add the imported member into the constructor




constructor
(private 
personalizationObject
: 
PersonalizationLibrary
) {}
  1. Configure the zone. The switch case shown below illustrates the processing for various content types. The following content types are currently supported:
    • recommendation
    • custom-url
    • wch-html
    • wch-url
    • "" : To be used when the content returned is a default content.
      If needed, you can add the processing for other content types as per your requirement.




function 
personalizationHandler(result) {
            switch(result.type) {
                case "recommendation": 
                    return displayRecommendations(result);
                case "custom-url":
                    return displayCustomUrl(result);
                case "custom-html":
                    return displayCustomHtml(result);
                case "wch-url":
                    return displayWchUrl(result);
                case "wch-html":
                    return displayWchHtml(result);
                case "":
                    return displayDefaultContent(result);
            }
        }

View definitions of the helper functions

The following code snippet provides the definitions of helper functions inside the personalizationHandler() function.





			displayDefaultContent(content) {
    // return the default content
	return content;
}
function displayDefaultHTMLContent(content) {
    // return the default HTML content
	let defaultHTMLText = '<div>Please come back again!</div>';
         return defaultHTMLText;
}
function displayCustomHtml(content) {
    let contentId = content.value
    if (contentId && contentId !== 'CONNF404') {
        // return the personalized html content
	return contentId;
    } else {
        displayDefaultHTMLContent(content);
    }
}
function displayWchHtml(content) {
    let contentId = content.value
    if (contentId && contentId !== 'CONNF404') {
        // return the personalized html content
	return contentId;
    } else {
        displayDefaultHTMLContent(content);
    }
}
function displayCustomUrl(content) {
    let contentId = content.value;
    if (contentId && contentId !== "CONNF404") {
        // return the personalized content
	return contentId;
    } else {
        // return the default content
        displayDefaultContent(content);
    }
}
function displayWchUrl(content) {
    let contentId = content.value;
    if (contentId && contentId !== "CONNF404") {
        // return the personalized content
	return contentId;
    } else {
        // return the default content
        displayDefaultContent(content);
    }    
}
function displayRecommendations(products) {
    let recommendations = products.value;
    if (recommendations && recommendations !== "CONNF404") {
        // return the personalized recommendations
    } else {
        // return the default recommendations
        return displayDefaultContent(products);
    }
}
  1. Configure the personalized zones.




this.personalizationObject.onReady(()=>{
this.personalizationObject.getContent({ zoneId:‘WelcomeBannerZone’})
.then(
result => {
            this.personalizationContentVar = personalizationHandler(result);
        // VARIBLE NAME can be used to display the contents
    }
)
});

Update the HTML file on your website

Locate the HTML file of your SPA zone on which you want to show content personalization. Add the following snippet to it.





<div id=”WelcomeBannerZone” wrtp-recommended-zone=”WelcomeBannerZone”>
     <div *ngIf=”personalizationContentVar”></div> // Make use of this variable to display and render the contents
</div>

In the code snippet:

  • Replace DEFAULTCONTENT with the default content that you want to display on the channel if no rules match the user behavior.
  • The error code CONNF404 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.

If the zones that you want to personalize are in the same component, include them in the same onReady function. If the zones that you want to personalize are in different components, create a separate onReady function for each component.

Add your first rule

Now that you have the website set up, we'll move on to creating your first rule for the area you selected to personalize on your site. For our quick start implementation, we will use a contextual-based rule based on browser type to control what displays on the site. Later, you'll want to integrate your analytics library for behavior-based segments, but it is not required for this guide.

  1. From the Personalization UI, open the main menu and click Zones.

  2. From your zone, click Actions>Create personalization.

  3. Click New rule

  4. Select Rule-based personalization and click Next.

  5. Enter a meaningful rule name. We used contextRule as our rule name.

  6. Enter 0 in the Control group field to apply this rule to everyone.

  7. The No limit radio button is selected by default. Keep this selection.

  8. Set the rule duration. For the Start option, select Specified date and time and enter your start date and time. For the End option, we'll keep the default selection of When unpublished.

  9. You'll see the option to select goals. This is an optional step that we'll skip for now. Click Next to continue.

  10. Review the rule configuration details and click Next.

  11. Add the content that you want to use for this rule in the form of URL or HTML blob.

Verify your implementation

It's time to see your rule in action with a simple check. Open your website across different browsers to verify everything is working as expected.

In Chrome, the content you added to your rule should display in the zone. For example, we tested this guide by seeing if our rule would display a banner image only in Chrome.

In another browser, like Firefox your content should not display. We opened our website in Firefox and the banner image did not display.

Now, it's your turn. Check out your page across different browsers now!

Move on to next steps

Congratulations on a successful implementation. Remember, this quick start was only the beginning.

Before you check out the coolest parts of Personalization, make sure you register your content source on the Implementation Status page. We skipped that step earlier since we it was needed for this quick start.

When you're ready, move on to more advanced configurations to unlock the full potential of Personalization:

Updated almost 2 years ago