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 commandnpm -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.
- Go to Exchange > Tools > Exchange Capture.
- From the Applications list, click Acoustic Personalization.
- The Deploy Application screen appears.
- 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-VERSION.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-VERSION.js
//cdn-personalization-us-1.goacoustic.com/acoustic/prod/lib/acoustic-personalization-2.2.0.js
- Go to Exchange Capture > Tag catalog.
- Find the Personalization tag from the Configured tags tab.
- Click Edit from the three-dot menu for the tag and navigate to Configure tag fields screen.
- In the Library URL section, select Constant for the Method.
- 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-VERSION.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:
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-VERSION.js
//cdn-personalization-us-1.goacoustic.com/acoustic/prod/lib/acoustic-personalization-2.2.0.js
- Click on Channel Tenant ID; from the Method dropdown, select Constant from the list.
- Provide the Channel Tenant to be used in your MPA.
Install library for SPA
- 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 allowscurl
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"}]}
- 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/personalization@stable
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/personalization@version
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.
- 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:
- Uninstall the previous library version. Use this command:
npm uninstall @acoustic/personalization
- Optional: You can also clear the entire NPM cache on your website.
- Next, perform a fresh install of the required library version.
- 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 over 1 year ago