App content guidelines

When you register an app to an organization, the app appears in the Kustomer App Directory.

The app directory listing describes what the app does and the benefits to installing it. After a user installs an app, additional content will be available in the settings page if a settings page was defined for the app.

We’ve shared some guidelines on how to create effective content for your users and how the JSON definition informs how your app description appears in the following locations:

• The app directory listing
• The app details page
• The app settings page (if a settings page is defined)

App directory listing and details page

The Kustomer App Directory displays a listing for each app available to the user.

The app directory listing shows basic information about the app including the following:

• App title
• Icon
• Version
• Description (displays up to 110 characters)

When a user selects an app listing, they can view the app details page with the following additional information:

• Full app description
• App dependencies
• Screenshots
• Links to external resources (for example, a help center article, release notes, or installation instructions)

The content that appears in the app listing and app details page is determined by the following elements in your main app definition:

title

The title of the app to display in the app directory. This should be the name of your product or service.

• The maximum length is 40 characters, including spaces.
• If you offer separate apps for the same product or service that integrate with Kustomer, you may use descriptors like "for Voice" or "for Chat" and so on in the name.
• Do not include "for Kustomer" or “app” in the name of the app.
• Omit any descriptors or SEO terms apart from the name of your product

Example: "title": "Magento"

description

A description for your app.

• Start with a concise, one-sentence summary of your app. (The first 110 characters will appear as your short description in the app directory.). Add a new line after the concise summary.
• Follow up the concise summary with a longer description for your app. In the longer description, include the following:
  • Information about your company
  • What your app does
  • Links to company site and relevant resources
  • Links to an externally-hosted support article or help center for further instructions for app installation or integration
• Use Markdown for formatting. Use \n to create a new line.
• The maximum length is 1,000 characters, including spaces.

Example: "description": "See Magento orders, sync customers, and view shopping carts in Kustomer.\n Learn more at [our website](https://magento.com/)."

iconURL

A URL pointing to the logo for the app. Appears in the app directory.

See App logo requirements for additional information.

• Must be externally hosted and cannot be stored on Kustomer
• Logos should be in PNG format, with a minimum size of 1200 x 1200 px

Example: "iconUrl": "https://standardecomm.com/kustomer/app-logo.png"

releaseNotesUrl

You can include a URL to external release notes for major version releases for the app.

Example: "releaseNotesUrl": View release notes [here](https://help.standardecomm.com/kustomer/release-notes)"

screenshots

Provide an array of screenshots or GIFs to appear in the app directory. Choose images that display clearly what the app does and how the app appears in the Kustomer platform.

Example: "screenshots": ["https://standardecomm.com/kustomer/screenshot1.png", "https://standardecomm.com/kustomer/screenshot2.png"]

App settings page

After app installation, the user can access the app settings page to modify the available preferences if a settings page has been defined.

The app settings page contains the following:

• App settings page title
• Settings page description
• Paired display name and description for each app setting

The content that appears in the app settings page is determined by the Internationalization strings and app settings keys defined along with any App Settings and Custom Settings Pages:

{
  ...
  "i18n": {
      "en_us": {
        "standardecomm.settings.page.title": "Standard E-comm",
        "standardecomm.settings.page.description": "Configure settings for your standard e-commerce app",
        "standardecomm.settings.path.default.authToken.displayName": "Auth Token",
        "standardecomm.settings.path.default.authToken.description": "An auth token for accessing the Standard E-comm service",
        "standardecomm.settings.path.default.subdomain.displayName": "Subdomain",
        "standardecomm.settings.path.default.subdomain.description": "The subdomain of of your store on the Standard E-comm site"
      }
  },
  ...
}

Settings page title

<app>.settings.page.title

Displays as the app title on the individual app settings page and the Settings pane in Kustomer.

• Use the same name as the app title.
• Use Title Case.

Example: "magento.settings.page.title": "Magento"

Settings page description

<app>.settings.page.description

Description for the app. Displays below the app title in the individual app settings page. Can include links to an external site for users to learn more.

• Use the short description, or the first sentence of the description, from the app directory
• Always include and end the description with a linked call to action (for example, "Learn more.") that directs the user to the company website, help center page, or relevant support article.
• Use Markdown formatting. Use \n to create a new line.
• Max character length 140

Example: "magento.settings.page.description": "The Magento app integration allows you to easily populate your Magento e-commerce platform data in your Kustomer organization in real-time. [Learn more](https://help.kustomer.com/magento-integration-BkI1rT5qz)."

Setting display name and description

A paired display name and description for each app setting. Appears on the app settings page.

<app>.settings.path.<categoryName>.<fieldName>.displayName

<app>.settings.path.<categoryName>.<fieldName>.description

• Provide a concise, clear display name and description for each settings field.
• The description should explain the field and the effect of any options.
• Use Markdown formatting. Use \n to create a new line. If needed, link to any relevant support articles or resources relevant for the field.

Examples:

"Status" setting with description "Activate your Magento settings."

"magento.settings.path.default.status.displayName": "Status", "magento.settings.path.default.status.description": "Activate your Magento settings."

"Domain" setting with description "The fully-qualified domain name of your Magento store."

"magento.settings.path.default.domain.displayName": "Domain", "magento.settings.path.default.domain.description": "The fully-qualified domain name of your Magento store."