Integrating VTEX IO with Synerise

You can use the Synerise plugin in your eshop built on VTEX IO ecommerce platform to transmit the data from your website to Synerise, so you can utilize it for analyses and your business campaigns.

This instruction contains steps which require contact with the Synerise Support.

Plugin scope

• Tracking transaction, cart, and customer activity events
• Tracking the checkout page
• Identifying customers after they filled out the form
• Synchronizing data between Synerise and VTEX through webhooks (creating, updating, and removing accounts)
• Implementing a service worker for displaying web push notifications
• Exporting historical data about customers and orders from VTEX to Synerise.

Prerequisites

1. You must be granted user permissions to access API key section and add the key in Synerise.
2. In VTEX, create an account and a workspace.
3. In VTEX, in Catalog > All Products, add the items you want to display in your eshop.

Configuration in Synerise

Create an API key

1. In Synerise, go to Settings > API Keys > Add API key.

2. On the pop-up:

   1. Enter the name of the API key (it will be visible on the list of API keys).
   2. Select Workspace.
   3. Optionally, enter the description of the key (it will be visible on the list of API keys).

   

3. Confirm by clicking Save.

4. Find the key on the top of API key list and click Permissions.

5. On the pop-up, select the following permissions:

   • CATALOG:
     • CATALOGS_CATALOG_CREATE
     • CATALOGS_CATALOG_READ
     • CATALOGS_ITEM_BATCH_CATALOG_CREATE
   • CLIENT:
     • API_BATCH_CLIENT_CREATE
     • API_CLIENT_CREATE
   • EVENTS:
     • API_ADDED_TO_CART_EVENTS_CREATE
     • API_ADDED_TO_FAVORITES_EVENTS_CREATE
     • API_CUSTOM_EVENTS_CREATE
     • API_LOGGED_IN_EVENTS_CREATE
     • API_LOGGED_OUT_EVENTS_CREATE
     • API_REGISTERED_EVENTS_CREATE
     • API_REMOVED_FROM_CART_EVENTS_CREATE
   • TRACKER
     • TRACKER_CREATE
   • TRANSACTION
     • API_BATCH_TRANSACTION_CREATE
     • API_TRANSACTION_CREATE
   • VTEX
     • IMPORT_FEEDER_INTEGRATION_VTEX_CREATE
     • IMPORT_FEEDER_INTEGRATION_VTEX_READ
     • IMPORT_FEEDER_SYNCHRONIZATIONS_VTEX_READ
     • IMPORT_FEEDER_SYNCHRONIZATION_VTEX_CREATE
     • IMPORT_FEEDER_SYNCHRONIZATION_VTEX_DELETE

6. Confirm by clicking Apply settings.

7. On the list of API keys, double-click the key you created.

8. On the General section, click Show.

9. Copy the API key and paste to the notepad.

   

Add the tracking code

1. In Synerise, go to Settings > Tracking codes and add a tracking code. Full instruction on adding tracking codes is available here.
   Note: You can select any feature configuration for the tracking code.
   Result: Synerise generates 2 tracking codes.
2. Copy the generated tracking codes and save them in the notepad.

Enable updating profile information with specific events

To prevent duplicating customers’ accounts when they become identified, make it possible for specific events to update profile information without JWT authorization.

1. Go to Data Management > Events.
2. Select the JS SDK event settings tab.
3. In the Events without JWT allowed for updating profiles’ information section, click Define.
4. From the Select events dropdown list, select form.submit
5. Confirm by clicking Add.

   

6. Confirm the settings by clicking Apply.

Prepare tracking events on the checkout page

In this part of the process, you will use a ready-to-use dynamic content template available in the Synerise platform. This template includes JavaScript that’s inserted into the checkout page to identify customers when they fill out a form and to track events on the checkout page. By default, the dynamic content from this template doesn’t include any elements visible on the site.

1. Go to Communication > Dynamic Content > Create new.
2. Enter the name of the dynamic content.
3. As the dynamic content type, select Insert object.
4. In the Audience section, select the Everyone tab.
5. In the Content section, click Simple message.
6. In CSS Selector:
   1. Select After.
   2. In the text field, enter.snrs-modal-wrapper
      This sets the dynamic content to be injected after one of the elements created when Synerise JS SDK is initialized. If you need to, you can set a different selector.
7. Click Create message.
8. Select Script templates.
9. From the Script templates library, select VTEX - tracking events on checkout page.
   The template is ready to be used, it contains all necessary scripts that track events and identify customers when they fill out the form.
10. If needed, you can make changes to the templates.
    
    Note: You can learn more how to edit a template in a dynamic content template builder here.
11. In the upper right corner, click Next.
12. Confirm the settings in the Content section by clicking Apply.
13. In the Schedule section, select Display immediately and click Apply. If needed, you can declare the date when the dynamic content will start and end being active
14. In the Display settings section:
    1. Open Advanced options.
    2. In Page targeting, click Others.
    3. In Display on pages, click Add rule.
    4. Select Page with URL and enter the URL of your checkout page.
15. Optionally, in the UTM & URL parameters section, define these parameters.
16. In the upper right corner, click Activate.

Configure web push notifications

If you want to enable web push notifications:

1. Configure web push notifications. In the Path to the service worker field, enter /synerise/snr-sw.js
2. Configure two-step agreement form.

Configuration in VTEX

Install the Synerise plugin

There are two ways of installing the Synerise plugin.

Connecting the item feed with Synerise

In this part of the integration, you will enable sending items from your VTEX item feed to an item feed catalog in Synerise.

This part includes the following sub-procedures:

1. In your VTEX workspace, go to Stores > (Synerise) Feed.
2. Add item data and configure additional settings.
3. Add the feed in Synerise.

Item data

The center of the view shows fields that are sent to Synerise and saved in the Synerise catalog that is your item feed.
By default, all the required parameter mappings are already added.

For each mapping:

• Field name is the name under which the value will be saved in Synerise.
• Field value is the value. You can use inserts to pull data from the VTEX database (see examples in fields added by default).

The field names and values that you send to Synerise must meet the requirements of the Google Merchant XML feed.

1. In all fields that indicate prices, add the currency. By default, those fields are g:price and g:sale_price
   Example:

   

2. In the link field, add your store’s hostname to the link.
   Example:

   

3. If you want to add a new field:
   1. At the bottom of the screen, click Add field.
   2. Enter the field name.
   3. Enter the field value.
      To add an insert that retrieves data from the VTEX database, click the plus icon and select an insert. The inserts are loaded with the feed configuration page, so if you added a field to the VTEX database in another window, you need to refresh the feed configuration to see it.
4. If you want to remove a field, click the red button to the right of the field.
5. If you want to replace a value or its fragment:
   1. Next to the field you want to modify, click Conversions.
   2. Click Add conversion.
   3. In Current value, enter the string to replace.
      This field is case-sensitive.
   4. In New value, enter the string that will replace the previous string. Example:
      By default, VTEX provides links to scaled-down images. You can modify the image address in g:image_link with this conversion:

      

6. In the upper-right corner of the page, click Save settings.
7. If you want to preview the feed after saving the settings, but before it’s exported to Synerise, go to https://yourshopsubdomain.myvtex.com/_v/synerise/feed-preview?start=0&end=10
   where:
   • yourshopsubdomain is your store’s subdomain.
   • start (optional parameter) is the ID of the first item to show.
   • end (optional parameter) is the ID of the last item to show.
     By default, the preview shows the first 10 items.
8. If you want to view the last feed that was generated for export to Synerise, in the upper-right corner, click Open.
   At the bottom of the file that opens, you can find the number of items and generation time (UTC).

Additional feed settings

Additional settings on the right side:

1. In The frequency of generating the feed, enter a cron expression for how often you want to regenerate the feed for export.
   Important:

   • The interval between updates must be at least 30 minutes.
   • The expression is interpreted starting with full hours, regardless of when you save the settings. For example, if you set the interval to 60 minutes and save the settings at 12:25, the nearest update will be at 13:00, then 14:00, and so on.
   • Copies older than 7 days are deleted from VTEX database.
2. If you want to only include available products in the feed, switch the Only available products toggle on.
3. Only for multistore integrations: In Sales channel, select the store from which you want to send the feed.
4. In Number of products processed at once, set the number of records sent in one batch of the export.
   If your feed has many parameters, a large batch of data may cause problems with transfer between Synerise and VTEX. We recommend setting the batch size to 1000 or less.
5. In the upper-right corner of the page, click Save settings.

Adding the feed to Synerise

In Synerise, create a link to the item feed which will be pulled from VTEX.

1. In Synerise, go to Settings > AI Engine Configuration > Add feed.
2. On the pop-up, select Google Merchant.
3. In the Feed link field, enter https://yourshopsubdomain.myvtex.com/_v/synerise/feed, where yourshopsubdomain is the subdomain of your store.
4. Fill out the rest of the form:
   1. Enter the name of the feed.
   2. As the file type, select XML.
   3. Define the frequency of pulling feed updates to Synerise. This should be the same frequency as the interval you set in the cron expression in VTEX.
   4. In Authentication type, select None.
5. Confirm the settings by clicking Apply.

Result: The item feed generated by VTEX starts being pulled into Synerise. You can use data from the feed, for example in search and recommendation.

Enable Synerise Web SDK on the store’s site

In this part of the process, enable tracking the customer activity and using other Web SDK features in your store (excluding the checkout page) by adding a tracking code.

1. In your VTEX workspace, go to Stores > (Synerise) Settings.
2. In the Tracker code tab, paste the Tracking code for the VTEX store’s website tracking code you created in this part of the process.
3. In the upper right corner, click Save settings.

Enable Synerise Web SDK on the checkout page

The checkout page in VTEX requires a custom script to enable Synerise tracker and SDK. You can implement it in one of the following ways (the choice of the method depends on your checkout page configuration in VTEX):

• Standard checkout configured in VTEX settings
• Custom UI checkout
• Checkout UI Settings

Standard checkout configured in VTEX settings

1. In your VTEX workspace, click the gear icon in the lower left corner and go to Checkout.
2. Next to the name of the store that you are configuring, click the gear icon.
3. On the page that opens, go to the Code tab.
4. From the Files list, open checkout6-custom.js
5. In the file, add the Tracking code for the Vtex checkout page tracking code you created in this part of the process.
   
   WARNING: Don’t add the customPageVisit and dynamicContent parameters in this tracking code!

   

6. Click Save.

Result: Synerise SDK is added to the checkout page and the dynamic content used to track events on the checkout page becomes enabled.

Custom UI checkout

1. Follow the instructions in the VTEX documentation.
2. While performing the procedure described in the documentation, in the JavaScript tab, add the Tracking code for the Vtex checkout page Synerise tracking code from this part of the process.

Checkout UI Settings

1. Follow the instructions in the VTEX documentation described in the Configuration section.
2. While performing the procedure described in the documentation, in the checkout-ui-custom folder, create a JS file with the Tracking code for the Vtex checkout page Synerise tracking code from this part of the process.

Enable data exchange between Synerise and VTEX

In this part of the process, enable data exchange between Synerise and VTEX.

1. In your VTEX workspace, go to Stores > (Synerise) Settings.
2. In the Api tab, enter the Synerise API key which you created in the previous part of the process.
3. In the Host field, enter the API host URL. Depending on the cloud where your Synerise workspace is hosted, use:
   • for Microsoft Azure: https://api.synerise.com
   • for Google Cloud Platform: https://api.geb.synerise.com
     Tip:

     If you don’t know where your workspace is hosted, you can check by looking at the link you’re using to access the Synerise platform.

     • If it’s https://app.synerise.com/login, the workspace is hosted on Microsoft Azure
     • If it’s https://app.geb.synerise.com/login, the workspace is hosted on Google Cloud Platform
4. In the upper right corner, click Save settings.

Enable event tracking

In this part of the process, enable tracking of the backend events related to customers and products. Additionally, you can select the transaction statuses that will trigger sending transaction information to Synerise.

1. In your VTEX workspace, go to Stores > (Synerise) Settings.

2. In the Events tab, enable the Sending events to Synerise toggle.

3. You can add the following events to the list:

   Event name in VTEX	Description	Event in Synerise
   Customer login	This event is generated when a customer logs in to their account on your website.	client.login See details in Event reference
   Customer logout	This event is generated when a customer logs out from their account on your website.	client.logout See details in Event reference
   Add to cart	This event is generated when a customer adds an item to the cart.	product.addToCart See details in Event reference
   Remove from cart	This event is generated when a customer removes an item from the cart.	product.removeFromCart See details in Event reference
   Cart status	This event is generated when the customer changes the contents of the cart.	cart.status See details in Event reference
   Order updated	This event is generated when a customer changes the order.	transaction.charge and product.buy See details of both events in Event reference
   Newsletter subscription	This event is generated when a customer enables the email marketing agreement.	marketingAgreement.turnOn See details in Event reference
   Add to favorite	This event is generated when a customer adds an item to wishlist.	product.addToFavorite See details in Event reference
   Remove from favorite	This event is generated when a customer removes an item from wishlist.	product.removeFromFavorite See details in Event reference

   Important: The events connected with creating, registering, and updating customers will be configured in this part of the process.

4. From the Order statuses dropdown list, select the transaction statuses which trigger sending transaction information (transaction.charge and product.buy events) to Synerise.

5. Complete by clicking Save settings.

Overwriting transaction events

Synerise generates events, such as product.buy and transaction.charge, in response to order statuses that trigger these events. Due to this dependency, it’s possible to overwrite the events that are specifically generated for a particular transaction.

The tables below show which event parameters are changed as a result of overwriting:

• product.buy

  Event parameter	Explanation
  $quantity	- When an item is removed, the value of the parameter is set to0 - When the item quantity changes, the value changes accordingly
  canceled	This parameter is added only when an item is removed. The value is set to true.

• transaction.charge

  event parameter	description
  $revenue	The total value of the transaction may change (for example, as a result of including promotions or removal of items from the order)
  status	Contains the name of the order status which triggered overwriting this event

Implement a service worker

In this part of the process, you will implement a service worker into your eshop which will let you display web push notifications.

1. In your VTEX workspace, go to Stores > (Synerise) Settings.
2. On the Service worker tab, enter the contents of the snr-sw.js file you downloaded while configuring web push notifications in Synerise.
3. Confirm the settings by clicking Save settings.

Enable sending customer data

In this part of the process, you will:

1. Configure the attributes to send (or leave them at default).
2. Enable sending data to Synerise when a customer account is:
   1. created,
   2. updated,
   3. deleted.

This process involves creating webhooks.

Attributes sent to Synerise

The following table lists the customer data that is sent to Synerise.

The same data is sent when synchronizing historical data.

(^\+[0-9 \-()/]{6,19}$)|(^[0-9 \-()/]{6,20}$)

^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$

¹The numbers are checked in the listed order. The first non-empty one is saved in Synerise.

Sending custom attributes

If you want to send additional customer attributes:

1. In your VTEX workspace, go to Stores > (Synerise) Settings.
2. Open the Data tab.
3. In the Customer attributes selector, from the dropdown, select the additional attributes that you want to send to Synerise.
4. Click Save settings.

Customer created an account

1. In the VTEX workspace, go to Store Settings > Master Data.
2. Select the method of authentication.
3. After you have been authenticated, select the Trigger tab.
4. From the Action dropdown list, select Send an HTTP request.
5. In the Name field, enter a meaningful name of the trigger (for example, “Create customer”).
6. From the Data Entity dropdown list, select Customer.
7. Set the Status option to Enabled.
8. In the Rules tab, from the Trigger rule dropdown list, select A record is created.
9. In the Schedule tab, select Run ASAP.
10. In the If Positive tab:
    1. In the URL field, type the endpoint: https://yourshopsubdomain.myvtex.com/_v/private/synerise/triggers/customer
       Replace yourshopsubdomain with your shop’s subdomain.
    2. As the method, select POST.
    3. In the headers, add x-synerise-api-key with your API key as the value.
    4. In the request body, enter the following code:

       {
          "id":"{!id}"
       }
               

       where {!id} will automatically be replaced with the ID of the record.
11. Click Save.

Customer updated the account

1. In the VTEX workspace, go to Store Settings > Master Data.
2. Select the method of authentication.
3. After you have been authenticated, select the Trigger tab.
4. From the Action dropdown list, select Send an HTTP request.
5. In the Name field, enter a meaningful name of the trigger (for example, “Update customer”).
6. From the Data Entity dropdown list, select Customer.
7. Set the Status option to Enabled.
8. In the Rules tab, from the Trigger rule dropdown list, select A record is changed.
9. In the Schedule tab, select Run ASAP.
10. In the If Positive tab:
    1. In the URL field, type the endpoint: https://yourshopsubdomain.myvtex.com/_v/private/synerise/triggers/customer
       Replace yourshopsubdomain with your shop’s subdomain.
    2. As the method, select PATCH.
    3. In the headers, enter the x-synerise-api-key parameters and as a value your API key.
    4. In the request body, enter the following code:

       {
          "id":"{!id}"
       }
               

       where {!id} will automatically be replaced with the ID of the record.
11. Click Save.

Customer account has been deleted

1. In the VTEX workspace, go to Store Settings > Master Data.
2. Select the method of authentication.
3. After you have been authenticated, select the Trigger tab.
4. From the Action dropdown list, select Send an HTTP request.
5. In the Name field, enter a meaningful name of the trigger (for example, “Delete customer”).
6. From the Data Entity dropdown list, select Customer.
7. Set the Status option to Enabled.
8. In the Rules tab, from the Trigger rule dropdown list, select A record is deleted.
9. In the Schedule tab, select Run ASAP.
10. In the If Positive tab:
    1. In the URL field, type the endpoint: https://yourshopsubdomain.myvtex.com/_v/private/synerise/triggers/customer
       Replace yourshopsubdomain with your shop’s subdomain.
    2. As the method, select DELETE.
    3. In the headers, enter the x-synerise-api-key parameters and as a value your API key.
    4. In the request body, enter the following code:

       {
          "email":"{!email}",
          "userId": "{!userId}"
       }
               

       where {!email} and {!userId} will automatically be replaced with the email of the customer and the ID of a customer respectively. In Synerise, userId is the equivalent of customId.
11. Click Save.

Historical data from VTEX

If you want to export historical information about orders and customers from VTEX to Synerise, you can use the Synchronization feature. It lets Synerise access the VTEX database and fetch data about customers and transactions.

Some customer attributes are sent by default. You can add custom attributes. For details, see “Attributes sent to Synerise”.

(^\+[0-9 \-()/]{6,19}$)|(^[0-9 \-()/]{6,20}$)

^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$

After exporting data to Synerise, you can use to train AI models, build analytics, create communication campaigns, and more.

Synchronization is a one-time transfer, usually used for historical data. Continuous connection (event tracking, transaction tracking, customer data updates) for exchanging new data is achieved by completing the integration as described in “Configuration in Synerise” and “Configuration in VTEX”.

Each exported transaction is saved in Synerise as a transaction.charge event and a number of related product.buy events. Exported customers are saved as profiles. If a transaction or profile already exists in Synerise and the synchronization contains new data, the transaction or profile is updated.

1. In your VTEX workspace, create a user role with a set of permissions required for historical imports:
   1. Go to Account settings > User roles > New role
   2. Select the following permissions for Product:
      • OMS
        • Notify payment
        • Notify invoice
        • View order
        • Notify refund
        • Order feed subscription
        • View store sales stats
        • Feed v3 and Hook Admin
        • Feed v3 and Hook view only
        • Subscription view only
        • Subscription metrics and reports
        • List Orders
      • Dynamic Storage
        • Full access to all documents
        • Insert or update document (not remove)
        • List data entity
        • Create data entity
        • Remove data entity
        • View data entity details
      • CMS
        • CMS GraphQL API
      • Pricing
        • Read prices
        • Read trade policy configurations
      • Search
        • General Settings
2. In your VTEX workspace, go to Stores > (Synerise) Synchronization.
3. If this is the first time that you’re accessing this feature, you are asked to allow Synerise access to VTEX API. To do so:
   1. In a new browser tab, open your VTEX admin panel.
   2. Generate an internal application key and token as described in VTEX documentation.
      Important: When you generate the token, copy it immediately. It won’t be accessible later.
   3. Return to the tab where you need to enter the app key and token in the Synerise plugin.
   4. Paste the key and token into the corresponding fields.
   5. Click Authorize.
4. Click Create New.
5. In the pop-up that opens:
   1. Select the date range for the export.
   2. Select one of the export types:
      • ORDERS exports data about transactions and creates/updates transaction.charge and product.buy events.
      • CUSTOMERS exports data about customers and creates/updates profiles.
   3. Click OK.

Result: The transfer starts. You can check its progress in the Status column on the list of synchronizations.