Register and update apps
Learn how to register a new app or to update an existing app in the Kustomer platform.
To register a new app or to update an existing app, create and send a Kustomer API call to upload a new or updated app definition to the appropriate Kustomer organization.
Getting a Kustomer API key
You can set up an API key in Kustomer under Settings > Security > API Keys. Create an API Key with the org.admin.apps
role. Learn more about creating API keys in: Kustomer Help Center | API Keys
Registering an app through the Kustomer API
To register a new app, make an API call using the POST method for the /v1/apps/available
endpoint. Authenticate the call with an API key for your organization and include the JSON app definition as the body.
You can use tools such as Postman or cURL to construct and send your API request.
The body of the request must include the app definition including a valid version. For the first version, you'll use the following for the version
property: "version": "0.0.1"
.
Example cURL call to register an app to a Kustomer organization:
curl --location --request POST 'https://api.kustomerapp.com/v1/apps/available'
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API-token-goes-here>' \
--data-raw '{
"app": "hello_world_example",
"version": "0.0.1",
"title": "Hello World",
"kviews": [{
"name": "hello-world-example.helloworld",
"template": "<div style={ { padding: '10px' } }>Hello, {_.get(customer, 'name')}!</div>",
"context": "smartbar-card",
"resource": "customer",
"meta": {
"displayName": "Hello World",
"icon": "earth",
"state": "open"
}
}]
}'
Once registered, an app will be available for installation from the app directory of the Kustomer organization linked with the API key.
Updating an app through the Kustomer API
To update an app, modify the version and body for the API request you used to register the app. Use the POST method to send the updated app definition to the same /v1/apps/available
endpoint.
In the updated app definition, you must include a new valid app version and can also include any relevant updates in the body of the definition (for example, link to updated release notes, an updated description, and so on).
Example cURL call to update an app to a Kustomer organization with a new version:
curl --location --request POST 'https://api.kustomerapp.com/v1/apps/available'
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API-token-goes-here>' \
--data-raw '{
"app": "hello_world_example",
"version": "0.0.2",
"title": "Hello World",
"kviews": [{
"name": "hello-world-example.helloworld",
"template": "<div style={ { padding: '10px' } }>Hello, {_.get(customer, 'name')}!</div>",
"context": "smartbar-card",
"resource": "customer",
"meta": {
"displayName": "Hello World",
"icon": "earth",
"state": "open"
}
}]
}'
Updating certain app fields without a version bump
The following fields can be updated without a version bump via PATCH /v1/apps/available/:appVersion
:
- title
- iconUrl
- description
- vendor
- website
- screenshots
- instructions
- releaseNotesUrl
- postInstallMessage
The endpoint's appVersion
path segment can either be <name>-<version>
or <name>-latest
. So for the hello_world_example
app it could be either hello_world_example-0.0.2
or hello_world_example-latest
.
Notice: While the endpoint is the same for both public and private apps, it can only be called by the org that initially registered the app. Therefore, if the app is a public app registered by the Kustomer team, it can only be updated by the Kustomer team.
curl --location --request POST 'https://api.kustomerapp.com/v1/apps/available/<appVersion>'
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API-token-goes-here>' \
--data-raw '{
"title": "Hello World!",
"description": "A Hello World App"
}'
Registering and updating an app through Kustomer App Starter Config
You can also use the available Kustomer App Starter Config repo to make it even simpler to register or update your app and to get started with building apps.
After you define your app and add the app to the index.js file, you can run npm run register-new-version <app-name>
to register or to update your app.
Troubleshooting
Having trouble with registering or updating an app? Here are some common things to check for and to try:
Duplicate app id
The app
property must be defined with an id that is globally unique to each Kustomer organization.
You will get the following error message in your JSON response if you try to register a new app with an app
id already registered to the same Kustomer organization:
...
"errors": [
{
"status": 409,
"source": {
"parameter": ""
},
"code": "duplicate"
}
]
...
Troubleshooting steps
Update your app definition so that the app
id is globally unique for the Kustomer organization. You can then submit the app definition again with the same version.
App won't install or upgrade from the app directory
An app registered or upgraded with errors in the definition might cause installation issues from within the app directory. If you are unable to install an app from the app directory or you run into app installation errors, you will need to update the app with the corrected version.
Troubleshooting steps
Step 1: Update the app with a minimal app definition
Submit a new version of the app definition that defines just the two app properties required to register an app: app
and version
.
Once you update the app definition, you should be able to upgrade and install the new version.
Step 2: Update the app with the correct app definition
Correct any errors in your original app definition. Submit the corrected full app definition under a new app version.
Once you register the corrected app definition, you should be able to upgrade to and install the new app version.
Updated about 3 years ago