Kibo eCommerce Java SDK

This topic explains how to develop Kibo eCommerce applications using the Kibo eCommerce Java SDK.

Before You Begin

Install the following software on your local machine:

In addition to the listed software, you need access to a Dev Center Account that contains a provisioned sandbox.

Don't have a Dev Center Account? Request a Demo

Get Started

The following steps guide you through installing the Kibo eCommerce Java SDK, authenticating your project with your Kibo eCommerce credentials, and making a call to the Kibo eCommerce API. Specifically, the tutorial demonstrates how to create a console application that retrieves the number of customer accounts for a Kibo eCommerce site, teaching you the necessary concepts for then building a fully-fledged application of your own.

Create a Kibo eCommerce application in Dev Center with the appropriate behaviors:

  1. Log in to Dev Center.
  2. Create a new Kibo eCommerce application.
  3. Add the Customer Read behavior to the application. This step is necessary to give your application the necessary permissions to read customer accounts. If you design additional functionality for your application, such as updating an order, add the appropriate behaviors to avoid a permissions error.
  4. Install the application to the sandbox of your choice.
  5. Enable the application in Admin.Note:  If you decide to add additional behaviors to your application after this step, you must reinstall the application to your sandbox and re-enable the application in Admin to apply the new behaviors.
  6. Note the application key, shared secret, tenant ID, and site ID. Tip:  You can obtain the application key and shared secret from the application details page. You can obtain the tenant ID and site ID by viewing your live site through Site Builder and looking at the URL, which has the pattern tTenantID‑sSiteID.sandbox.mozu.com. You can obtain the master catalog ID through a GetTenant API call, which also returns the tenant ID and site ID, but the master catalog ID is not required for the API call used in this tutorial.

Create a Java application that uses the Kibo eCommerce Java SDK:

  1. Create a new directory on your local machine.
  2. Within the new directory, create the following folder structure, which follows the Java convention for structuring applications:
  3. Within the src/main/java directory, create a two-level folder structure with a meaningful name for the application you are building. For example, for this tutorial, you can create the following folder structure:
  4. The lowest level folder (which for this tutorial is GettingStarted) is the folder that contains the main class for your application. Navigate to this folder and create a Java file called GetCustomerAccountsCount.java.
  5. Open GetCustomerAccountsCount.java for editing and add the following code:Tip:  While Kibo eCommerce allows authenticating using only an application's shared secret, it is highly recommend that you encrypt the shared secret to prevent unauthorized users and/or applications obtaining access. To learn how to do this, refer to the Kibo eCommerce Java SDK topic.
    yourAppDirectory/src/main/java/yourCompany/GettingStarted/GetCustomerAccountsCount.java
    package yourCompany.GettingStarted;
    
    import com.mozu.api.MozuApiContext;
    import com.mozu.api.contracts.appdev.AppAuthInfo;
    import com.mozu.api.resources.commerce.customer.CustomerAccountResource;
    import com.mozu.api.security.AppAuthenticator;
    
    public class GetCustomerAccountsCount {
    	public static void main(String[] args){
    		AppAuthInfo appAuthInfo = new AppAuthInfo();
            
    		/** replace with your authentication configuration */
    		appAuthInfo.setApplicationId("yourApplicationKey");
    		appAuthInfo.setSharedSecret("yourSharedSecret");
            
    		AppAuthenticator.initialize(appAuthInfo);
            
    		/** replace with your tenant ID and site ID */
    		MozuApiContext apiContext = new MozuApiContext(yourTenantID, yourSiteID);
    		
    		/** create a customer account resource */					
    		CustomerAccountResource customerAccountResource = new CustomerAccountResource(apiContext);
    		
    		/** log the total number of customer accounts */
    		try {
    			System.out.println("Number of Customer Accounts: " + customerAccountResource.getAccounts().getTotalCount());
    		} catch (Exception e) {
    			e.printStackTrace();
    		}
    	}
    }
  6. Save your changes.
  7. In your project's root directory, create a file called build.gradle. Within this file, install the Kibo eCommerce Java SDK as a dependency and specify the build framework, as shown in the following code block:Tip:  You can find the SDK version by going to Maven Central and searching for Mozu. The main SDK package is mozu-api-java. If you click on a version of that package, you can find the needed dependency information for Gradle under the Dependency Information section.
    yourAppDirectory/build.gradle
    // specify your package and version
    group 'yourCompany.GettingStarted'
    version '1.0-SNAPSHOT'
    
    // specify a Java application							
    apply plugin: 'java'
    // specify an executable application
    apply plugin: 'application'
    
    // specify Maven Central as the repository for dependencies
    repositories {
    	mavenCentral()
    }
    
    // specify your main class name
    mainClassName = 'yourCompany.GettingStarted.GetCustomerAccountsCount'
    
    // specify a certain version of Gradle
    task wrapper(type: Wrapper) {
    	gradleVersion = '2.12'
    }
    
    // specify a certain  version of the Mozu Java SDK, in addition to the standard test dependencies and exclusions. 
    dependencies {
    	testCompile group: 'junit', name: 'junit', version: '4.11'
    	compile  ('com.mozu:mozu-api-java:1.19.8') {
    		exclude group: 'javax.sql'
    		exclude group: 'javax.transaction'
    		exclude group: 'jcs'
    		exclude group: 'javax.servlet'
    	}
    }
  8. Save your changes.

Run your application:

  1. Open a command prompt in your project's root directory.
  2. Run gradle wrapper to generate the Gradle files.
  3. Run gradlew.bat run or ./gradlew.bat run to execute your application. After it builds, the application logs the number of customer accounts to the console.

About the Toolkits

Maven Package Name Description
mozu-api-java The Kibo eCommerce Java SDK package.

View the source on GitHub
mozu-api-core The subpackage that contains API resources and contracts.

View the source on GitHub
mozu-api-toolkit A package that adds common code and classes.

View the source on GitHub
mozu-java-security A package that adds security features, such as encrypting your shared secret.

View the source on GitHub

Encrypt the Shared Secret

Kibo eCommerce allows authenticating using only an application's shared secret; however, Kibo eCommerce highly recommends encrypting this shared secret to prevent unauthorized users and/or applications obtaining access.

You can use Kibo eCommerce's Java based encryption application to generate an encrypted shared secret. This encryption application takes a predefined salt key along with your application's shared secret and hashes them together to create an encrypted shared secret, which you can then use in the SharedSecret field in the configuration file where you specify the shared secret.

Note:  The encryption application is in a private GitHub repository. Contact Kibo eCommerce Support with your Github username for access to the Mozu/mozu-java-security repository.

To encrypt your application's shared secret:

  1. Clone the encryption application's source code, available at Mozu/mozu-java-security.
  2. Run the command gradlew clean build installApp distZip.
    This command builds the application and creates a Windows batch file, as well as a distribution zip file.
  3. Go to root\build\install\mozu-java-security\bin.
  4. Run mozu-java-security.bat and follow the prompts:
    1. Enter the salt key—Enter your predefined salt key that will be hashed together with your shared secret.
    2. Enter value to encrypt—Enter your application's shared secret.
  5. The encryption application returns your encrypted value. You can use this value in the SharedSecret field in your configuration file.

SDK Function Reference

The Kibo eCommerce Java SDK provides dozens of built-in functions that help you interact with the Kibo eCommerce API quickly and easily. To familiarize yourself with these functions:

  1. View the Kibo eCommerce Java Core SDK source on GitHub.
  2. Navigate to the src/main/java/com/mozu/api directory. From there, select the appropriate folder based on the type of function you are looking for, or use the repository search box (on GitHub) to find the function you are looking for. The files in the resources directory mirror the structure of the Kibo eCommerce API.

For example, to find the functions related to customer segments, you would view the CustomerSegmentResource.java file located in the src/main/java/com/mozu/api/resources/commerce/customer directory.