ClerkIO Integration

📢 Use this project, contribute to it or open issues to help evolve it using Store Discussion.

ClerkIO Integration

This Apps Allow Stores to integrate with the Recommendation Shelves that ClerkIO Provides.

Main Features

The app has the option of creating a feed per language and per binding supported on the store.
Design of the shelf and the recommendation comes from ClerkIO.
The Store can Declare the ClerkIO Block anywhere on their site and configure the Recommendation Logic as they need on VTEX Site-Editor.

Initial Setup

On the vtex cli run vtex install clerkiopartnerdk.integration-vtex. You can confirm that the app has now been installed by running vtex ls again.
Access the Apps section in your account's admin page and look for the ClerkIO Integration box. Once you find it, click on the box. Fill in the Fields as requested. For MultiBinding Sites, click on the enable configuration by binding to match a Clerk Store to each Binding.
Generate the feeds for products, categories and orders by making a POST request to the following endpoints (replacing the account and workspace):

Do a GET Request to this following endpoint: https://app.io.vtex.com/clerkiopartnerdk.integration-vtex/v1/{{accountName}}/{{workspace}}/_v/integration-vtex/clerk-feed/{{bindingId}}

It requires VtexIdclientAutCookie to be sent as header.

Notes:

The first call to the generation of the feed will respond with an empty array. Depending on the size of your store Catalogue the feed might take some time to generate

* There is a known issue with the generation of the orders feed

Configuration VTEX Search & Recommendations

Important: Before proceeding please make sure you have already completed the setup in ClerkIO following the instructions below

On your store theme, Add clerkiopartnerdk.integration-vtex 1.x as a theme peerDependency in the manifest.json file
```
"peerDependencies": {
"clerkiopartnerdk.integration-vtex": "1.x"
}
```
add the clerkio_recommendations block anywhere on your store. Example: in home.json

{
  "store.home": {
    "blocks": [
      "responsive-layout.desktop#homepage",
      "responsive-layout.mobile#homepage"
    ]
  },
  "responsive-layout.desktop#homepage": {
    "children": ["clerkio_recommendations"]
  }
}

Note: for this step onwards, please make sure you have already completed the configuration on ClerkIO steps 1 - 4.

Go to VTEX Site Editor, and on the right side menu a ClerkIO block will be displayed. Click on it.
Fill in the information required on the block. Block Class Name: insert unique identifier for the block within the page it is used on. Eg. clerk-product-page-alternatives Template Name: insert the ID provided by Clerk on the previously created Content. Product Logic: match the recommendation logic to the one specified on the previously created Content on Clerk. User can get the details and usage for different product logics on Clerk.io. The available product logics are:

Product Logic	Details
Best Sellers
Hot Products
Newest Products
Best Sellers In Category	Send a category id as `data-category` to Clerk block. When block is placed in a category page, the category id can be obtained from the page context. User can also manually add a category id via site editor.
Hot Products In Category	Send a category id as `data-category` to Clerk block. When placed in a category page, the category id can be obtained from the page context. User can also manually add a category id via site editor.
Newest Products in Category	Send a category id as `data-category` to Clerk block. When placed in a category page, the category id can be obtained from the page context. User can also manually add a category id via site editor.
Best Alternative Products	When added into a product page, sends the product id as `data-products` to Clerk block. Product id is obtained from context.
Best Cross-Sell Produts	When added into a product page, sends the product id as `data-products` to Clerk block. Product id is obtained from context.
Recommendations Based On Keywords	User can add a list of keywords via site editor that will be sent to Clerk as `data-keywords`
Visitor Recommendations
Visitor Alternatives
Visitor Click History
Recommendations Based On Orders	If there is a user logged in the store, the block will send the user email to Clerk as `data-email`
Similar To Order History	If there is a user logged in the store, the block will send the user email to Clerk as `data-email`
Customer Order History	If there is a user logged in the store, the block will send the user email to Clerk as `data-email`
What Customers Look At Right Now
Recently Purchased Products

You can also implement a search page in the same manner, by adding a block to your theme. The search page block is called: clerkio_searchpage

The App will also create a dedicated search page route on /clerk-search?searchTerm=__QUERY__. This route already has the clerkio_searchpage block added in the body.

The App also creates a component search input field for use in your header: clerkio_searchinput. By default this input field takes you to the dedicated page route created by the app.

Predictive search can also be enabled through the component named: clerkio_livesearch. This will listen for keystrokes on a selected input field and give real time search results.

Both clerkio_searchpage and clerkio_livesearch have fields available in the Site Editor where you can control use of facets, translation texts.

Live search and search page can be used independently, but the search page will only take the query as searchTerm from the urls params by default.

clerkio_categorypage:

Parameters:

Block Class Name :: Class Name in DOM. Eg. category-page-popular

Template Name :: Template Content Name from clerk.io. Eg. @category-page-popular

Facets :: Attributes to be used for facets, separated by commas. Eg. price,categories

Facets Titles :: Attribute titles as rendered in the facets. Eg. price:Prix,categories:Collection

Multiselect Facets :: Attributes to be used for facets, with multiple allowed selections within a group. Eg. price,categories

Filter Button Text :: Localized Text Message for Facets toggle button. Eg. Options

View More Button Text :: Localized Text Message on the View More Button on facets with more than 12 entries. Eg. Show All

Search for ... Text :: Localized placeholder in the text filter field within a facet group. Eg. Recherche ici

Facets Design ID :: The ID of the custom Facets Design Template you may wish to use. Eg. 123455

Facets Price Append :: The Symbol you may wish to append to prices in the facets.

Facets Price Prepend :: The Symbol you may wish to prepend to prices in the facets.

clerkio_searchpage:

Parameters:

Block Class Name :: Class Name in DOM. Eg. product-page-alternatives

Template Name :: Template Content Name from clerk.io. Eg. @product-page-alternatives