Kentico.Xperience.StoreApi 0.1.0-prerelease-2

Xperience by Kentico - KX 13 E-Commerce integration

This integration is currently a Proof of Concept (PoC). For further details, please refer to the Support section and the KenticoLabs tag associated with this feature.

Name	Package
Kentico.Xperience.K13Ecommerce
Kentico.Xperience.Store.Rcl
Kentico.Xperience.StoreApi

Description

This integration is primary intended for existing Kentico Xperience 13 (KX 13) E-Commerce projects to enable them to migrate to new Xperience By Kentico (XbyK) and still use KX 13 E-Commerce functionality.
It can also be used as a basis for new projects where E-Commerce data will be stored on KX 13, but further development is necessary to achieve this goal.

This solution covers several scenarios according to the complexity of integration between XByK and KX 13:

Product listing widget

• We recommend to use this widget for simple scenarios such as Landing page offers, etc.
• Product listing widget example is located in Dancing Goat XbyK example project.
• The widget is used to display products directly from KX 13, purchase itself still takes place on Kentico 13.
• The widget has a couple of properties based on the Store property selector which enable to display products for given category, culture and currency.

Full scale e-commerce solution

• We recommend to use for possible partial migration of existing e-commerce projects from KX 13 to XbyK.
• Product data (with variants and images) is synchronized to Content hub (can be turned off).
• Product listing, detail and checkout process are placed on XbyK (shopping cart is saved and calculated still on KX 13).
• Orders are created from cart, order related data is saved on KX 13 side.
• Products need to be manually linked from Content hub to pages in website channel applications. You can use CI to restore examples of content types for pages that display products. See this section of User Guide for detailed information.
• Sample XbyK Dancing Goat site implements store functionality and can be used as an example of migration of existing e-commerce projects to new XbyK.

The integration provides an API with services for implementing the following scenarios:

• Listing products based on parameters, product categories, prices and inventory
• Actions with shopping cart, changing currency and order creation
• Listing of orders (currently suitable for implementing listing orders in administration)
  • Order updates and listing for specific customers are under development
• Listing site cultures and currencies
• Check this part of User Guide for more specific description

Project structure

There are currently 2 solutions:

Kentico.Xperience.K13Ecommerce.sln

Complete solution with all libraries and sample sites:

• Kentico.Xperience.StoreApi - library for Kentico 13 that exposes a REST API for an E-Commerce site.
• Kentico.Xperience.K13Ecommerce - library for XbyK connecting to the REST Store API running under Kentico 13.
• Kentico.Xperience.Store.Rcl - Razor Class Library for selector components.
• Sample Dancing Goat sites
  • DancingGoat.csproj - XbyK Dancing Goat (live site channel + administration) enriched with integration to KX 13 Dancing Goat to show how to create simple e-shop with product listing, product detail and checkout process on XByK.
  • Kentico13_DancingGoat.csproj - KX 13 Dancing Goat example (live site) with configured Store API to demonstrate how you can set up REST Store API on your own KX 13 e-commerce solution.
• KX 13 administration project (CMSApp) is not part of this solution!

Kentico.Xperience.K13Ecommerce.Libs.sln

• Contains only libraries without sample sites, used for publishing of NuGet packages

Library Version Matrix

Summary of libraries which are supported by the following versions Xperience by Kentico / Kentico Xperience 13

Kentico Xperience 13 E-Commerce integration

Dependencies

Xperience by Kentico application:

• ASP.NET Core 8.0
• Xperience by Kentico

Kentico Xperience 13 application (or standalone API app):

• ASP.NET Core 6.0
• Kentico Xperience 13 Refresh 11

Package Installation

Xperience by Kentico

Add these packages to your XbyK application using the .NET CLI

dotnet add package Kentico.Xperience.K13Ecommerce
dotnet add package Kentico.Xperience.Store.Rcl

Kentico Xperience 13

Add this package to your Kentico Xperience 13 ASP.NET.Core application (live site or create standalone application when your KX 13 live site is not running)

dotnet add package Kentico.Xperience.StoreApi

Quick Start

Kentico Xperience 13

First set up your Kentico 13 ASP.NET Core application:

1. Set up your own settings for Store REST API authentication (based on JWT and OAuth client credentials flow)

{
  "CMSStoreApi": {
    "Jwt": {
      "Key": "YourSecretKeyForAuthenticationOfApplicationMustBeAtLeast64CharsLong",
      "Issuer": "yourCompanyIssuer.com",
      "Audience": "XbyK-DancingGoat",
      "TokenExpiresIn": 60
    },
    "ClientId": "3ef7fe1b-696c-4afa-8b56-d3176b7bea95",
    "ClientSecret": "********************"
  }
}

2. Add Store API services to application services and configure Swagger

// Startup.cs

public void ConfigureServices(IServiceCollection services)
{
    // ...
    //Store API registration
    services.AddKenticoStoreApi();
    //Registers Swagger generation
    services.AddKenticoStoreApiSwagger();
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment environment)
{
    //Registers Swagger endpoint middleware and swagger UI
    app.UseStoreApiSwagger();
}

Xperience By Kentico

Then set up your Xperience By Kentico application

1. Fill settings to connect your Kentico Xperience 13 instance

{
  "CMSKenticoStoreConfig": {
    "StoreApiUrl": "http://dev.dancinggoat.com:65375",
    "ClientId": "3ef7fe1b-696c-4afa-8b56-d3176b7bea95",
    "ClientSecret": "********************",
    "ProductSyncEnabled": true,
    "ProductSyncInterval": 10
  }
}

2. Add K13Ecommerce library to the application services

// Program.cs

// Registers Kentico Store API and services for e-commerce support
builder.Services.AddKenticoStoreServices(builder.Configuration);

3. For the simplest scenario: copy product listing widget from Dancing Goat example project to your project and configure properties to display products from KX 13.
4. For more complex scenario with full e-shop, you can be inspired by implementation of Dancing Goat sample Store on XbyK. Check Usage guide for detailed instructions to configure categories, products and cart steps.
5. Restore CI repository files to database (reusable content types, custom activities). CI files are located in .\examples\DancingGoat-K13Ecommerce\App_Data\CIRepository\ and you need to copy these files to your application.

dotnet run --kxp-ci-restore

6. Start to use on your live site

Full Instructions

View the Usage Guide for more detailed instructions.

Contributing

To see the guidelines for Contributing to Kentico open source software, please see Kentico's CONTRIBUTING.md for more information and follow the Kentico's CODE_OF_CONDUCT.

Instructions and technical details for contributing to this project can be found in Contributing Setup.

License

Distributed under the MIT License. See LICENSE.md for more information.

Support

This contribution has Kentico Labs limited support.

See SUPPORT.md for more information.

For any security issues see SECURITY.md.