When developing a VTEX IO app, you can create an interface for accepting custom user settings. The app settings interface allows you to retrieve data provided by the user and enable or modify an app behavior based on it. The configuration possibilities depend on the type of data collected by the interface and the intended use.

This guide outlines the process of creating such an interface and using the data input by users within your app.

The app settings interface displays configuration forms for installed apps in the App Store. This interface is defined via the settingsSchema field on manifest.json, where an app may declare the schema of its configuration.

See the Google Tag Manager app interface in the example below, with the appropriate configuration of the settingsSchema field in the manifest.json file.

After building the settings interface for your app, you need to consume the data provided by the app’s user. Consider the Google Tag Manager example above retrieving the GTM ID.

Based on the given example, below is a step-by-step guide for creating an interface for your app and retrieving the data to use within the app.

Open your app project in any code editor of your choice and open the manifest.json file.

Define the settingsSchema object, declaring a JSON Schema containing the fields that meet your business needs. See the JSON Schema documentation to build the settingsSchema field correctly.

The JSON Schema offers a predefined model that outlines how the settings should be formatted in your app. Note that, according to the JSON Schema specification, the types accepted within a property include: string, number, integer, boolean, object, array, or null. It is also possible to use arrays of types (e.g., [string, number]) to indicate that the property accepts multiple types.

Considering the example of the Google Tag Manager interface previously presented, the settingsSchema object was configured as follows:

This code defines a schema for the settings UI that interacts with the Google Tag Manager app. The configured fields are described below:

• title: App name shown in the app settings interface. It is recommended to use the same app name configured in the title field of the manifest.json file.
• type: JSON Schema type (this must always be set as object).
• description (optional): Description of the settingsSchema field.
• properties: Key-value pairs that define the fields that will be displayed to the app users, with their own definition within this object. Each defined key accepts the following properties: title, description, and type.
• gtmId: String-type property that represents the Google Tag Manager ID. In the settings UI, this property is shown as a text box.
• allowCustomHtmlTags: Boolean-type property that determines whether custom HTML tags are allowed. In the settings UI, this property is shown as a checkbox.
• sendGA4Events: Boolean-type property that indicates whether to send Google Analytics 4 events. In the settings UI, this property is shown as a checkbox.

On your app’s code, you can retrieve the app settings in two ways:

• Frontend apps: Fetch the data using a GraphQL query.
• Backend apps: Use the getAppSettings method from the ctx.clients.apps client.

Below is an example of each case.

Frontend apps

1. In the manifest.json file, add the vtex.apps-graphql 3.x within the dependencies field.
2. In the react directory, create a new folder named queries.
3. Create a new graphql file (e.g., AppSettings.graphql) and query the settings options as in the following example.

Replace vendor, app.name, and 0.x with values based on your scenario.

The example above is a GraphQL query that fetches the data of a specific app declared in the arguments of publicSettingsForApp field: the app and its version. The configured fields are described below:

• @context(provider: “vtex.apps-graphql”): The context for the query. In this case, it must be configured as “vtex.apps-graphql”.
• message: The message field to be included in the query result, which is a field within the publicSettingsForApp object. Note that the message may vary depending on the app's settingsSchema.

This query will return an object like the one below:

Please be aware that only settings labeled with public access in the settingsSchema will be returned.

4. Open the tsx file of the React component that will consume this information (e.g., ProductComparisonContext.tsx) and import the GraphQL query:

5. Parse and use the defined query (e.g., AppSettings) value based on your needs. Check the example below:

The code above interacts with an API through a GraphQL query, which is managed by the useQuery hook, to fetch the app settings. It then parses and updates the app’s state with these settings using a useEffect hook whenever the settings data changes.

Backend apps

1. Open your node app in any code editor of your choice.
2. Declare a new function (e.g., getConfig) and use the getAppSettings method to retrieve and return the app settings data. Consider the example below:

The getConfig function returns a promise as it fetches the app settings and handles errors. It retrieves an app ID from environment variables, uses it to request settings, and logs any errors that occur.

3. Import the defined function and consume it based on your needs.