Constructor.io App Installation Guide

Constructor.io is a product discovery platform developed specifically for enterprise e-commerce platforms. It optimizes customer experience across digital platforms with enhanced search results powered by machine learning and natural language processing.

With Marketplace, you can now easily install the Constructor.io application and use it within your stack to link your entries to the collections in your Constructor.io account.

Prerequisites

• Constructor.io account
• Contentstack account
• Access to the Contentstack Organization/Stack as the Owner/Admin

This step-by-step guide explains how to install and configure Constructor.io within your stack.

Steps for Execution

1. Get your credentials from Constructor.io
2. Create Collections in Constructor.io
3. Install and Configure Constructor.io in Contentstack Marketplace
4. Map and Save Entries from Contentstack to Constructor.io
5. Use Constructor.io within your Stack

Let's look at the steps in detail.

1. Get your credentials from Constructor.io

   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.

   To generate the Constructor API Key, 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 the Integration tab at the top and select API Integration. You'll get the API key as shown below: 
   
   3. On the Generate New API token screen, click the Generate API Token button. You'll get a Generate New API Token pop-up screen. 
   
   4. Click 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.

   Note: Add "=" at the end of the generated API token. Convert this to base64 format before using it in constructor.io app config.

2. Create Collections in Constructor.io

   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 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 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 by uploading the CSV file that has your list of items using the ADD ITEMS button and by adding items with conditions. 
   
   4. Once you have added the items using the conditions click SAVE.

   For example, 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.

3. Install and Configure Constructor.io app in Contentstack Marketplace

   To install the application in Contentstack, follow the steps below:

   1. Login to your Contentstack account.
   2. On the left-hand-side primary navigation, you will find a new icon for Marketplace (as shown below). Click the icon to go to the Marketplace. 
   
   3. Within the Marketplace, you will be able to see all the apps available, hover over the Constructor.io app and click Install App.
   
   4. In the popup window, select the stack for which you want to install the Constructor.io app.
   5. Accept the terms of service and privacy policy and click Install.  
   
   6. On the resulting Configuration page, under Step1: Constructor Fields, enter the Constructor.io API token, API key , and Index Section Name, and click Finish. 
   

   Note: If you want to save your published Contentstack entries in Constructor.io, then refer to the Map and Save Entries from Contentstack to Constructor.io section.

   7. Click the Open Stack button to start using the Constructor.io application.

4. Map and Save Entries from Contentstack to Constructor.io

   Data mapping helps match fields from one database with fields from another database. A connection is created by connecting a field in one source with a field in another.

   If you want to save data from your published Contentstack entries in Constructor.io, follow the steps below:

   1. On the Configurations page, toggle on the Enable Webhook button present under step 1 and select Next.
      This opens the second step, Contentstack Fields. 
   
   2. Add the Contentstack Environments where you will be publishing your entries. 
   3. Select the Content Type from which you wish to save entry data in Constructor.io:  
   
   4. On clicking Next, the Mapping Rules field appears.
   

   Without Mapper:

   Suppose you want to save data in Constructor.io without using a mapper. In that case, your content type schema should match the Constructor.io schema. You need to add fields within your content type whose UIDs match the field names provided in the JSON Parameters section of the Add or Update an Item in Constructor.io document. 

   

   Note: If you do not provide the Constructor.io fields according to the type of data it accepts, then Constructor.io returns an error that you can view in webhook logs. This also results in your published entry not being saved in Constructor.io.

   Your content type in Contentstack should have fields with item_name and url as UIDs similar to Constructor.io's item_name and url fields. The Contentstack entry data will not be saved in Constructor.io if these fields are missing.

   With Mapper:

   If your content type schema does not match the Constructor.io schema, you need to map individual fields from your content type schema to your Constructor.io fields. 

   

   Note: When you add a mapping rule, it is mandatory to map Contentstack fields to Constructor.io's item_name and url fields. The Contentstack entry data will not be saved in Constructor.io if these fields are not mapped.

   Since only flat structures are visible in the fields dropdown list, you can map nested or complex structures using the New Field option. 

   

   For example,

   • While mapping nested fields, you must specify the object and its field using the dot(.) notation. For example, Object.age for accessing the age field within the object.
   • While mapping arrays, use indexing. For example, Array[1] for accessing the second value of an array.
   • You can use the above rules to create mapping rules for complex structures that include objects and arrays.
   

   Similarly, you can also add new fields in Constructor.io field options using the New Field option.

   Note: Once you map a Constructor.io field, you cannot edit it. You will need to delete and create a new rule.

   Warning: When you unpublish or delete an entry of the specified content type in Contentstack, its saved data in Constructor.io will also be removed.

   5. Once you are done with the steps, on selecting the Finish button, Reset Configuration button appears. You can select this to reset the configuration. 
   
   6. Click Save to save these configurations and start publishing entries in Contentstack to save them in Constructor.io.
   

   Your entry details in Constructor.io would look like this: 

   

   You can view the status of your published, unpublished, or deleted entries in the webhook logs section. You can also check the webhook logs to confirm if your credentials are successfully saved. 

   

5. Use Constructor.io app within your Stack

   To use the Constructor.io application within an entry of your stack, follow the steps given below:

   1. Go to your stack and click the “Content Models” icon on the left navigation panel, and click the + New Content Type button.
   2. Create a content type by adding relevant details as displayed below: 
   
   3. In the Content Type Builder page, add a Custom field in your content type by clicking on the “Insert a field” link represented by a + sign.
   4. Under Select Extension or App, select Constructor.io and click Proceed.  
   
   5. After adding the app, click Save or Save and Close to save your changes. 
   
   6. To use the Constructor.io app, create an entry for this content type, and you will see this Constructor.io custom field on your entry page.
   7. Under the Collection custom field, select the collections from your Constructor.io account and link them to your entry. 
   
   8. The collection you select is linked to your entry. You can now save and publish your entry as it is.