Personalization

Configure library

Configure the PZN library for your MPA channel or your SPA channel. When you update the library, validate it in a non-production environment first.

Before you begin

  • Register Personalization endpoints in Exchange and Exchange Capture.
  • Register and configure your analytics library in Exchange and Exchange Capture.
  • To install the library for SPA, you must have npm installed. To install npm, download Node.js and run the npm install command. You can verify the npm version installed by running the command npm -v.
  • You must have access to the Acoustic artifactory to download the library package for SPA.

Identify your channel type

The first step to installing the Personalization library is to identify your channel (website) type. Personalization currently supports the following types of channels:

  • Multi-Page Applications (MPA)
  • Angular JavaScript Single-Page Application (Angular SPA)
  • React JavaScript Single-Page Application (React SPA)

The installation process differs based on the channel type.

MPA
Angular SPA and React SPA

Deploy Personalization library in Exchange Capture

Download and install the Personalization library from the Acoustic artifactory

Specify the Personalization library version in Exchange Capture

Specify the Personalization library version during installation

Configure the zones using code snippets specific to MPA

Configure the zones using code snippets specific to Angular SPA or React SPA

Deploy library for MPA

To deploy the library for an MPA channel, specify the library version in Exchange Capture.

  1. Go to Exchange > Tools > Exchange Capture.
  2. From the Applications list, click Acoustic Personalization.
  3. The Deploy Application screen appears.
  4. In the Personalization Library field, specify the version URL. For more information about supported library versions, see Library overview.

Note:

When you configure Personalization for the first time, use the stable version.

Option 1: To deploy the stable version of the library, specify the URL as follows:

//cdn-personalization-us-1.goacoustic.com/acoustic/prod/lib/acoustic-personalization-stable.js

Option 2: To deploy the latest version of the library, specify the URL as follows:

Note:

The example shows specifying the version for v2.2.0 as the latest version. Find the latest version number from library versions.

//cdn-personalization-us-1.goacoustic.com/acoustic/prod/lib/acoustic-personalization-VERSIONVERSION.js
//cdn-personalization-us-1.goacoustic.com/acoustic/prod/lib/acoustic-personalization-2.2.0.js

Option 3: To deploy a specific version of the library, specify the URL as follows:

Note:

The example shows specifying the version for v2.2.0 as the specific version. Find the version number you want to deploy from library versions.

//cdn-personalization-us-1.goacoustic.com/acoustic/prod/lib/acoustic-personalization-VERSIONVERSION.js
//cdn-personalization-us-1.goacoustic.com/acoustic/prod/lib/acoustic-personalization-2.2.0.js

  1. Go to Exchange Capture > Tag catalog.
  2. Find the Personalization tag from the Configured tags tab.
  3. Click Edit from the three-dot menu for the tag and navigate to Configure tag fields screen.
  4. In the Library URL section, select Constant for the Method.
  5. Then, in the Constant field, add the URL to deploy the Personalization library.
    For more information about supported library versions, see Library overview.

Note:

When you configure Personalization for the first time, use the stable version.

Option 1: To deploy the stable version of the library, specify the URL as follows:

//cdn-personalization-us-1.goacoustic.com/acoustic/prod/lib/acoustic-personalization-stable.js

Option 2: To deploy the latest version of the library, specify the URL as follows:

Note:

The example shows specifying the version for v2.2.0 as the latest version. Find the latest version number from library versions.

//cdn-personalization-us-1.goacoustic.com/acoustic/prod/lib/acoustic-personalization-VERSIONVERSION.js
//cdn-personalization-us-1.goacoustic.com/acoustic/prod/lib/acoustic-personalization-2.2.0.js

Option 3: To deploy a specific version of the library, specify the URL as follows:

Note:

The example shows specifying the version for v2.2.0 as the specific version. Find the version number you want to deploy from library versions.

//cdn-personalization-us-1.goacoustic.com/acoustic/prod/lib/acoustic-personalization-VERSIONVERSION.js
//cdn-personalization-us-1.goacoustic.com/acoustic/prod/lib/acoustic-personalization-2.2.0.js
  1. Click on Channel Tenant ID; from the Method dropdown, select Constant from the list.
  2. Provide the Channel Tenant to be used in your MPA.

Install library for SPA

  1. Update the .npmrc file for authorization.
    a. Log in to Acoustic artifactory. Click your username and then click Edit Profile.
    b. From the Authentication Settings, copy the API key.
    c. Run the following command on the Git bash or on any terminal that allows curl commands. Provide your Acoustic 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

d. Navigate to your user profile folder, usually located in the operating system drive.
e. Open the .npmrc file located in the user profile folder.

  • For Windows: The file is located in the USERPROFILE folder of the logged-in user. Use any text editor to open the file.
  • UNIX: The file is located in the /app directory. Use any text 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

Tip:

The following error in the .npmrc file is caused due to incorrect credentials. Remove the output generated and re-run the curl command using the correct credentials.

{"errors" : [{"status": 401,"message":"Bad credentials"}]}
  1. Install the library
    To install the library, run the command from the root directory of the application.
    Option 1: To install the stable version, run the following command:
npm install --save @acoustic/[email protected]

Option 2: To install the latest version, run the following command:

npm install --save @acoustic/personalization

This command fetches and installs the latest version from the artifactory.
Option 3: To install a specific version, run the following command:
The example illustrates the command to install version 2.2.0.

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

Info:

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. Personalization library is now installed. You can verify the installation by running the following command:
npm list @acoustic/personalization

The console output displays the Personalization library version.

Troubleshooting

For issues in installing or upgrading the library version, try the following steps:

  1. Uninstall the previous library version. Use this command: npm uninstall @acoustic/personalization
  2. Optional: You can also clear the entire NPM cache on your website.
  3. Next, perform a fresh install of the required library version.
  4. If the issue persists, restart your code editor. Then re-try the installation by specifying the version number. For example, npm install @acoustic/[email protected].

Next steps

After you install the library, configure the zones of your channel. Zones must be configured to display the personalized content or product recommendations.

Updated 3 months ago


Configure library


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.