Help

2 min read

Product List

Last Updated - Platform 25.0 - SDK 20.0

The Product List screen (PLP) is a core catalogue feature that uses the Search API to present product listing results for search queries, or categories. It surfaces dynamic filters and sort options driven by the API / feed.

product list 

# Search Results
products/search/{query}


# Category
products/category/{id}?title={title}

All parameters should be correctly percentage encoded (ex. spaces should be '%20'). Replace query with the search string.

# Recently Viewed
products/recentlyviewed


# Specific Products
products?ids={pid,pid,pid}
products?ids={pid,pid,pid}&external_ids={lid,lid,lid}

When using external_ids (listings) the number of ids should match. Replace pid,.. and lid,.. with comma separated arrays of product and listing identifiers respectively.

Set up

The Product List screen is automatically set up when linked to your app.

  1. Ensure the SDK and Platform are set up following the PoqSDK set up steps.
  2. Add the PoqProductList framework to your project following these steps.
  3. Configure your product image aspect ratio in your AppModule on didAddToPlatform.
// Use the tallest image ratio calculation for best results.
Settings.Catalogue.imageRatio = 207 / 250

Dynamic Content

Product List supports the following Dynamic Content slots as standard.

  • scroll-top: Before all other scroll content.

Adding slots to a collection view is a bit more complex as cells do not know the size of other cells. You will need to customise the ProductListView/makeLayout() functions as well as the data source to add custom slots.

Multiple Images

The Product List and Carousel cells support multiple images from v24 onwards. This can be enabled by removing the image limit (defaults to the first image only).

Settings.Catalogue.imageLimit = nil

Variant Grouping

Product listings work with variant groups instead of variants. These are sets of variants grouped by common forms (ex. red variants, wooden variants...) that visually change the appearance of the product.

Product listings have a slot for a variant group view at the bottom. Prior to v24 this was a 'More Colors' view to indicate there are other looks of the product to the user. With v24 we default to a swatches view to allow the user to switch the appearance of the listing to a different variant group.

Container.shared.views.variantGroupView.replace { FormSwitcherVariantGroupView() }
Container.shared.views.variantGroupView.replace { MoreVariantGroupView() }

Add to Cart

With the v22 improvements to the CartWidget the widget can be used anywhere to add a product to the cart. The CartWidget can fetch the full product if it doesn't have variant level information. For the Product List screen, listings are light-weight with only variant group information (for fast indexing) so the widget will make this call and briefly show loading to the user.

From v24 onwards we support this on the Product List screen (disabled by default). When enabled the widget is presented as a floating button over the bottom right of the image (similar to the wishlist button). To enable this customise the ProductListingView with a CartWidget using an IconCartButton.

Container.shared.views.productListingView.replace { PoqProductListingView(cartWidget: CartWidget(view: IconCartButton())) }

History

  • 20.0 (v25):
    • Reworked to use UICollectionViewCompositionalLayout for easier customisation and dynamic cell sizing.
    • Added scroll-top Dynamic Content slot.
  • 19.0 (v24):
    • Added dynamic API driven sort options replacing hardcoded options.
    • Added swatches as the default variant group view.
    • Added multiple-images and add to cart opt-in functionality.
  • 17.0 (v22):
    • Reworked cells to be self-sizing for reduced cell spacing.
    • Added coordinator to remove custom deeplink code and inconsistencies.
  • 12.0 (v18): Initial SDK release improving on the previous with dynamic filters.