User experience is key in the success of modern products. Ease of use means avoiding context switching and manual insertions to optimize user experience. For example when designing a flow, make sure users don’t have to:

...copy an API key
...multi-task with two separate browser tabs
...locate a <head> tag in a template
...paste a <script> tag

Examples

Guidelines

Use the Live Preview

Live Preview allows customers to see how an app looks and feels on their site. Apps with visual components should always include real preview, or a simulated facsimile.

Always allow customers to try an app without an account. Many apps include a preview account to make this possible.

Including a preview account

var options = INSTALL_OPTIONS
var isPreview = INSTALL_ID === 'preview'
var accountID = isPreview && !options.accountID ? 'abc123' : options.accountID

Previewing “platform” apps

Apps that act as sign-up flows for other app platforms are generally not approved. If possible, we recommend splitting platform features into specific apps that can be previewed individually. Additionally, visual apps should be completely configurable within the Live Preview, rather than an external editor.

Use enums, not pixel or numeric values

Many libraries and tools accept arbitrary numeric values for parameters like size and delay. Rather than requesting those values as a number, consider choosing a few reasonable options and presenting them as an enumeration.

INSTALL_OPTIONS = {{options.enumVsNumeric | json}}

{
  "title": "Delay",
  "description": "How quickly should the tooltip hide after moving the cursor away?",
  "type": "string",
  "format": "radios",
  "default": "1000",
  "enum": ["500", "1000", "2000", "5000"],
  "enumNames": {
    "500": "Very Fast",
    "1000": "Fast",
    "2000": "Slow",
    "5000": "Very Slow"
  }
}

Alternatively, use a slider option.

Note that as only string values are allowed to have enumerated options, it will be necessary to define your option as a string, and then cast its value to a number before using it.

var delay = parseInt(INSTALL_OPTIONS.delay, 10)

Specify titles and descriptions for your fields

All Cloudflare form types allow you to specify a title and a description as a part of the definition. The description is a valuable place to provide extra context or help information.

When finalizing your app, always ask yourself if a non-technical person could understand what your app, and what each of its options, does. If not, reword what you have or add more help information.

Provide default option values

Providing a default value for your app’s options allows the app previewer to render initially with content, making it clear how your options relate to the values displayed. In general, you should use default for any value which is being shown in the app, and only use placeholder for example values which are not rendered.

Don’t include every option

Often libraries and tools will include numerous technical options which are only relevant to a tiny fraction of users. If you can’t think of the situation where an option is valuable, or can’t come up with an easily understood description for an option, consider simply setting it to something reasonable rather than making it configurable.

Hide advanced options

In general we recommend not including options which aren’t applicable to the average user. Occasionally however, it is necessary to include a special option for a subset of customers. To do this, include the option behind an “Advanced options” toggle:

INSTALL_OPTIONS = {{options.showAdvanced | json}}

{
  "showAdvanced": {
    "order": 1,
    "type": "boolean",
    "title": "Show advanced options",
    "default": false
  },
  "advanced": {
    "showIf": {
      "showAdvanced": true
    },
    "order": 2,
    "type": "object",
    "title": "Advanced options",
    "properties": {
      "urlType": {
        "order": 1,
        "type": "string",
        "title": "URL to Like",
        "format": "radios",
        "enum": [
          "automatic",
          "provided"
        ],
        "enumNames": {
          "automatic": "Automatically use the URL of the page displaying the button",
          "provided": "Specify a particular URL"
        }
      }
    }
  }
}

Allow your customers to localize

In an ideal world you would provide translations for the text in your app into all the languages of the world. More realistically however, it’s often easier to simply let your users customize the text of your app. By exposing your text as options, optionally behind a “Customize Labels” advanced option, you are giving them the ability to use your app on their foreign language site. Customized labels also give customers a chance to align your app with the tone of their site and how they prefer to address their visitors.

For example, the Cover Message app allows customers to specify their own text. (source).

What does “ease of use” mean?