Installation

Using the CLI

1. Download the cartridge source from the Partner Marketplace.

2. Unzip the directory.

3. Install the dependencies from the unzipped directory.

   Shell

   Copy

   1
   2
    cd /path/to/unzipped/folder
    npm install
   

4. Create a dw.json file in the directory where you just installed the NPM dependencies, and add the following content:

   JSON

   Copy

   1
   2
   3
   4
   5
   6
   {
     "hostname": "...",
     "username": "...",
     "password": "...",
     "code-version": "..."
   }
   

   • hostname is the hostname you use to access your sandbox, for example "zzgk-001.sandbox.us01.dx.commercecloud.salesforce.com",
   • username and password are your account manager email and password,
   • code-version is the name of the active code version in Administration → Code Deployment. For example, "SFRA_AP_05_15_2020".

5. Upload the cartridges by executing the following command.

   Shell

   Copy

   1
   npm run uploadCartridge
   

6. Verify that the Algolia cartridges are correctly uploaded by going to Administration → Development Setup → Folder Browser → Cartridges.

Using Salesforce UX Studio

1. Download the cartridge source from the Partner Marketplace.

2. Establish a new digital server connection with your SFCC instance.

3. Import the cartridges to a workspace in Salesforce UX Studio.

4. Add the cartridges to Project Reference.

5. Wait until Salesforce UX Studio completes the workspace build and uploads the source codes to your SFCC instance.

Enable the cartridges on your site

Algolia provides the following cartridges to integrate with your SFCC storefronts:

1. Go to Administration → Sites → Manage Sites.
   Select your desired site from the Storefront Site list:

2. Go to the Settings tab. The site cartridges you will need to assign depend on the type of architecture of your site:

   • If your site is based on SFRA, add int_algolia_sfra:int_algolia at the beginning of your cartridge path.
   • If your site is based on SiteGenesis,
     (a) add algolia_sg_changes:int_algolia_controllers at the beginning of your cartridge path, and
     (b) add int_algolia at the end of your cartridge path.
   • If your site is based on a headless architecture, add int_algolia at the beginning of your cartridge path.

   

Next, add the cartridge to the Business Manager:

1. Go back to Administration → Sites → Manage Sites and click on Manage the Business Manager Site.

2. Go to the Settings tab, and add bm_algolia:int_algolia at the end of your cartridge path.

Import metadata

1. Go to Administration → Site Development → Site Import & Export. and upload the algolia.zip archive from the metadata folder.

2. To import algolia.zip, select the radio button next to it and click the import button.

3. Confirm the import is successful.

Set Algolia custom preferences for your site

1. Go to Merchant Tools → Site Preferences → Custom Preferences.

2. Select Algolia in Custom Site Preferences Groups.

3. Set Enable Algolia to Yes.

4. Fill in your Application ID, Search API Key and Admin API Key. You can find these in the Algolia Dashboard

5. Set the Read Host Base Url to https://sfcc-stream.algolia.com.

6. Set up your custom fields (or attributes) from our list of attributes. We recommend starting with the following attributes: name,short_description, long_description, price, brand, color, size and image_groups.

7. Set your OCAPI credentials:

   • OCAPI client ID: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa,
   • OCAPI client password: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.

   These are placeholder credentials. You need to provide them for the Algolia integration to work, but we don’t currently use them. You can use whichever placeholder you need.

Add service credentials

1. Go to Administration → Operations → Services → Service Credentials → algolia.http.api.cred

2. In the URL field, add https://sfcc-stream.algolia.com. You can leave the User and Password fields empty.

To keep your logs from overflowing, only turn on communication logs when you really need them.

Enable Algolia in the Business Manager

1. Go to Administration → Organization → Roles & Permissions

2. Select the Role for which you’d like to enable access (e.g. Administrator)

3. Go to the Business Manager Modules tab.

4. Select the checkbox next to Algolia and press Update at the end of the settings page.

Update your templates

This section is only relevant for sites using SiteGenesis or SFRA. If you are using a headless architecture, refer to our dedicated guide on using a headless architecture in SFCC with Algolia.

This section is only relevant if you haven’t enabled the Algolia cartridge and are using the base cartridge. Algolia cartridge already contains those changes.

1. In app_storefront_base/cartridge/templates/default/common/htmlHead.isml, add the following code on line 32:

1
<isinclude template="algolia/headerScripts" />

1. In app_storefront_base/cartridge/templates/default/components/header/search.isml, add the following code at the start of the file, and move existing the code to an <iselse> section:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<isset name="algoliaData" value="${require('*/cartridge/scripts/algolia/lib/algoliaData')}" scope="page" />
<isif condition="${algoliaData.getPreference('Enable')}">
    <div class="site-search">
        <div id="suggestions-wrapper"
            data-category="${pdict.cgid}"
            data-category-display-name-path="${pdict.categoryDisplayNamePath}"
            data-category-display-name-path-separator="${pdict.categoryDisplayNamePathSeparator}"
            data-q="${pdict.q}"
            data-search-page-root="${URLUtils.http('Search-Show')}"></div>

        <input
            type="search"
            id="aa-search-input"
            class="aa-input-search form-control"
            placeholder="${Resource.msg('label.header.searchwatermark', 'common', null)}"
            name="search"
            autocomplete="off" />

    </div>
<iselse/>
   ... existing code ...
</isif>

1. In app_storefront_base/cartridge/templates/default/search/searchResult.isml, search for the following line of code:

1
<isinclude template="search/searchResultsNoDecorator" />

and replace it with the following code:

1
2
3
4
5
<isif condition="${pdict.algoliaEnable}">
    <isinclude template="algolia/search/searchResultsNoDecorator" />
<iselse/>
    <isinclude template="search/searchResultsNoDecorator" />
</isif>