Quick Start: Recommendations
Welcome to the Particular Audience Quick Start guide! By the end of this tutorial you will have a functioning recommendation UI widget that you can place on your website. Along the way you will also learn more about the PA recommendation system.
In 10 minutes you will build:

To get started, let’s create a React project.
yarn create react-app pa-recommendation-ui
You should now have an empty React JS project.
Let’s now start building!
cd pa-recommendation-ui
yarn start
Let’s go ahead and add in the PA Sandbox Tag. This (to an extent) mimics the production PA Tag that will be given to you. The tag also helps get the CustomerId for you from PA’s servers.
To add the tag, navigate to
public/index.html
and add the following script in the head tag.public/index.html
<script>window.addPAC = function (c, e) { document.cookie = 'PAC=' + c + ';' + e + ';' }</script>
<script src="https://cdn.particularaudience.com/js/sandbox/t.js"></script>
🧙 Tips: The PA Tag does a lot of house keeping work such as track user behaviour data and automatically fetch the CustomerID for you.
Next, let’s go to
src/App.js
and add some boilerplate code.This piece of code contains three key steps:
- 1.Fetch recommendations
- 2.Enrich recommendation data
- 3.Display recommendations
src/App.js
import './App.css';
import React, { useState, useEffect } from "react";
const WEBSITE_ID = '11111111-1111-1111-1111-111111111111'
const PLACEHOLDER_DATA_STORE = {
pr001: {
title: 'Sennheiser CX 400BT True Wireless In-Ear Headphones (Black)',
price: '$149',
imageUrl: 'https://s3-syd-shrd-api-doc-public-assets.s3-ap-southeast-2.amazonaws.com/sennheiser-cx.jpeg'
},
pr002: {
title: 'Sony WF-XB700 Truly Wireless In-Ear Extra Bass Headphones (Blue)',
price: '$139',
imageUrl: 'https://s3-syd-shrd-api-doc-public-assets.s3-ap-southeast-2.amazonaws.com/sony-wf-xb700.jpeg'
}, pr003: {
title: 'Urbanista Athens True Wireless In-Ear Headphones (Black)',
price: '$114',
imageUrl: 'https://s3-syd-shrd-api-doc-public-assets.s3-ap-southeast-2.amazonaws.com/urbanista-athens.jpeg'
}, pr004: {
title: 'SteelSeries Arctis 7 Wireless Gaming Headset 2019 Edition (Black)',
price: '$339',
imageUrl: 'https://s3-syd-shrd-api-doc-public-assets.s3-ap-southeast-2.amazonaws.com/steelseries-7.jpeg'
}, pr005: {
title: 'SteelSeries Arctis 9X Wireless Gaming Headset for Xbox Series X',
price: '$359',
imageUrl: 'https://s3-syd-shrd-api-doc-public-assets.s3-ap-southeast-2.amazonaws.com/steelseries-9x.jpeg'
}, pr006: {
title: 'SteelSeries Arctis 7P Wireless Gaming Headset (White)',
price: '$349',
imageUrl: 'https://s3-syd-shrd-api-doc-public-assets.s3-ap-southeast-2.amazonaws.com/steelseries-7p.jpeg'
}
}
const STYLES = {
container: {
display: 'grid',
gridGap: '16px 16px',
gridTemplateColumns: 'auto auto auto auto',
padding: 16
},
slot: {
border: '1px solid black',
padding: 8
}
}
function App() {
const [rawRecommendations, setRawRecommendations] = useState([])
const [enrichedRecommendations, setEnrichedRecommendations] = useState([])
useEffect(() => {
// Get PA CustomerID
const customerId = getCookie('PAC')
fetchRecommendations(customerId)
}, []);
useEffect(() => {
// Enrich data
enrichRecommendations()
}, [rawRecommendations]);
const getCookie = (cookieName) => {
let name = cookieName + '='
let cookieAttributes = document.cookie.split(';')
for (var i = 0; i < cookieAttributes.length; i++) {
let cookieAttribute = cookieAttributes[i]
while (cookieAttribute.charAt(0) === ' ') {
cookieAttribute = cookieAttribute.substring(1)
}
if (cookieAttribute.indexOf(name) === 0) {
return cookieAttribute.substring(name.length, cookieAttribute.length)
}
}
return ''
}
const fetchRecommendations = async (customerId) => {
const res = await fetch(`https://recs-1a.particularaudience.com/1.0/ClientRecom/${WEBSITE_ID}/Personalized?customerId=${customerId}`)
if (res.ok) {
const resultsJson = await res.json()
setRawRecommendations(resultsJson.payload)
}
};
const enrichRecommendations = () => {
const enrichedRecs = []
rawRecommendations.forEach(productId => {
enrichedRecs.push(PLACEHOLDER_DATA_STORE[productId])
})
setEnrichedRecommendations(enrichedRecs)
}
return (
<div className="App">
<h1>Particular Audience React Recommendation UI</h1>
<div style={STYLES.container}>
{
enrichedRecommendations.map((recommendation) => {
return (
<div style={STYLES.slot}>
<img width={150} height={150} src={recommendation.imageUrl} />
<p>{recommendation.price}</p>
<p>{recommendation.title}</p>
</div>
)
})
}
</div>
</div>
);
}
export default App;
Fetching recommendations
There are three key unique IDs to keep in mind when making a GET request to any recommendation endpoint:
- WebsiteID: this is an ID given to you, the client, when the tracker is completed
- CustomerID: this is the customer ID
- ProductID: this is the primary ID of the product, either on a SKU level or item group level depending on how the recommendations were set up for you
🧙 Tips: The Sandbox WebsiteID is 111111-1111-1111-1111-111111111111
🧠 Note: CustomerID vs ProductID based requests
We have customer centric recommendations that require a customer ID such as recently viewed products. On the other hand, we have product based recommendations which depend on what product the user is viewing at the current moment. To get a full idea of all the available tactics, please refer to our API Reference.
If you’re unsure of what tactic or strategy to implement, reach out to your account manager and we can create a plan for you!
For this tutorial, we will use one of the CustomerID specific endpoints that you can see below.
https://recs-1a.particularaudience.com/1.0/ClientRecom/11111111-1111-1111-1111-111111111111/Personalized?customerId={CustomerID}
Before we make the request we need to get the CustomerID. The PA Tag stores the CustomerID either:
- In a cookie
- As part of the HTML body
The boilerplate code has included a function to get the CustomerID.
const getCookie = (cookieName) => {
let name = cookieName + '='
let cookieAttributes = document.cookie.split(';')
for (var i = 0; i < cookieAttributes.length; i++) {
let cookieAttribute = cookieAttributes[i]
while (cookieAttribute.charAt(0) === ' ') {
cookieAttribute = cookieAttribute.substring(1)
}
if (cookieAttribute.indexOf(name) === 0) {
return cookieAttribute.substring(name.length, cookieAttribute.length)
}
}
return ''
}
Once you have the CustomerID you are able to make the sandbox request.
🧙 Tips: If you want to use PA Recommendations in your email or SMS campaigns, be sure to save the CustomerID down in your database for future requests.
The PA Recommendation API returns a list of product IDs. We do not include extra data such as product title, image, price, availability or other pieces of information. This provides flexibility in how you enrich the data with your own up-to-date product information.
In our code sample, we mimic this process with a constant variable called
PLACEHOLDER_DATA_STORE
which contains the product information.
The easy part! Now that we have our enriched recommendations, we can display it however we want.
Last modified 2yr ago