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's 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 you declare the schema of your app’s configuration.

Below is an example of the Google Tag Manager app interface and its corresponding settingsSchema configuration:

Interface

settingsSchema

manifest.json _22 "settingsSchema": { _22 "title": "Google Tag Manager", _22 "type": "object", _22 "bindingBounded": true, _22 "properties": { _22 "gtmId": { _22 "title": "Google Tag Manager", _22 "description": "Enter the ID (GTM-XXXX) from your Google Tag Manager", _22 "type": "string" _22 }, _22 "allowCustomHtmlTags": { _22 "title": "Allow Custom HTML tags", _22 "description": "Beware that using Custom HTML tags can drastically impact the store's performance", _22 "type": "boolean" _22 }, _22 "sendGA4Events": { _22 "title": "Send Google Analytics 4 Events", _22 "description": "When this setting is active, also send the GA4 version of the events", _22 "type": "boolean" _22 } _22 } _22 },

After building your app's settings interface, 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 are the instructions for creating an interface for your app and retrieving the data to use within the app.

To create the app settings interface, define the settingsSchema object in its manifest.json file.

This object declares a JSON Schema with the fields that meet your business needs. See the JSON Schema documentation to correctly build the settingsSchema field.

The JSON Schema offers a predefined model that outlines how the settings should be formatted in your app. Note that, depending on the JSON Schema specification, the types accepted within a property include: string, number, integer, boolean, object, array, or null. You can also use arrays of types (for example, [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 displayed in the app settings interface. We recommend using 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 displayed as a checkbox.
• sendGA4Events: Boolean-type property that indicates whether to send Google Analytics 4 events. In the settings UI, this property is displayed as a checkbox.

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

• Frontend apps: Use a GraphQL query to fetch app settings.
• Backend apps: Use the getAppSettings method from the ctx.clients.apps client.

Below is an example of each case.

Make sure your app has the required permissions to communicate with the frontend or backend app. Without proper permissions, your store won’t be able to share data with the solution. Learn more in Policies.

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 (for example, 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. In the case of the Google Tag Manager app, the app value is vtex.google-tag-manager, and the version value is 1.x.

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. The message may vary depending on the app's settingsSchema.

This query will return an object like the one below:

4. Open the tsx file of the React component that will consume this information and import the GraphQL query:

5. Parse and use the defined query value (for example, AppSettings) based on your needs. See 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. When the data is retrieved, a useEffect hook parses the settings, extracts the gtmId, and dynamically initializes GTM by injecting its script into the document if the gtmId is available.

Backend apps

1. Open your node app in any code editor of your choice.
2. Declare a new function (for example, getConfig) and use the getAppSettings method from the apps client to retrieve and return the app settings data. See 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.

3. Import the defined function and consume it based on your needs. For example, you can use it in a resolver, middleware, or any other part of your backend app.