Learn how to create a user interface for your app and fetch data from it.
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.
Usage example
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 |
---|---|
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.
Instructions
Step 1 - Creating the settings interface
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
, ornull
. 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:
_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 },
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 thetitle
field of the manifest.json file.type
: JSON Schema type (this must always be set asobject
).description
(optional): Description of thesettingsSchema
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 followingproperties
:title
,description
, andtype
.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.
Step 2 - Retrieving and consuming the app settings data
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 thectx.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
- In the
manifest.json
file, add thevtex.apps-graphql@3.x
within thedependencies
field. - In the
react
directory, create a new folder namedqueries
. - Create a new
graphql
file (for example,AppSettings.graphql
) and query the settings options as in the following example.
_10query getSettings {_10 publicSettingsForApp(app: "{vendor}.{app.name}", version: "0.x")_10 @context(provider: "vtex.apps-graphql") {_10 message_10 }_10}
Replace
vendor
,app.name
, and0.x
with values based on your scenario. In the case of the Google Tag Manager app, theapp
value isvtex.google-tag-manager
, and theversion
value is1.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 thepublicSettingsForApp
object. The message may vary depending on the app's settingsSchema.
This query will return an object like the one below:
_10{_10 "data": {_10 "publicSettingsForApp": {_10 "message": "{\"gtmId\": \"GTM-1234\"}"_10 }_10 }_10}
- Open the
tsx
file of the React component that will consume this information and import the GraphQL query:
_10import AppSettings from './queries/AppSettings.graphql'
- Parse and use the defined query value (for example,
AppSettings
) based on your needs. See the example below:
_17 const { data: appSettingsData } = useQuery(AppSettings, {_17 variables: { version: process.env.VTEX_APP_VERSION },_17 ssr: false,_17 });_17_17 useEffect(() => {_17 if (appSettingsData) {_17 const { gtmId } = JSON.parse(appSettingsData.publicSettingsForApp?.message || '{}');_17 if (gtmId) {_17 window.dataLayer = window.dataLayer || [];_17 window.dataLayer.push({ 'gtm.start': new Date().getTime(), event: 'gtm.js' });_17 const script = document.createElement('script');_17 script.src = `https://www.googletagmanager.com/gtm.js?id=$\{gtmId\}`;_17 document.head.appendChild(script);_17 }_17 }_17 }, [appSettingsData]);
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
- Open your
node
app in any code editor of your choice. - Declare a new function (for example,
getConfig
) and use thegetAppSettings
method from theapps
client to retrieve and return the app settings data. See the example below:
_18export const getConfig = async (_: any, __: any, ctx: Context) => {_18 const {_18 clients: { apps },_18 vtex: { logger },_18 } = ctx;_18_18 const appId = process.env.VTEX_APP_ID;_18_18 try {_18 const settings = await apps.getAppSettings(appId);_18 return settings;_18 } catch (error) {_18 logger.error({_18 message: 'getConfig-getAppSettings-error',_18 error,_18 });_18 }_18};
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.
- 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.