Getting Started With ATS
Particular Audience’s Adaptive Transformer Search (ATS) API is a flexible and robust interface that supports any eCommerce platform or application.
The below APIs are all required to configure the Particular Audience ATS product suite.
- Products API
- Config
- Search
- Suggestion
- Events API
- When to Trigger Search Terms Event
- Implementing Search Click Events
Products API
A product catalogue is required to get started with Particular Audience ATS. All product properties and attributes in the Search API payloads must exist in the PA database.
Product data required for ATS includes data that is ‘searchable’ (useful product data to be used in forming vector embeddings) as well as product data that is for display and navigation on FE, such as product title, or URL link or category for aggregations (faceted filters).
Pushing a product catalogue to Particular Audience is easy with the UpdateProductDetails API. UpdateProductDetails API is a PUT request which can called from client ERP, Ecommerce platform, PIM or other business system to push catalogue and delta updates.
Config API
GetConfig API returns important fields related to CustomerID, SessionID, and the client configuration of Website and Routes. GetConfig is called when a customer visits the website for the first time and does not already have a PA CustomerID.
Before using this API, the Website must be configured in the PA Webapp along with Recommender > Campaign > Tactic, Widget, and Routes.
Search
Search API request is used to query ATS for vector search results, fuzzy suggestions, and redirect links.
Search Query
The initial search request will appear like the below example.
website_id and client are unique values assigned to the client during onboarding. customer_id is only required for Personalised Search. Personalised Search be enabled and trained by Particular Audience.
scope for the initial query is empty. sort_fields configured in the PA webapp are included when a customer sorts by a specific value on the FE.
start defines the offset from the first result you want to fetch, size defines the number of results for the request. The start and size values determine the number or results for the page load.
"website_id": "26aXXXXXXXXXXXXXXXXXXXXX7c",
"q": "Search Term",
"client": "CLIENT_SHORTCODE",
"customer_id":"530XXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX3"
"start": 0,
"scope": {},
"sort_fields": [{ "price": {"order":"asc"}}],
"size": 60
Search Query Response:
aggregations: Grouping of product attributed which a customer can filter the search results by.results: The list of search results complete with all product properties and attributes.suggestions: The suggestions in the search response are fuzzy_suggestions. These are typo correction suggestions when out of vocabulary words are identified in user queries.redirects: The redirects are URL links configured in the PA Webapp for specific queries. Redirect Documentation
{
"type" : 1,
"code" : 0,
"payload": {
"aggregations": {
"price": {
"avg": 6.08374996483326,
"count": 16,
"max": 24.989999771118164,
"min": 2,
"sum": 97.33999943733215
},
"product_category": [
{
"doc_count": 260,
"key": "Category1"
},
{
"doc_count": 14,
"key": "Category2"
}
]
},
"result": [
{
"attributes": {
"brand": "Kansas",
"org_price": 449,
"product_category": "Category1",
"sale_price": 319
},
"availability": -1,
"image_link": "https://www.testlink.com/",
"item_group_id": "250433",
"link": "https://www.testimagelink.com",
"object_types": [
"shelf",
"cupboard",
"filing cabinet",
"cabinetry"
],
"personalized": false,
"product_category_id": 465,
"score": 1,
"sku_id": "12188",
"title": "Sample item",
"website_logo": "https://www.samplelogo.com"
}
],
"total_results": 274,
"suggestions" : {
"fuzzy_suggestions" : ["sample_suggestion"]
},
"redirects" : {
"url": "https://sample_url.com/"
}
}
}
Scope Change - Filtering a Search Results page
When a customer interacts with facet filters on the search results page, a new request is sent to search API inclusive of the new scope the new scope.
Facets available for a user to filter by are returned in the aggregations in the Search response.
"website_id": "26aXXXXXXXXXXXXXXXXXXXXX7c",
"q": "Search Term",
"client": "CLIENT_SHORTCODE",
"customer_id":"530XXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX3"
"start": 0,
"scope": {brand: ["sample brand"]},
"sort_fields": [
{
"price":
{
"order":"asc"
}
}
],
"size": 60
Suggestion
The /suggestion API endpoint is used for Suggested and Trending Search terms. Suggested and Trending Terms are used in the Search Preview widget to help direct a user query.
For both Suggested and Trending terms, the Suggestion API returns both ranked terms based on live user behaviour as well as synthetic terms which are inserted by business users in the PA webapp.
- Ranked terms are returned under: suggested_terms, trending_terms
- Synthetic terms are returned under: synthetic_treding_terms , synthetic_suggested_terms
When displaying the ranked and synthetic suggestions in the search preview UI, the synthetic terms should always be displayed first in their respective UI, unless specified otherwise.
The /suggest API response looks like the below:
{
"payload": {
"suggested_terms": [
{}
],
"synthetic_suggested_terms": [
{}
],
"synthetic_trending_terms": [
{}
],
"trending_terms": [
{}
]
},
"type": 1
}
The UI should be displayed like the below:
Events API
ATS use first-party data combined with product metadata to deliver the most tailored product discovery journey’s for customers. To do so, PA ingests anonymised behaviour signals like SearchTerms, clicks, and purchase events via the PA Events API.
Events API sends the events that are required for PA Advanced Analytics. It is important these events are configured and triggering correctly and being ingested by PA Events API.
- Search Terms
- Slot Impressions
- Clicks
- View Products
- Add To Carts
- Checkoutss
- Purchase
Event: Search Term
Search Term event tracks unique, genuine search terms on a website. This event is triggered upon the response payload from Search API, complete with number of results for the query.
Capturing the user Search Term accurately is critical for tracking the performance of the ATS product. Inaccurately triggering SearchTerm on partial query could incorrectly report Zero Results queries.
The NumberOfResults captured in the Search Term event will be taken from the search API response payload.
See the below guide to correctly implement Event: Search Terms
Event: Search Terms Documentation
Slot Impressions
Slot Impressions event tracks the impressions of each product slot in search results.
Slot Impressions only triggers once a user has viewed the product slot on the page. Slot impressions are important to track the engagement and performance of PA search results on a client website. Slot Impressions is also required for PA Advanced Analytics.
Event: Slot Impressions Documentation
Clicks
The Click event tracks unique clicks on UI powered by Particular Audience, e.g. clicks on search results, CTA buttons, sort/filters.
Within the Click event, ActionType determines the event being tracked and ContextType relates to the PA powered widget or slot being clicked. Click events are vital for ATS Automated Reinforcement Learning (ARL) and PA Advanced Analytics.
See the below guide to correctly implement Event: Clicks for ATS.
View Products
The View Products event tracks a product view for the unique CustomerID and SessionID. This event is triggered on a product page and is used to analyse anonymised customer browsing behaviour for real time personalisation in search.
Event: View Products Documentation
Add To Carts
The AddProductToCart event tracks all Add to Cart event on client website. The event triggers for each item added to cart, both for the native ATC button as well as Add To Cart CTAs on Particular Audience Powered widgets, e.g. Add to Cart from Search. AddProductToCart is used for Advanced Analytics reporting.
Event: Add To Carts Documentation
Checkouts
Checkouts event tracks the customer checkout, capturing all items in a basket. This event is used for analysing customer browse and buying behaviour and is also used for PA Advanced Analytics.
Checkouts triggers every time a customer reaches the Cart or Checkout page, depending on the conversion funnel configuration. Each time the event triggers, the cart contents will be reconsidered.
Event: Checkouts Documentation
Purchases
Purchase event tracks the customer transactions, including all items being purchased. This event is used in analysing customer purchase behaviour and is also required for Advanced Analytics.
Purchase event triggers on the confirmation page of a website, upon the successful completion of a transaction.
When to trigger the Search Terms event
Default Implementation:
Search Terms event triggers when the Search Engine Results Page (SERP) loads on a website. When the SERP page loads, the payload is returned for the query [q] SearchTerm complete with the total_results which is used in the NumberOfResults field required for the SearchTerm event.
The example below of the request and response. The SearchTerm, q is ‘mountain’ and the NumberOfResults returned is 119
Request:
"customer_id": "43XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXb61",
"website_id": "180XXXXX-XXXX-XXXX-XXXX-XXXXXXXX447c",
"q": "mountain",
"client": "XXX",
"start": 0,
"size": 10,
"scope": {}
Response:
"type": 1,
"code": 0,
"payload": {
"total_results": 119,
}
Search Preview Widget with Product Results:
Some websites' Search Preview Widget UI displays top product results. In this case, the preview widget is calling both /search endpoint for product results and /suggestion endpoint for Suggested and Trending keywords.
If a user clicks on a product result in the search widget preview UI, this click opens the PDP page of the specific product. This click will trigger both the SearchTerm event and the Click event (ActionType: 1). Note: if Add To Cart is also available in the Search Preview Widget, the Click event will be (ActionType: 2).
Search Preview Widget
Search Preview Widget with Top Products
Search Preview Widget Suggestions Only
Live search results UI
Some websites' display a live results in the Search Widget or SERP page. While this UI can provide a nice UX for the customer, it proves challenging when tracking genuine Search Termss. For live search results implementation we suggest the below for triggering Search Terms.
Search Terms is triggered on any of the below, whichever comes first after a search API response has been received.
-
After a new response from search API, when the user interacts with the widget.
- This includes but not limited to Scroll, Sort, Filter, Facet or Click on a result in the search widget to open the product page or Add to Cart.
Implementing Search Click Events
Clicks events track user behaviour in Search.
In addition to tracking Search Terms for analytics, Clicks is used to understand user behaviour, inform our ATS models through reinforcement learning, and track search attribution. Clicks event triggers on all user clicks of the Search Preview Widget and Search Results Page.
Clicks events include the specific click action recorded in the ActionType field. All search Clicks events must include the Search Term in the ContextData1 field (the only exception is ActionType 14 - ClickFilterSort)
ATS requires Clicks events to be sent for the below ActionType:
-
OpenProductPage = 1: Triggered when a product is clicked in search results and the PDP is opened in current or new tab/window.
-
AddProductToCart = 2: Triggered when the customer adds an item to cart directly from search result.
Clicks events are not required for the below ActionType, however are informative of user behaviour:
- ClickDidYouMeanTerm =15: Triggered when a user clicks on the Typo Suggest Term.
- PopularSearchLink = 5: Triggered when a user clicks on the Suggested or Trending Search Term
- RecentlySearchTerm =18: Triggered when a user clicks on a Recent Search Term
- QuickLink = 6: Triggered when a user clicks on a Quick Link (redirect or category link)
- ClickFilterSort = 14 Triggered when a user clicks on sort or filter options in search results (ContextDats will be the Filter or Sort information, not the SearchTerm)