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 the Constructor.io app 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 can see the Home tab under the Dashboard section. 
      
   2. Click the Integration tab at the top and then select API Integration. You can 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 click 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 VIEW, the following products pops up: 
   

   

   
   

   Similarly, you can create additional collections as required.

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

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

   1. Log in to your Contentstack account.
   2. In the left-hand side primary navigation, click the Marketplace icon to go to the Marketplace.
      
   3. Click Apps from the left panel.
   4. Within the Marketplace, you can see all the available apps. Hover over the Constructor.io app and click Install App.
      
   5. In the popup window, select the stack where you want to install the Constructor.io app and click the Authorize & Install button.
      
      
   6. On the Configuration screen, enter the Constructor.io API token, Constructor.io API key, and Constructor.io Index Section Name retrieved in step 1, and then click Finish.
      

   Additional Resource: 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 Save button.
   8. Click Open Stack 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 name and url fields. The Contentstack entry data will not be saved in Constructor.io if these fields are not mapped.
   • The Constructor.io item_name field is renamed as name. New users can see the field name as name, but existing users can see item_name until the app is updated.

   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.
      
   You can see your entry in the Constructor.io account.
   
    

   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 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, click the Content Models icon in 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 the Insert a field link represented by a + sign.
   4. Under Select Extension/App, select Constructor.io and click Proceed.
      
      This adds Constructor.io in the custom field.
      
   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. In the left navigation panel, navigate to the Entries page and click + New Entry to create a new entry for the above content type, and then click Proceed.
      You can see the Constructor.io app’s custom fields on your entry page as shown below:
      
   7. Under the Collections custom field, select the collection from your Constructor.io account and link them to your entry. 
      
   8. The collection you selected is linked to your entry. You can now Save and Publish your entry.