Creating an integration app from a Template

The integration Template App is a pre-built app developed by VTEX for our partners to reduce development and implementation time when integrating with external marketplaces. By using the template to build your integration app, connectors will also have the app displayed in the VTEX App Store.

What the App Template includes for the VTEX Admin

An integration app created from our App Template already includes:

  • Standard set up page containing:
    • Activate/deactivate the integration button
    • Field identifying the affiliate
    • Field with sales channel values and the country it is applied
    • Callback URL used by the VTEX notification system
    • Save Settings button
  • Complete search endpoint to retrieve seller configurations using AppKey and AppToken generated in the seller’s account, defined by the appVendor.
  • Feed creation mechanism in Sent Offers, that allows the connector to interact with Sent Offers for generating logs.
  • Link to VTEX Mapper Registration, allowing sellers to map their catalog according to the marketplace’s definitions

Before you start

The Template App runs in VTEX IO. Before you begin creating your app from our template, make sure to:

📘

VTEX Partner

If you do not have access to a VTEX Account, join our Partner Program, to become a certified partner.


Step 1 - Creating your repository from the template

  1. Access the Template App’s repository.
  2. Don't forget to request the use of the builders necessary for the development of the app. Read the article Filling the Application form for development and request the builders: admin, docs, graphql, messages, node and react.
  3. Click on Use this template.
  4. Add a name to your repository.
  5. Select the Private option.
  6. Do not check the Include all branches option.
  7. Click on Create repository from template.

Step 2 - App configurations

Once your repository is created from the template, you must configure your app by substituting placeholders and setting up the necessary Template App Configurations.

Substituting placeholders

Follow the list below to substitute placeholders properly. Once placeholders are replaced, the App’s foundation will include the fields needed to set up the seller and the integration on VTEX's side.

📘

Manifest file

Placeholders within the manifest.json file must follow the rules described in Manifest Fields Summary.

Placeholder Description Files where it can be found
appName Name of the app. This value must follow the kebab case (only minor case letters and the `-` character).
  1. manifest.json
  2. navigation.json
  3. routes.json
  4. node/service.json
  5. node/constants/variables.ts
  6. react/package.json
appVendor Name of the app’s owner, responsible for its distribution and maintenance. It must be the Partner’s VTEX `accountName`.
  1. manifest.json
  2. navigation.json
  3. node/routes.json
  4. node/service.json
  5. node/constants/variables.json
appTitle Title of the app that will appear in the VTEX Admin’s screen and left navigation, once the seller accesses it.
  1. messages/context.json
  2. messages/en.json
  3. messages/pt.json
  4. messages/es.json
  5. node/constants/variables.ts
connectorEndpoint Base URL of the backend connector to which notifications coming from VTEX will be sent. Examples: https://externalconnector.com or relative URL https://externalconnector.com/api/vtex.
  1. node/constants/variables.ts
  2. react/areas/ConfigArea/DefaultConfigs/endpoint.tsx
connectorEndpointHost Endpoint host informed in the connectorEndpoint placeholder. Example: externalconnector.com.
  1. manifest.json
affiliateId Affiliate identifier code, which consists of three consonants, whether they are repeated or not.
  1. react/areas/ConfigArea/index.tsx
manifestTitle App’s title in the VTEX App Store.
  1. manifest.json
manifestDescription App’s description in the VTEX App Store.
  1. manifest.json
mapperId Connector’s ID in VTEX Mapper.
  1. admin/navigation.json
feedId Connector’s ID in Sent Offers.
  1. node/constants/variables.ts

The fields listed above come with the App Template as default. However, it is possible to remove fields that represent features not used by your integration, like the VTEX Mapper and Sent Offers. They are listed ahead in the section CustomConfigs.

Receiving notifications

To receive notifications from VTEX, the seller needs to implement specific API routes in the endpoint informed in connectorEndpoint. These endpoints are described in the following sections:

Catalog notification

To receive product update notifications and product variations (including stock, price and trade policy), you must implement the POST {{connectorEndpoint}}/catalog/notification route.

This notification follows the format of our VTEX Broadcaster Adapter.

Store configuration notification

To receive notifications of updates to store or seller settings, you must implement the POST {{connectorEndpoint}}/store-config/notification route.

The store configuration notification format will vary according to the configuration you implement in your app. The default fields are:

Field nameDescriptionType
accountNameName of the seller’s account in VTEX.string
activeFlag that indicates if the seller wants to be active in the marketplace. If false, the connector should deactivate the seller’s products on the marketplace.boolean
affiliateIdUnique affiliate ID configured in the seller that identifies its connection with the marketplace.string
salesChannelSales channel/trade policy ID configured in the seller and being used for this marketplace.string
emailEmail that’ll be notified about changes related to the affiliate.string
cookieApp’s auth cookie. This token can be used when making requests to VTEX APIs with the seller’s account.string
allowFranchiseAccountsFlag indicates if the seller also wants to synchronize their franchise accounts catalog/orders with the marketplace, through the Multilevel Omnichannel Inventory feature.boolean

Template App Configurations

The Template App is divided into two areas:

  • TitleArea: where the app's title goes, defined by the {{appTitle}} field.
  • ConfigArea: where the app's set up fields go. The ConfigArea has two types of configurations: Default Configurations and Custom Configurations.

DefaultConfigs

DefaultConfigs is where the mandatory fields for all apps are included. This section does not need to be changed, regardless of the marketplace's needs, since they are internal configurations used by VTEX. This section already includes:

  • Toggle indicating if the integration is activated or inactivated.
  • Input field showing the marketplace's affiliateId.
  • Input field showing the connector's endpoint, for notifying product and order updates occurred in VTEX.
  • Button leading to the account's Affiliate page.
  • Selection box showing sales channels that the seller has set up in their account, and the country they are applied to.
  • Input field for the seller to fill in the email registered with the Affiliate.

CustomConfigs

The CustomConfigs section is where you find configurations that come as default but are optional, like VTEX Mapper, Sent Offers and AllowFranchiseAccounts.

Removing VTEX Mapper

You can remove VTEX Mapper Registration from the app, if the integration does not require mapping categories, or the partner already has a solution for mapping catalog architecture. To remove VTEX Mapper, on the admin/navigation.json, remove file the object that defines the Mapper endpoint in the Admin:

{
“labelId”: “admin/app.mapper.tile”,
“path”: “/admin/mkp-category-mapper/{{mapperId}}
}
Removing Sent Offers

You can remove Sent Offers from the app, If your integration already includes a solution to generate logs for offers. To remove Sent Offers, on the node/resolvers/saveConfig.ts file (line 15), remove the feed’s creation in Sent Offers:

await ctx.clients.sentOffers.createFeed({affiliateId, salesChannel, id: FEED_ID)}.then( async () => {
Removing AllowFranchiseAccounts

When the configuration AllowFranchiseAccounts is configured, the component becomes a toggle indicating whether franchise accounts are permitted.

You can remove the configuration by performing the following actions:

Instruction

Files where it can be found

Remove component AllowFranchiseAccounts

react/areas/ConfigArea/CustomConfigs/index.tsx

Remove field allowFranchiseAccounts

react/graphql/getConfig.gql
graphql/schema.graphql
graphql/types.graphql
node/typings/configuration.d.ts
react/typings/config.d.ts

Set the atribution allowFranchiseAccounts as false

react/areas/ConfigArea/index.tsx:

Adding your own CustomConfigs

CustomConfigs is also where connectors can add their custom fields and most of the app’s development will be made, in case it is necessary to add extra fields like input field for the marketplace’s token, or a button to activate a connector’s new feature, for example. To add custom fields in the App:

  1. In the folder react/areas/configArea/customConfigs, create a file with the field’s name and .tsx extension.
    Ex. email.tsx, token.tsx.

  2. In the file, add the following code, replacing the ExampleComponent field with the name you wish to give it.

import React from "react"
import { DefaultProps } from '../../../typings/props'

const ExampleComponent: React.FC<DefaultProps> = ({ intl, config }) => {
    return (
    )
}

export default ExampleComponent
Field Description Files where it can be found
DefaultProps Defines attributes used by all components present in the integration. The attributes include `intl` (used for field internationalization) and `config` (represents the seller’s current configuration). react/typings/props.tsx
  1. To add more properties to the DefaultProps for a specific field, extend the DefaultProps interface, adding the extra properties. This step is optional.
import React from "react"

export interface CustomProps extends DefaultProps {
    newProp: string
}

const FieldName: React.FC<CustomProps > = ({ intl, config, newProp}) => {
    return (
    )
}

export default FieldName

In the example above, a new interface called CustomProps was created, that can extend the DefaultProps, by adding a newProp string property. Thus, it is possible to use CustomProps in place of DefaultProps, and the component can now accept the extra newProp property.

  1. To use other properties that are not listed in DefaultProps, define a new interface with the needed properties.

In the example below, a new interface called CustomProps is created, with only two properties: prop1 (string) and prop2 (number).

import React from "react"

export interface CustomProps {
    prop1: string.
    prop2: number
}

const FieldName: React.FC<CustomProps > = ({ prop1, prop2 }) => {
    return (
    )
}

export default FieldName
  1. Add components developed to the app’s template.

Here’s an example code for adding an input field:

import React from "react"
import InputComponent from "../../../components/InputComponent"
import { DefaultProps } from "../../../typings/props"

export interface ExampleProps extends DefaultProps {
  setConfig: React.Dispatch<React.SetStateAction<Configuration>>
}

const ExampleComponent: React.FC<ExemploProps> = ({ intl, config, setConfig }) => {
    return (
            <InputComponent
          id={example}
          label={example}
          canEdit={true}
          initValue={config.email}
          type={'text'}
          required={false}
          tooltip={intl.formatMessage({ id: "admin/app.example" })}
          onChange={value => {
              if(value !== undefined){
                setConfig(oldConfig => ({ ...oldConfig, email: value }))
              }
            }
          }
        />
    )
}

export default ExampleComponent

The example above creates an input field called ExampleComponent. It uses an extra property, or the setConfig, used in this case within the onChange property of the Input component. This updates the email field in the config, whenever the seller types something within the field. This is how it is rendered in the UI:

  1. To finalize the new field’s inclusion, add the new field within the CustomConfigsArea. To do that:
  • In the react/areas/configArea/customConfigs/index.tsx field, add an import to the new component developed.
    Following the example above: import ExampleComponent from './example'
  • Add the component within the
    of CustomConfigArea.
const CustomConfigsArea: React.FC<CustomConfigsProps> = ({ intl, config, setConfig }) => {
  return (
    <div>      
      <ExemploComponent
        config={config}
        intl={intl}
        setConfig={setConfig}
      />
    </div>
  )
}

Note that the CustomConfigArea in the template does not include intl, config and setConfig. They must be added, like in the example above, depending on which properties are needed. To add more properties, repeat step 3.

  1. If other components are necessary, add them in the return object.

The order of components within the return affects the order in which components are rendered in the app.


Step 3 - Translating a component

The app’s internationalization is made using the intl library in the messages builder, declared in the manifest.json. This builder’s addition comes in the Template App as default and does not need to be altered. It is only necessary to add translations for new inserted fields. Check out Translating the component to know more.

The intl library gets what locale is being used in the VTEX Admin’s context and searches in the messages file the corresponding translated text in the {messageId}. In case the VTEX Admin is using a language that is not translated in the app, the library will search the id of a language mapped in the app, and automatically translate it to the Admin’s locale.

To add translations to the app:

  1. Add the translations in the messages folder. The Template app already includes the files:
  • en.json: english
  • es.json: spanish
  • pt.json: portuguese

The following languages are also available in the VTEX Admin: italian (it), japanese (ja), korean (ko), dutch (nl) and romanian (ro).

  1. Add the translations in the {messageId} to the corresponding locale’s file in the format "admin/{messageId}": "translation".
  2. In the selected property that needs translation, substitute the text for the code intl.formatMessage({ id: 'admin/{messageId}' }).
  • admin/: used to identify a translation of a component installed in the VTEX Admin. It must be every Id’s prefix.
  • messageId: can be substituted for any text. It only accepts letters and - to define the text.

To illustrate with an example, let’s suppose we have the following component:

import React from "react"
import InputComponent from "../../../components/InputComponent"
import { DefaultProps } from '../../../typings/props'

const ExemploComponent: React.FC<DefaultProps> = ({ intl }) => {
    return (
      <InputComponent 
        canEdit={true}
        id={'test'}
        initValue={""}
        label={intl.formatMessage({ id: 'admin/app.test.title' })}
        type={'text'}
      />
    )
}

export default ExemploComponent

In this case, we have an Input component, type “text”, and its label will be translated according to the VTEX Admin’s locale. If we do not add the id "admin/app.test.title" in the messages folder, this is what is rendered in the UI:

Since the id does not exist in any messages file, it renders the id itself as a response.

To add the id to the file, we add the code: “admin/app.test.title”: “Teste no en.json”. Once the id is rendered in all files, the component will then render:


Step 4 - Testing the app locally

  1. With the app already configured, open a CLI in the project’s root.
  2. Login into a test account using the command: vtex login {{account}}. Substitute {{account}} by the test account’s accountName.
  3. Once logged into the account, use the command vtex use {{workspace}} to access a development workspace to link the app. Substitute {{workspace}} by any name you choose.
  4. Use the command vtex setup to adjust IO types and variables based on the values set in the app’s configuration.
  5. Use the command vtex link to link the app so it operates on VTEX IO’s infrastructure.
  6. Access the following address:
    https://{{workspace}}--{{account}}.myvtex.com/admin/{{appVendor}}/{{appName}} substituting the placeholders for the chosen values in the previous steps.

Collecting the app’s configurations

Once the app is configured, it is possible to recover the seller’s configuration through the app. To search a seller’s configuration:

  1. Call the following API:
    https://{{workspace}}--{(account}}.myvtex.com/_v/{{appVendor}}/{{appName}}/config
Field Description
workspace Environment where the app was linked. In production, the workspace is not included in the call, so the endpoint is as follows: `https://{(account}}.myvtex.com/_v/{{appVendor}}/{{appName}}/config`
account Seller’s VTEX account you wish to recover configuration information from.
appVendor Name of the app’s owner, responsible for its distribution and maintenance. It must be the Partner’s VTEX `accountName`.
appName Name of the app. This value must follow the kebab case (only minor case letters and the `-` character).
  1. Generate the account’s AppKey and AppToken to authenticate it.

Request’s curl in a workspace:

curl --location -g --request GET 'https://{{workspace}}--{{account}}.myvtex.com/_v/{{appVendor}}/{{appName}}/config' \ --header 'appkey: {{appkey}}' \ --header 'apptoken: {{apptoken}}'

Request’s curl in production:

curl --location -g --request GET 'https://{{account}}.myvtex.com/_v/{{appVendor}}/{{appName}}/config' \ --header 'appkey: {{appkey}}' \ --header 'apptoken: {{apptoken}}'

Step 5 - Publishing the app in the VTEX App Store

Once all steps are completed, you must publish the app in VTEX’s App Store, so it is available for clients to install it in their accounts. Follow the instructions on Submitting your app in the VTEX App Store for this step.


Did this page help you?