Skip to main content

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​

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.

Products API Documentation

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.

Config API Documentation

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

Search API Documentation

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.

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

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

Events API Documentation

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.

Event: Clicks Documentation

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.

Event: Purchases

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

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 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)