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 ID
    • Field to inform the email that will receive notifications about changes in the affiliate
    • Callback URL used by the VTEX notification system
    • Field for the sales channel ID
    • Fields included in the sales channel form
    • Save Settings button
  • Custom settings page containing:
  • 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 Offer Management, that allows the connector to interact with Offer Management 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 Offer Management.
  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 Offer Management. 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.
  • Input field for sellers to fill in the email registered as the affiliate.
  • Button leading to the account's Affiliate page.
  • Selection box showing a list of countries, currencies, time zones and other information registered in the sales channels that the seller has set up in their account. This way, sellers can create or edit their sales channel information directly through the Default Configs page.
  • Field showing the sales channel's name used for the marketplace, with a button leading to the VTEX account's Sales channels page. This becomes available after the initial set up of the fields listed above.

CustomConfigs

The CustomConfigs section is where you find configurations that come as default but are optional, like VTEX Mapper, Offer Management 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 Offer Management

You can remove Offer Management from the app, If your integration already includes a solution to generate logs for offers. To remove Offer Management, 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.

291291

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:

12831283
  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:

935935

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:

17641764

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?