Integrating Contentstack with Constructor.io

Constructor.io is a cloud-based product discovery solution designed for enterprise e-commerce platforms. With its enhanced search results powered by machine-learning and natural language processing it optimizes customer experience across digital platforms.

Additional resources: Learn more about constructor.io and its offering on its official website. To know about its working, refer to its how it works page.

In this guide, we will walk you through the steps involved in setting up search capabilities on your Contentstack-powered website using Constructor.io.

Process Overview: In this guide, we have demonstrated the steps for using the collections and auto complete features of Constructor. We have created a content type in Contentstack that has all product's details. The same products get reflected in the Constructor dashboard.

Collection is a term in Constructor.io, and is directly created in the Constructor.io dashboard which consumes the products reflected in Constructor.io from Contentstack. When any changes are made to the products in Contentstack, the same gets reflected in the Constructor dashboard.

Additional resources: For quicker search results, you can structure the product data on your e-commerce website using the Constructor Automation Hub Connector.

Prerequisites

1. Contentstack account
2. Constructor account
3. The latest version of Node.js installed on your computer
4. Access to Amazon Web Services
5. Basic understanding of Contentstack features such as working with stacks, content type, webhooks, extension, and entries
6. Working knowledge of API

Steps for Execution

1. Generating the Constructor API Token
2. Setting up the webhook configuration
3. Creating collections in Constructor
4. Setting up the collection extension in Contentstack
5. Setting up Collections in Contentstack
6. Implementing the auto-complete feature
7. Deploying the sample project

1. Generating the Constructor API Token

   For this exercise, we have assumed that you already have a working Constructor account with you. If you haven't created an account yet, visit the official website and sign up with one of their plans. 

   Now that you have the account ready, we will need the Constructor API token so that we can use its API integration features. To do this, follow the steps given below: 

   1. Log in to your Constructor account. You'll be on the Dashboard page inside the Home tab as shown below:
      
      
      
      
   2. Then, click on the Integration tab at the top and select API Integration. You'll get the API key as shown below:
      
      
      
      Alternatively, you can click on the arrow next to your username at the top right corner and then select Account. Click on API Integration to get to the same page shown above.
      
   3. On the Generate New API token screen, click on the Generate API Token button. You'll get a Generate New API Token pop-up screen.
      
      
      
      Click on the Display my new token button to generate the new API token. Note that the API token will be visible just once, so ensure that you have copied it for later use.
      
      We will use these tokens to establish communication between Contentstack and Constructor to update product collection.
      

   Now that we have the tokens handy, let's discuss the steps to configure the webhook.

2. Setting up the Webhook Configuration

   Let's set up a webhook that will invoke the lambda function to execute the required operations.

   1. Go to your stack, click on the Settings icon on the left navigation panel, and select Webhooks.
   2. Click on the + New Webhooks button located at the top of the page. 
   3. On the Create Webhooks page, provide the following webhook details:
      
      
      1. Name (mandatory):- Provide a name for the webhook.
         
      2. URL to notify:- Specify the HTTP post endpoint for the webhooks URL. where the data will be sent once the webhook is triggered.
         
         

         Note: In your case, it will be the API gateway endpoint generated using serverless.js framework.

      3. HTTP basic auth username (optional): Provide the username of the HTTP basic auth if you intend to use Basic Authentication to secure your webhook.
         
      4. HTTP basic auth password (optional): Provide the password of the HTTP basic auth.
         
      5. Custom headers (optional): This field lets you add any additional header into the HTTP POST request. You can add multiple headers by clicking the + icon.
         
      6. When (mandatory): Set the conditions for the webhook to trigger. Here, you need to define the event when the webhook will be triggered. Specify the conditions inside the Conditional View tab: 
         
         
         
         
         
      7. Click on the Save button. 

   Now that we have the webhook set up ready, let's move ahead and create collections in Constructor. 

3. Creating Collections in Constructor

   In Constructor, you can create landing pages that are based on manual lists or automated rules of products by using Collections. This helps you to enhance search and browse and product discovery experience.

   To create a collection in Constructor, follow the steps given below:

   1. Click on the Collections tab at the top of the Constructor Dashboard page and then on the ADD NEW COLLECTION button as shown below:
      
      
      
      
   2. On the Collections Pages screen, enter the Display name for your collection and click on CREATE as shown below:
      
      
      
      

      Note: The ID field gets filled automatically as you type the Display name. However, you can edit the ID if required.

   3. On your collection page, you can add items to your collection in the following two ways:
       
      1. By uploading the CSV file that has your list of items using the ADD ITEMS button.
      2. By adding items with conditions.
         
         
         
         
   4. Once you have added the items using the conditions click on SAVE.

   For this exercise, we have created a few collections. One of them is Weekly Wines Special, as shown below:
   

   

   In the above condition, we have specified to list products that do not belong to the Country Chile. So based on this condition, if we click on VIEW, the following products pops up:
   

   

   
   Similarly, you can create additional collections as required. Let's now create an extension that will be used within the modular block.

4. Setting up the Collection Extension in Contentstack

   To set up the extension, log in to your Contentstack account and proceed with the following steps:

   1. Go to your stack, and click on the “Settings” icon on the left navigation panel.
      
   2. Click on Extensions. You can also use the shortcut keys “alt + X” for Windows OS users, and “option + X” for Mac OS users to access the extensions menu. 
   3. On the Extensions page, click on the + New Extension button. 
   4. Then click on Create new as shown below:
      
      
      
      
   5. In the Select Extension Type window, select Custom Field.
      
      
      
   6. On the Create New Extension page, enter values in the fields as given below: 
      1. Title (required): Provide a suitable title, for example Collection, for your custom field. This title will be visible when you select the extension in the custom field in your content type.
      2. Field data type (required): Select the data type in which the input data of the field should be saved in Contentstack. In this case, select JSON.
      3. Multiple (optional): Leave this field unchecked. 
      4. Hosting method (required): Select Hosted by Contentstack as the hosting method for this content type. 
      5. Extension source code: (required): Specify the extension code here. Contact our Support team to get the code for the extension.
   7. Once you have added these details, click on Save.

   The following is the pictorial representation of the code that we have used as extension source code showing the "Consumption of AWS API endpoint" for fetching ‘List of Collections’: 
   

   

   Now that we have the extension ready, let's move ahead and understand how to set up the collections feature in Contentstack.

   Setting up Collections in Contentstack

   The product list that you see above in Constructor is actually fetched from Contentstack. All your products are managed at the Contentstack end and accordingly they are displayed in Constructor.

   To integrate Constructor.io Collection with Contentstack, we have created a content type named Home that has the following structure:
   

   

   As you can see above, the content type consists of a Title field, a URL field, a Modular Block field with several fields inside it, and a Global field. 

   The entry of this Home content type is shown below:
   

   

   As seen above, the Modular Block field has a block named Collections (which is an extension) that contains the following fields: 

   1. Title: Specifies the title or the name of the collection you want to have.
   2. Number of items: Specifies how many items/data you want to show from the list of items/data from that particular collection.
   3. Select Collection: Specifies which collection you want to select from the list of available collections.

   If the collection you are searching for is not available in the list, you can create a new one by clicking on the ‘link’ at the bottom of this extension as shown below:
   
   

   

   Let's now set up the extension in Contentstack
   

   Setting up Serverless with AWS

   We have created the serverless to serve the Constructor.io Collections API endpoint in AWS. The AWS endpoint fetches the "List of Collections" using the Collections API from Constructor.io. 

   Below is the snippet of "API Call Routes Setup" in serverless for "Constructor.io Collections API": 

   

   
   In the above code snippet, the url key has the following value:
   

   https://ac.cnstrc.com/v1/collections?key=${constructor_api_key}§ion=Products

   Where, constructor_api_key Is the API key of your Constructor.io account we created in step 1.

   Integrating Contentstack Collection Extension with Demo Site

   We have created a demo website for the example. We have created the "Collections Extension" and added it to the schema of the required content type in Contentstack. For this example, we have added it to the Home content type.

   Inside the demo site, we have added a code set up to fetch the items/data for that particular collection. The code makes use of the Constructor.io Node package along with API Key to initialize the Constructor.io object. 

   This object contains the browse.getBrowseResults() method which consumes the Collection Id that we received from Collection Extension and fetches the items/data. The following is the pictorial representation of the code for this integration. We have created a ‘Nunjucks Filter’ to integrate the API with frontend nunjucks: 
   

   

   The Outcome of the Integration 

   Below is the pictorial representation of the "Collections" on the demo site. Here, we have selected the "Weekly Wines Specials" (we discussed above) collection from the extension: 
   

   

   You can select other collections simply from the Collections extension and publish the entry.

   

   Now that we have seen how to set up the collection in Contentstack and use the feature in Constructor, it's time to move ahead and understand how to implement the auto-complete feature.

5. Implementing the Auto-complete Feature

   To implement the auto-complete feature, you can use any of the methods as discussed below.

6. 
   Using jQuery 

7. To install with jQuery, use the following code snippet:

8. <script type="text/javascript">
     $.getScript("//cnstrc.com/js/cust/<your_custom_bundle_name>.js", function () {
       $("#query").constructorAutocomplete({
         key: "<your_api_key>",
       });
     });
   </script>

9. In the above example, #query is the DOM selector of your search box and <your_api_key> can be found on your dashboard as discussed in step 1. Also for the <your_custom_bundle_name>.js, get in touch with the Constructor.io support team.

10. 
    Using HTML/JavaScript

11. To install using HTML/JavaScript, use the following code snippet:

12. <script
      type="text/javascript"
      src="https://cnstrc.com/js/cust/<your_custom_bundle_name>.js"></script>
    
    <script>
      const inputElement = document.querySelector("#query");
      const autocomplete = new ConstructorioAutocomplete(inputElement, {
        key: "<your_api_key",
      });
    </script> 

13. Additional resource: For more information, refer to these links: autosuggest_client, autosuggest client installation, autosuggest client methods, and autosuggest client advanced options. 
    

14. Integrating Constructor.io Search Page with Contentstack

15. To integrate Constructor.io Search page with Contentstack, use the following steps:

1. Install the npm package. This package can be installed through npm as shown below:
   
   
   npm i @constructor-io/constructorio-node

   
   
2. Once installed, import the package into your repository.
   
   

   Note: This library should only be used in a server-side context.

3. Retrieve the API key and token. You can find these in your Constructor.io dashboard. Contact sales if you'd like to sign up, or support if you believe your company already has an account.
4. Implement the Client. Once imported, an instance of the client can be created as follows:
   
   
   const ConstructorIOClient = require('@constructor-io/constructorio-node');
   var constructorio = new ConstructorIOClient({
       apiKey: 'YOUR API KEY',
   });
   

   
   
5. We have used the following method to retrieve the results:
   
   
   constructorio.search.getSearchResults('<search-query>', {
       resultsPerPage: <result page option>,       ---- this is option
       filters: {
           <option1 >: “ ” ,       
       },
   });

   
   A real-world use case of the above method is shown in the following example:
   
   
   constructorio.search.getSearchResults('t-shirt', {
       resultsPerPage: 40,           // result page display option
       filters: {
           size: 'medium'   // Filter option 
       },
   });

16. 
    References

17. To get the complete API documentation, visit the GitHub Pages. For information, refer to the following links:

1. REST API Search 
2. Search Queries
3. Search Results
4. Results Structure
5. Group Structures
6. Facets Structure

18. Deploying the Sample Project

    The sample app that we have developed for this example uses the webhook integration. If you want to deploy this webhook integration, the following are the requirements: 

    1. An AWS account
    2. AWS CLI installed locally
    3. API credentials for your AWS account are configured in your AWS CLI locally by running AWS configure
    4. Serverless framework installed locally via npm -g install serverless
    5. Clone the project from our GitHub repo or contact support

    Once you have the prerequisites ready, follow these steps to deploy this project: 

    1. Switch to the current working directory of the project and get inside the constructor_webhooks folder. 
    2. Then, run npm install to install all the necessary dependencies.
    3. Update the configuration file as mentioned below:
       
       
       app: constructor-webhook
       service: constructor-webhook
       
       frameworkVersion: '2'
       
       Provider:
          name: aws
          runtime: nodejs12.x
          stage: stag
          region: us-east-1
          stackName: ${self:service}-${sls:stage}
          apiName: ${self:service}-${sls:stage}
          lambdaHashingVersion: 20201221
          profile: constructor
         deploymentPrefix: ${self:service}
       
       Functions:
          Webhook:
          handler: handler.handler
          Events:
            - http:
                path: /{proxy+}
                method: any
                cors: true
       
       <strong>Note</strong>: To deploy without the dashboard, you will need to remove the org fields from the serverless.yml file.

       
       
    4. Run sls deploy to deploy the stack.
    5. After running deploy, you should see output similar to:
       
       
       

       
       Note: In the current form, after deployment, your API is public and can be invoked by anyone. For production deployments, you might want to configure an authorizer. For details on how to do that, refer to HTTP event docs.

    Invocation

    After the successful deployment, you can call the created application via HTTP. We have used the following endpoint for webhooks configuration:

    curl https://xxxxxxx.execute-api.us-east-1.amazonaws.com/stag/api

    Triggering the Webhook

    Use the steps to trigger the webhook that we created in step 2. Then follow the steps given below:

    1. Go to the products entry page and publish/unpublish the entry.
       1. On publish, the product will get listed on Constructor.io.
       2. On unpublish or delete of the product, it will get delisted from Constructor.io. 
          
          
          
          
          
    2. You will find the listed products in the Product section in Constructor.io as shown below:
       
       
       
       
       

    Removing all Resources

    After you’ve finished working with this example, remove all resources to make sure you’re not getting billed for unused resources. 

    Run sls remove to remove all resources.