Use the App Starter Config repo

Learn how to use the Kustomer App Starter Config repository to develop and register apps with app configuration templates and NPM commands.

Kustomer apps extend the functionality and flexibility of the Kustomer platform and support integrations with other services.

As a developer, you can create different types of apps for organizations to install from the Kustomer App Directory. Users can install apps to customize, automate, and build on the Kustomer platform.

Kustomer app templates and starter config

To help you get started with your first Kustomer app, we've provided app templates based on common Kustomer app configurations. Each configuration includes inline comments to explain the different components of the app configuration in the template.

We've also provided NPM commands you can use to generate app JSON definitions and to register and update apps to your Kustomer organization easily.

Prerequisites

This Kustomer App Starter Config repo on GitHub is designed to help developers create apps on the Kustomer Apps Platform.

To use this repository and related NPM commands to register and update apps, you will need the following:

Kustomer org and API access

You will need access to a Kustomer organization for the following information:

• The API base URL for your organization

  • Example: https://<my_org_name>.api.kustomerapp.com

• A valid API Key that includes the following roles at the minimum: org.admin.apps and org.permission.apps

If you do not have access to a Kustomer account, see Get access.

NPM

This repository includes NPM commands used to generate app JSON definitions and to register and update app definitions for your Kustomer organization.

Make sure you have the latest versions of Node.js and NPM installed for your machine.

Kustomer Apps Platform knowledge

We also recommend a basic understanding of Kustomer Apps and the App Object Model.

How to use this repo

To use the Kustomer App Starter Config templates to create a new app, you'll need to do the following:

1. Select the Use this template option in GitHub to create a new repository. The new repository will start with the same files and folders as the kustomer-apps-starter-configs repo. You can then clone the new repository to your local machine.

2. Use the demo app templates to create a new app directory to configure your app definition.

3. Create a .env file in the root of the local repository, and include the environment variables defined within the provided .env.example file and a value for each variable. The variables are:

   API_BASE_URL=https://<organization-name>.api.kustomerapp.com
   API_TOKEN=<API key>
   

4. Configure the root index.js file to include your app definition in the apps array, if you create a new app definition.

5. Use the npm run register-new-version [app] command in this repo to register or to update an app for your Kustomer organization. See Register or update an app with commands.

Structure

We've provided an overview of the app template repo structure below:

• ./src: This folder contains the main portion of the app templates repo. The ./src folder contains the root index.js file and subfolders for each app template.

  • App template subfolders: Each app template subfolder contains the different app properties for that app. We use index.js files with commands to bundle together these app property files into the complete app JSON definition.

  • index.js: The root file we will use to hold all of the available apps. We can use the index.js file to import and to include new apps in the available apps array. The get-app-json and register-new-version commands available to use with this repo will pull available JSON from this file.

• .env.example: This file stores an example template for your .env file, including a Kustomer API base URL and API key as environment variables. The npm command in this repo pulls these environment variables to register and update apps. You will need to update this file with the appropriate environment variables for your Kustomer organization.

Demo app templates

The ./src folder contains app templates for common Kustomer app configurations. Each app template subfolder contains a folder for each app property and any necessary index.js files required to bundle the app definition through commands.

While these demo app templates contain different app properties, you can create a single Kustomer app that supports and defines all of these possible app properties.

Once you feel comfortable with these demo app configurations, you can experiment and combine different app properties, such as advanced KViews, Outbound Webhooks, and Workflows, to create powerful, feature-rich app experiences for Kustomer users.

In the meantime, we've provided an overview of some of the demo app templates in the starter repo:

my-first-app

Use this app template as the most minimalist example of installing an app to Kustomer.

• Contains an index.js file for the root apps array and a kviews subfolder with an index.js file and a JavaScript file with the KViews app property.

my-first-advanced-kview-app

Use this app template to create an app that installs a more advanced KView. This advanced KView can load an external URL in an iFrame. If the external site includes the Kustomer Cards SDK, the KView can communicate with the Kustomer instance.

• Contains an index.js file for the root apps array and a kviews subfolder with an index.js file and a JavaScript file with the KViews app property.

my-first-outbound-webhook-app

Use this app template to create an app that installs an outbound webhook in Kustomer.

• Contains an index.js file for the root apps array and a outbound-webhooks folder with an index.js file and a JavaScript file with the outbound webhooks app property.

📘

Outbound webhooks review for public apps

The Kustomer Apps Platform team reviews apps that require outbound webhooks during the submission process for public apps.

If your public app uses an outbound webhook, the outbound webhook must be mission critical to the app, and your team will need to create a privacy TOS agreement with Kustomer before the public release of the app. The Kustomer team may also request additional security information to notify app users that their data will be sent to a third party.

my-first-widget-app

Use this app template to create an app that installs a widget in Kustomer. Widgets are similar to KViews that appear in the Insight panel and use the Cards SDK. However, unlike KViews, widgets load an iFrame-based widget in Kustomer that users can access on any page of the Kustomer platform and not just in the Insight panel.

• Contains an index.js file for the root apps array and three subfolders (i18n, settings, widgets), each with an index.js file and a file, subfolder, or files for the appropriate app property:
  • i18n: Contains an index.js file and a language locale subfolder (for example, en_us) with the JSON language strings for settings and widgets.
  • settings: Contains an index.js file and a JavaScript file with the settings app property.
  • widgets: Contains an index.js file and a JavaScript file with the widgets app property.

App properties

You can develop Kustomer apps to include a variety of app properties to configure Kustomer further.

Descriptions of supported app properties and interfaces are available in the app starter config _docs folder available in the repository. These interfaces can help you understand the following:

• The config object for a given app inside of ./src/app-name/index.js
• How to properly create an app config using the appropriate properties

You can also view more detailed descriptions for these app properties in the "App Object Model" section of the Apps Platform documentation.

Internationalization

One important property of the app definition is the i18n, or internationalization, property. This property allows an app developer to provide translations in as many locales as their app supports and use en_us as a fallback locale.

While the i18n property may not be required for your app, define the internationalization property to provide an improved experiences for your app users.

For explanations of the supported translated fields and the appropriate format for the field key, see Internationalization.

Register or update an app with commands

This repo includes the following NPM command: npm run register-new-version [app].

The command pulls environment variables from your customized .env file to register a new app configured for your Kustomer organization. You can use the same command to publish a new version of an existing app.

When you publish an app, your app name or app property must meet the following criteria:

1. The app property value must be unique to your organization. If you start from one of these templates, we recommend adding a postfix to the app property, starting with an underscore, followed by a value to distinguish the app property value. For example, my_starter_app_myKustomerOrg01_01.

2. You cannot use any of the app values for the templates included in this repo (they are, my_first_advanced_kview_app, my_first_app, my_first_outbound_webhook_app, and my_first_widget_app.

👍

Always update app versions to post app changes

Update the semver version of the version property when you make POST requests to update your app with changes. Your request will fail if you try to post app changes without a new version. To learn more, see Register and update apps.

See Register and update apps to learn how to register and update apps manually with the output from the npm get-app-json [app] command and an API call with tools like Postman.

📘

When should I register and update apps manually?

The app starter config repo and npm run register-new-version [app] command work best for most cases. However, you can use npm run get-app-json [app] to view or to generate a JSON app definition to register or to update your app manually.

Common use cases for manual app registration and updates include debugging, registering and updating apps with tools like Postman, developer preference, or as a fallback when there's an error in the app starter config repo.