constructor.io
3.3.2
See the version list below for details.
dotnet add package constructor.io --version 3.3.2
NuGet\Install-Package constructor.io -Version 3.3.2
<PackageReference Include="constructor.io" Version="3.3.2" />
paket add constructor.io --version 3.3.2
#r "nuget: constructor.io, 3.3.2"
// Install constructor.io as a Cake Addin
#addin nuget:?package=constructor.io&version=3.3.2
// Install constructor.io as a Cake Tool
#tool nuget:?package=constructor.io&version=3.3.2
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
- Follow the directions at Nuget to add the package to your project.
- Retrieve your API token and key. You can find this at your Constructor.io dashboard.
- 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 | Versions 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. |
-
.NETStandard 2.0
- Newtonsoft.Json (>= 13.0.1)
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 | 275 | 2/13/2024 |
3.3.2 | 2,037 | 11/29/2023 |
3.3.0 | 374 | 11/17/2023 |
3.2.0 | 1,831 | 8/1/2023 |
3.1.0 | 600 | 7/21/2023 |
3.0.0 | 8,481 | 6/28/2023 |
2.13.1 | 589 | 5/31/2023 |
2.13.0 | 557 | 5/25/2023 |
2.12.0 | 625 | 5/5/2023 |
2.11.0 | 3,955 | 4/27/2023 |
2.10.0 | 1,794 | 4/6/2023 |
2.9.0 | 620 | 4/4/2023 |
2.8.2 | 721 | 3/28/2023 |
2.8.1 | 664 | 3/28/2023 |
2.8.0 | 1,595 | 3/23/2023 |
2.7.1 | 681 | 3/21/2023 |
2.7.0 | 685 | 3/18/2023 |
2.6.1 | 926 | 3/8/2023 |
2.6.0 | 2,513 | 2/23/2023 |
2.5.0 | 737 | 2/23/2023 |
2.4.2 | 725 | 2/23/2023 |
2.4.1 | 706 | 2/18/2023 |
2.4.0 | 1,154 | 2/3/2023 |
2.3.0 | 767 | 1/23/2023 |
2.2.2 | 1,447 | 12/8/2022 |
2.2.1 | 818 | 12/7/2022 |
2.2.0 | 862 | 11/9/2022 |
2.1.2 | 844 | 11/8/2022 |
2.1.0 | 829 | 11/8/2022 |
2.0.0 | 1,056 | 8/9/2022 |
1.0.9 | 1,696 | 4/5/2018 |
1.0.8 | 1,538 | 2/15/2018 |
1.0.7 | 1,525 | 5/2/2017 |
1.0.6 | 1,545 | 4/25/2017 |
1.0.5 | 1,785 | 11/5/2016 |
1.0.4 | 1,534 | 10/24/2016 |
1.0.3 | 1,536 | 10/17/2016 |
1.0.2 | 1,581 | 6/9/2016 |
1.0.1 | 1,634 | 6/2/2016 |
1.0.0 | 1,573 | 6/1/2016 |
0.0.4 | 1,542 | 4/16/2016 |
0.0.3 | 1,629 | 3/29/2016 |
0.0.2 | 2,665 | 10/30/2015 |
0.0.1 | 3,247 | 10/28/2015 |