Skip to main content

Getting Started With ATS

Particular Audience’s Adaptive Transformer Search (ATS) Search 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.

UpdateProductDetails - POST

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.

UpdateProductDetails API

Config - GET

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.

Config API

PageView - GET

Pageview API call is used to request PA Search Display configuration such as WidgetID and RouteID, required in sync API calls and used in PA Advanced Analytics.

PageView API

Search - POST

Search API request is used to query ATS for vector search results, fuzzy suggestions, and redirect links.

Search API

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. PA search supports infinite load and pagination. 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:

Included in the response are aggregations, results, suggestions, and redirects.

  • aggregations are grouping of product attributed which a customer can filter the search results by.
  • results includes the list of search results complete with all product properties and attributes.
  • suggestions in search response are fuzzy_suggestions. These are typo correction suggestions when out of vocabulary words are identified in user queries.
  • redirects are 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 - POST

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.

Search Suggestion API

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:

ATS Suggestion

Sync API - POST

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 Sync API.

Sync API

Sync sends events required for PA Advanced Analytics. It is important these events are configured and triggering correctly and being ingested by PA Sync API.

  • Sync.SearchTerm
  • Sync.SlotImpression
  • Sync.Click
  • Sync.ViewProduct
  • Sync.AddProductToCart
  • Sync.CheckoutCart
  • Sync.Purchase

Sync.SearchTerm

sync.SearchTerm 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 SearchTerm 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 SearchTerm event will be taken from the search API response payload.

See the below guide to correctly implement sync.SearchTerm

Sync.SearchTerm Documentation

Sync.SlotImpression

SlotImpression event tracks the impressions of each product slot in search results. SlotImpression 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. SlotImpression is also required for PA Advanced Analytics.

Sync.SlotImpression Documentation

Sync.Click

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 sync.clickfor ATS.

Sync.Click Documentation

Sync.ViewProduct

The ViewProduct 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.

Sync.ViewProduct Documentation

Sync.AddProductToCart

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.

Sync.AddProductToCart Documentation

Sync.CheckoutCart

CheckoutCart 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.

CheckoutCart 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.

Sync.CheckoutCart Documentation

Sync.Purchase

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.

Sync.Purchase Documentation

When to trigger the SearchTerm Sync event

Default Implementation:

SearchTerm sync 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

ATS Search Preview 1

Search Preview Widget Suggestions Only

ATS Search Preview 2

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 SearchTerms. For live search results implementation we suggest the below for triggering SearchTerms.

SearchTerms 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

Click events track user behaviour in Search.

In addition to tracking sync.SearchTerm for analytics, sync.Click is used to understand user behaviour, inform our ATS models through reinforcement learning, and track search attribution. sync.Click triggers on all user clicks of the Search Preview Widget and Search Results Page.

sync.Click events include the specific click action recorded in the ActionType field. All search sync.Click events must include the SearchTerm in the ContextData field (the only exception is ActionType 14 ClickFilterSort)

ATS requires sync.Click 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.

sync.Click 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)