README

Commerce Layer Algolia Importer

A Javascript library that lets you easily import your ecommerce catalog into Algolia.

What is Commerce Layer?

Commerce Layer is a headless platform that lets you easily build enterprise-grade ecommerce into any website, by using the language, CMS, and tools you already master and love.

How it works
Getting started
- Installation
- Import
Usage
Adding prices to the search

How it works

Commerce Layer Algolia Importer is designed to make it quick and simple to import your products data, index them into Algolia, and eventually get their prices from Commerce Layer and add them to the search.

This importer is CMS-agnostic — you can import your content data from any CMS of your choice, according to any content model you defined.

Getting started

To get started and import your data into Algolia you need to install the importer and retrieve your credentials from your Algolia account.

Installation

Commerce Layer Algolia Importer is available as an npm package:

// npm
npm install @commercelayer/algolia-importer

// yarn
yarn add @commercelayer/algolia-importer

Import

You can use the ES6 default import as follows:

import importer from '@commercelayer/algolia-importer'

Usage

The importer function

Commerce Layer Algolia importer function returns as a promise an array of Algolia index objects — one for each of your selling countries (associated with the specified translation). You need to pass to it as a parameter an object containing at least:

algoliaConfig — your Algolia app ID and admin API key
items — the list of products you want to index

importer({
  algoliaConfig: {
    appId: 'your-algolia-app-id',
    adminApiKey: 'your-algolia-admin-api-key'
  },
  items: yourItems,
}).then((results) => {
    console.log(results)
})

The items array

items is an array of objects. It has to be properly built by specifying the language code, the country code, and a list of key/value parameters related to the single variants:

// Typescript types

{
  [languageCode: string]: {
    [countryCode: string]: {
        customRanking: number
        reference: string
        objectID: string
        category: string[] | string
        description: string
        name: string
        code: string
        image: string
    }[],
    marketId?: string
  }[]
}[]

// Example

[
  {
    'en-US': [
      {
        us: [
          {
            customRanking: 0,
            reference: 'your-reference',
            objectID: 'your-objectID',
            category: 'your-category',
            description: 'your-description',
            name: 'your-variant-name',
            code: 'your-sku-code',
            image: 'your-image-url'
          }
        ]
      }
    ]
  }
]

For each item you can define a custom ranking by setting the customRanking parameter — the lower its value the higher the item will be ranked within the search results.

Default settings

Commerce Layer Algolia importer comes with some default values for its main parameters:

showPrice: false,
clConfig: {
  clientId: '',
  endpoint: '',
},
algoliaIndexPrefix: 'store'
algoliaSettings: {
  searchableAttributes: [
    'category',
    'code',
    'description',
    'name',
    'reference',
  ],
  customRanking: ['asc(customRanking)'],
  attributesForFaceting: ['category'],
  distinct: 1,
  attributeForDistinct: 'reference',
  replicas: [],
}

The algoliaSettings object can be overridden at your leisure — please refer to Algolia documentation for more info on how to set their API parameters.

Adding prices to the search

Our Algolia importer lets you import from Commerce Layer the prices of each product you want to index and sort (ascending or descending) your search result by price. To do that, just set the showPrice parameter to true and add the clConfig object with your Commerce Layer organization credentials, remembering to specify the market in scope at a country code level in the items array:

const items = [
  {
    'en-US': [
      {
        us: [
          {
            customRanking: 0,
            reference: 'your-reference',
            objectID: 'your-objectID',
            category: 'your-category',
            description: 'your-description',
            name: 'your-variant-name',
            code: 'your-sku-code',
            image: 'your-image-url'
           }
        ],
        marketId: 'your-market-id'
      }
    ]
  }
]

importer({
  algoliaConfig: {
    appId: 'your-algolia-app-id',
    adminApiKey: 'your-algolia-admin-api-key'
  },
  items: items,
  showPrice: true,
  clConfig: {
    clientId: 'your-client-id',
    endpoint: 'https://yourdomain.commercelayer.io'
  }
})

This way, all the prices are added to the related index and two Algolia replicas (price_asc and price_desc) are automatically created.

License

This repository is published under the MIT license.

@commercelayer/algolia-importer

Usage no npm install needed!