constructor.io 3.4.0

dotnet add package constructor.io --version 3.4.0
NuGet\Install-Package constructor.io -Version 3.4.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="constructor.io" Version="3.4.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add constructor.io --version 3.4.0
#r "nuget: constructor.io, 3.4.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install constructor.io as a Cake Addin
#addin nuget:?package=constructor.io&version=3.4.0

// Install constructor.io as a Cake Tool
#tool nuget:?package=constructor.io&version=3.4.0

Constructor.io Netcore Client

Constructor.io provides search as a service that optimizes results using artificial intelligence (including natural language processing, re-ranking to optimize for conversions, and user personalization).

Documentation

Full API documentation is available on Github Pages

Requirements

Requesting results from your .NET based back-end can be useful in order to control result rendering logic on your server, or augment/hydrate results with data from another system. However, a back-end integration has additional requirements compared to a front-end integration. Please review the Additional Information For Backend Integrations article within the wiki for more detail.

Installation

  1. Follow the directions at Nuget to add the package to your project.
  2. Retrieve your API token and key. You can find this at your Constructor.io dashboard.
  3. Create a new instance of the client.
ConstructorioConfig config = new ConstructorioConfig("apiKey", "apiToken");
ConstructorIO constructorio = new ConstructorIO(config);

Uploading a Catalog

To upload your product catalog, you will need to create a CatalogRequest. In this request, you can specify the files you want to upload (items, variations, and item groups) and the section you want to send the upload. You can also set a notification e-mail to be alerted when a file ingestion fails.

// Create a files dictionary and add the relevant files
StreamContent itemsStream = new StreamContent(File.OpenRead("./catalog/items.csv"));
itemsStream.Headers.ContentType = new MediaTypeHeaderValue("text/csv");
StreamContent variationsStream = new StreamContent(File.OpenRead("./catalog/variations.csv"));
variationsStream.Headers.ContentType = new MediaTypeHeaderValue("text/csv");
StreamContent itemGroupsStream = new StreamContent(File.OpenRead("./catalog/item_groups.csv"));
itemGroupsStream.Headers.ContentType = new MediaTypeHeaderValue("text/csv");

Dictionary<string, StreamContent> files = new Dictionary<string, StreamContent>()
{
    { "items", itemsStream },
    { "variations", variationsStream },
    { "item_groups", itemGroupsStream },
};

// Create a CatalogRequest with files to upload and the section to upload to
CatalogRequest request = new CatalogRequest(files);
request.Section = "Products";

// Set a notification e-mail
request.NotificationEmail = "integration@company.com";

// Set the force flag if the catalog should be processed even if it will invalidate a large number of existing items
request.Force = true;

// Send a request to replace the catalog (sync)
CatalogResponse response = await constructorio.Catalog.ReplaceCatalog(request);

Retrieving Autocomplete Results

To retrieve autocomplete results, you will need to create an AutocompleteRequest. In this request you can specify the number of results you want per autocomplete section. If the results are for a specific user, you can also create a UserInfo object, which will allow you to retrieve personalized results.

// Create an AutocompleteRequest with the term to request results for
AutocompleteRequest request = new AutocompleteRequest("rain coat");

// Define the number of results to show per section
request.ResultsPerSection = new Dictionary<string, int>
{
    { "Products", 6 },
    { "Search Suggestions", 8 },
};

// Create a UserInfo object with the unique device identifier and session
UserInfo userInfo = new UserInfo("device-id-1123123", 5);
request.UserInfo = userInfo;

// Add a variations map to request specific variation attributes as an array or object (optional)
VariationsMap variationsMap = new VariationsMap();
variationsMap.AddGroupByRule("url", "data.url");
variationsMap.AddValueRule("variation_id", AggregationTypes.First, "data.variation_id");
variationsMap.AddValueRule("deactivated", AggregationTypes.First, "data.deactivated");
request.VariationsMap = variationsMap;

// Request results as an object
AutocompleteResponse response = await constructorio.Autocomplete.GetAutocompleteResults(request);

Retrieving Search Results

To retrieve search results, you will need to create a SearchRequest. In this request you can specify the number of results you want per page, the page you want, sorting instructions, and also filter the results by category or facets. If the results are for a specific user, you can also create a UserInfo object, which will allow you to retrieve personalized results.

// Create a SearchRequest with the term to request results for
SearchRequest request = new SearchRequest("peanut butter");

// Add in additional parameters
request.ResultsPerPage = 5;
request.Page = 1;
request.SortBy = "Price";
request.Filters = new Dictionary<string, List<string>>()
{
    { "Brand", new List<string>() { "Jif" } }
};

// Add the following paramaters to request for hidden fields
request.HiddenFields = new List<string>
{
    "hidden_price_field",
    "hidden_brand_field",
};

// Add the following paramaters to request for hidden facets
request.HiddenFacets = new List<string>
{
    "hidden_price_facet",
    "hidden_brand_facet",
};

// Create a UserInfo object with the unique device identifier and session
UserInfo userInfo = new UserInfo("device-id-1123123", 5);
request.UserInfo = userInfo;

// Add a variations map to request specific variation attributes as an array or object (optional)
VariationsMap variationsMap = new VariationsMap();
variationsMap.AddGroupByRule("url", "data.url");
variationsMap.AddValueRule("variation_id", AggregationTypes.First, "data.variation_id");
variationsMap.AddValueRule("deactivated", AggregationTypes.First, "data.deactivated");
request.VariationsMap = variationsMap;

// Faceting expression to scope results, it is applied before other filters and doesn't affect facet counts
string preFilterExpressionJObject = @"{
    or: [
        {
        and:
            [
            { name: 'group_id', value: 'BrandXY' },
            { name: 'Color', value: 'red' },
        ],
        },
        {
        and:
            [
            { name: 'Color', value: 'blue' },
            { name: 'Brand', value: 'XYZ' },
        ],
        },
    ],
}";
JsonPrefilterExpression preFilterExpression = new JsonPrefilterExpression(preFilterExpressionJObject);
request.PreFilterExpression = preFilterExpression;

// Request results as an object
SearchResponse response = await constructorio.Search.GetSearchResults(request);

Retrieving Browse Results

To retrieve browse results, you will need to create a BrowseRequest. When creating the BrowseRequest the filter name can be one of collection_id, group_id, or a facet name (i.e. Brand). In this request, you can also specify the number of results you want per page, the page you want, sorting instructions, and also filter the results by category or facets. If the results are for a specific user, you can also create a UserInfo object, which will allow you to retrieve personalized results.

// Create a BrowseRequest with the filter name and filter value to request results for
BrowseRequest request = new BrowseRequest("group_id", "8193");

// Add in additional parameters
request.ResultsPerPage = 5;
request.Page = 1;
request.SortBy = "Price";
request.Filters = new Dictionary<string, List<string>>()
{
    { "Brand", new List<string>() { "Jif" } }
};

// Add the following paramaters to request for hidden fields
request.HiddenFields = new List<string>
{
    "hidden_price_field",
    "hidden_brand_field",
};

// Add the following paramaters to request for hidden facets
request.HiddenFacets = new List<string>
{
    "hidden_price_facet",
    "hidden_brand_facet",
};

// Create a UserInfo object with the unique device identifier and session
UserInfo userInfo = new UserInfo("device-id-1123123", 5);
request.UserInfo = userInfo;

// Add a variations map to request specific variation attributes as an array or object (optional)
VariationsMap variationsMap = new VariationsMap();
variationsMap.AddGroupByRule("url", "data.url");
variationsMap.AddValueRule("variation_id", AggregationTypes.First, "data.variation_id");
variationsMap.AddValueRule("deactivated", AggregationTypes.First, "data.deactivated");
request.VariationsMap = variationsMap;

// Faceting expression to scope results, it is applied before other filters and doesn't affect facet counts
string preFilterExpressionJObject = @"{
    or: [
        {
        and:
            [
            { name: 'group_id', value: 'BrandXY' },
            { name: 'Color', value: 'red' },
        ],
        },
        {
        and:
            [
            { name: 'Color', value: 'blue' },
            { name: 'Brand', value: 'XYZ' },
        ],
        },
    ],
}";
JsonPrefilterExpression preFilterExpression = new JsonPrefilterExpression(preFilterExpressionJObject);
request.PreFilterExpression = preFilterExpression;

// Request results as an object
BrowseResponse response = await constructorio.Browse.GetBrowseResults(request);

Retrieving Browse Results for Item ID's

To retrieve browse results for a supplied list of item ID's, you will need to create a BrowseItemsRequest. When creating the BrowseItemsRequest the itemIds parameter will be a list of item ID's. In this request, you can also specify the number of results you want per page, the page you want, sorting instructions, and also filter the results by category or facets. If the results are for a specific user, you can also create a UserInfo object, which will allow you to retrieve personalized results.

// Create a BrowseItemsRequest with the filter name and filter value to request results for
BrowseItemsRequest request = new BrowseItemsRequest(Arrays.asList("t-shirt-xxl"));

// Add in additional parameters
request.ResultsPerPage = 5;
request.Page = 1;
request.SortBy = "Price";
request.Filters = new Dictionary<string, List<string>>()
{
    { "Brand", new List<string>() { "Jif" } }
};

// Add the following paramaters to request for hidden fields
request.HiddenFields = new List<string>
{
    "hidden_price_field",
    "hidden_brand_field",
};

// Add the following paramaters to request for hidden facets
request.HiddenFacets = new List<string>
{
    "hidden_price_facet",
    "hidden_brand_facet",
};

// Create a UserInfo object with the unique device identifier and session
UserInfo userInfo = new UserInfo("device-id-1123123", 5);
request.UserInfo = userInfo;

// Request results as an object
BrowseResponse response = await constructorio.Browse.GetBrowseItemsResults(request);

Retrieving Recommendation Results

To retrieve recommendation results, you will need to create a RecommendationsRequest. In this request, you can also specify the number of results you want and the items (given the ids) that you want to retrieve recommendations for. If the results are for a specific user, you can also create a UserInfo object, which will allow you to retrieve personalized results.

// Create a RecommendationsRequest with the pod id to request results for
RecommendationsRequest request = new RecommendationsRequest("pdp_complementary_items");

// Add in additional parameters
request.NumResults = 5;
request.ItemIds = new List<string> { "9838172" };

// Create a UserInfo object with the unique device identifier and session
UserInfo userInfo = new UserInfo("device-id-1123123", 5);
request.UserInfo = userInfo;

// Add a variations map to request specific variation attributes as an array or object (optional)
VariationsMap variationsMap = new VariationsMap();
variationsMap.AddGroupByRule("url", "data.url");
variationsMap.AddValueRule("variation_id", AggregationTypes.First, "data.variation_id");
variationsMap.AddValueRule("deactivated", AggregationTypes.First, "data.deactivated");
request.VariationsMap = variationsMap;

// Request results as an object
RecommendationsResponse response = await constructorio.Recommendations.GetRecommendationsResults(request);

Retrieving All Tasks

To retrieve all tasks, you will need to create a AllTasksRequest. In this request you can also specify the page and number of results per page. The page and number of results per page will default to 1 and 20 respectively.

// Create a AllTasksRequest to request results for
AllTasksRequest request = new AllTasksRequest();

// Add in additional parameters
request.Page = 2;
request.ResultsPerPage = 10;

//Request all tasks as an object
AllTasksResponse response = await constructorio.Tasks.GetAllTasks(request);

Retrieving Task with Task ID

To retrieve a specific task with a task_id, you will need to create a TaskRequest.

// Create a TaskRequest with the task_id to retrieve
TaskRequest request = new TaskRequest("12345");

//Request task as an object
Task response = await constructorio.Tasks.GetTask(request);

Development

Using VS Code

  • Download ".NET Core Test Explorer" Extension
  • In settings ⇒ .NET Core Test Explorer ⇒ Test Project Path: Constructorio_NET/Constructorio_NET.Tests

Testing

  • Make sure you have .NET SDK V6 installed
  • Open your terminal and navigate to the test directory:
    cd src/Constructorio_NET.Tests/
    
  • Run the following command to execute tests:
    dotnet test
    

For code coverage:

  • if initial setup:
    • dotnet husky install
  • dotnet husky run -g coverage

Documentation

  • Documentation generated by Doxygen for Mac OS X 10.14 and later
Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
3.4.0 220 2/13/2024
3.3.2 1,432 11/29/2023
3.3.0 340 11/17/2023
3.2.0 1,637 8/1/2023
3.1.0 559 7/21/2023
3.0.0 8,160 6/28/2023
2.13.1 558 5/31/2023
2.13.0 525 5/25/2023
2.12.0 586 5/5/2023
2.11.0 3,796 4/27/2023
2.10.0 1,770 4/6/2023
2.9.0 587 4/4/2023
2.8.2 703 3/28/2023
2.8.1 630 3/28/2023
2.8.0 1,570 3/23/2023
2.7.1 643 3/21/2023
2.7.0 646 3/18/2023
2.6.1 887 3/8/2023
2.6.0 2,474 2/23/2023
2.5.0 708 2/23/2023
2.4.2 680 2/23/2023
2.4.1 671 2/18/2023
2.4.0 1,117 2/3/2023
2.3.0 746 1/23/2023
2.2.2 1,420 12/8/2022
2.2.1 770 12/7/2022
2.2.0 838 11/9/2022
2.1.2 812 11/8/2022
2.1.0 803 11/8/2022
2.0.0 1,024 8/9/2022
1.0.9 1,661 4/5/2018
1.0.8 1,503 2/15/2018
1.0.7 1,489 5/2/2017
1.0.6 1,512 4/25/2017
1.0.5 1,743 11/5/2016
1.0.4 1,499 10/24/2016
1.0.3 1,500 10/17/2016
1.0.2 1,548 6/9/2016
1.0.1 1,595 6/2/2016
1.0.0 1,539 6/1/2016
0.0.4 1,508 4/16/2016
0.0.3 1,593 3/29/2016
0.0.2 2,459 10/30/2015
0.0.1 3,036 10/28/2015