Using Profile Lists

Background

Omneo Lists allows products to be grouped together into lists that are implicitly linked to a customer profile. These lists can have specific attributes that make them capable of delivering a wide range of customer experiences online and in store. A simple use case is a simple ‘omnichannel wishlist’ which is one list (with a unique handle of ‘wishist’) that the customer can add and remove products to from the website. This list can then be visible (or even editable) on the customer profile, in the app and in clienteling experiences in store)

📘

This guide documents the use of configuring Omneo Lists on your front end using the Omneo Shapes SDK. Because the code discussed in this guide should be implemented on your frontend, modifications to your eCommerce front end are necessary to deliver the wishlist experience to your customers.

🚧

Session level lists

Omneo Lists can only be attached to existing customer profiles - we currently do not support session level lists that are not attached to a logged in / known customer.

Before you begin

• Become familiar with the ShapesSDK, as it is used in this guide.
• Successfully authenticate with Omneo using one of the supported methods.
  you may wish to complete the [Authentication] (https://omneo.readme.io/docs/authentication) guide first, and then continue below

If using an Omneo eCommerce plugin, this metafield will be generated automatically
Include the shapes CDN.
When using the CDN, the library will be attached to the window, and can be referenced using window.shapesSDK

JavaScript

<script type="text/javascript" src="https://cdn.omneo.io/shapes-sdk/shapes.sdk.js"></script>

Process Overview

1. Authenticate against Omneo
2. Initialise an authenticated shapesClient
3. Configure a ‘lists.ready’ event listener, to activate when the shapesClient.hydrate() has finished. Using this event, you can populate all items on the page with their wishlist state accordingly by using the shapesClient.find() method.
4. Configure a ‘lists.update’ event listener, to activate when the shapeClient data has been modified. Using this event, you can modify each product's wishlist state if it has changed since the last hydration event.
5. Hydrate the shapesClient with lists data, pulling the data from Omneo.
   Upon completion this will trigger the event configured in step 2.
6. Using the shapesClient, add a product to the wish list by using shapesClient.post()
   This will trigger the event configured in step 4.
7. Using the shapesClient, remove a product from the wish list by using shapesClient.delete()
   This will trigger the event configured in step 4

📘

Authenticate with Omneo First!

Before you begin continue below, make sure you have authenticated an initialised version of the shapesSDK client.

Complete the [Authentication] (https://omneo.readme.io/docs/authentication) guide first, and then continue below

Create an Omneo List called ‘Wishlist’

The ‘wishlist’ is a specific list created for the use of the website. Omneo can manage multiple lists - but creating a list with the handle ‘wishlist’ (if one with this name is not already created for the current profile) allows the website to behave they most people expect wishlists to behave

JavaScript

var list = 'lists'
   	shapesClient.post(list, {‘name’: wishlist, ‘handle’: wishlist}, true)
   	.then(()=>{
       	console.log('created list wishlist')
   	})

Retrieve List items from ‘wishlist’

Using the .hydrate() method, populate the shapes client with lists data.
This method is responsible for refreshing the shapes client with data from the Omneo API.
Doing this will instruct the shapesSDK to populate the client’s cache with the requested data. Upon completion the client will emit the event shapes.lists.ready

JavaScript

function displayList(data){
   console.log(data);
}
shapesClient.hydrate('lists');
shapesClient.on(lists.ready,displayList)

Access the retrieved data from step 1 by using the .find() method.
This method allows us to retrieve the cached data in the shapesSDK client.

Note: This method is not responsible for pulling in fresh data from Omneo, each time you wish to repopulate the data from the Omneo server, use .hydrate()

JavaScript

function displayList(data){
   var lists = shapesClient.find('lists').data
   console.log(lists)
}
shapesClient.hydrate('lists');
shapesClient.on('lists.ready',displayList)

Add current SKU/Variant to Wishlist

shapesClient provides methods for making authenticated requests
We can use the shapesClient.post() method to add to a list.
You can also use product_id, product_variant_id and product_variant_barcode to add items to a list.

JavaScript

shapesClient.post('list.wishlist.items', {'product_variant_sku': mySKU1234}, true)
   	.then(()=>{
       	console.log('added item to wishlist!')
  	})

Remove Item from list

shapesClient provides methods for making authenticated requests
We can use the shapesClient.delete() method to remove an item from the list

JavaScript

var deleteID = 'lists.wishlist.items.' + itemID
   	shapesClient.delete(deleteID, true)
   	.then(()=>{
       	console.log('deleted an item!')
   	})

Remove a List

Similar to the above, we can delete the entire list object by specifying the list without an item

JavaScript

var list = 'lists.wishlist'
   	shapesClient.delete(list, true)
   	.then(()=>{
       	console.log('deleted the whole wishlist!')
   	})

Event Tracking

Keeping track of events emitted by the shapesSDK will allow you to dynamically update the page based on the event. For example, you may wish to render the full wishlist and keep it up to date.

shapesSDK.on(‘lists.ready’, readyHandler)
shapesSDK.on(‘lists.update’, updateHandler)
.ready
Emitted on completion of a .hydrate() task.
.update
Emitted on completion of a client state update.