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; marketing consent changes
• 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 a workspace with products you want to display in your shop.

Pre-configuration in Synerise

Generating the tracking code

To enable tracking the customer activity on your website, create a tracking code which you will implement into your store later in the process.

1. In Synerise, go to Settings > Tracking codes and generate a tracking code dedicated to VTEX.
   Full instruction on generating tracking codes is available here.

   

   Result: Synerise generates 2 tracking codes.

2. Copy the generated tracking codes and save them in the notepad. One of them will be needed for Enabling data exchange between Synerise and VTEX and the other will be needed for Enabling Synerise Web SDK on the checkout page

   

Creating an API key

Create an API key with specific permissions (the list is available in the instruction below), which will enable authorization between Synerise and VTEX.

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

2. On the pop-up:

   1. Select Workspace.
   2. Enter the name of the API key (it will be visible on the list of API keys).
   3. Optionally, in the Description field, you can provide a brief explanation for the purpose of the key. This will help you and your team in identifying the key promptly on the API key list.

   

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 all the permissions listed below to enable complete synchronization of data between Synerise and VTEX:

   Click to expand the list of permissions

   • 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. Close the pop-up with permissions.

8. On the General section, click Show.

9. Copy the API key into 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, set the CSS Selector option to After.
6. 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 Use in communication.
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.
    5. Confirm the settings by clicking Apply.
15. Optionally, in the UTM & URL parameters section, define these parameters.
16. In the upper right corner, click Activate.

Setting up web push notifications

If you want to enable web push notifications:

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

Configuration in VTEX

Install the Synerise plugin

Install the application through the VTEX console:

1. Download the VTEX console.
2. In the console, log on to your VTEX workspace.
3. Install the Synerise application with the following command: vtex install synerisepartnerar.synerise-integration
   Result: A native Synerise integration appears in the Apps section in the menu and you will be redirected to the Configuration section automatically.

   

Enable data exchange between Synerise and VTEX

This is the first part of the integration. To initiate the exchange of data between Synerise and VTEX, you will provide the workspace API key, paste the tracking code you generated and declare the scope of customer activities and attributes you want to send to Synerise.

1. In the Synerise Workspace API key field, enter the Synerise API key which you created in “Creating an API Key.
2. If you want to use basic authentication, in the Synerise API GUID (Optional) field, enter GUID which you can locate in Synerise Settings > API keys > Basic access authentication. Filling out this field results in setting GUID to be a password and Workspace API key a login for basic authentication.
   
   Note: Read more about Basic authentication.
3. From the Synerise API host list, select the API host URL. Depending on the cloud where your Synerise workspace is hosted:
   • for https://api.synerise.com, use Microsoft Azure
   • for https://api.geb.synerise.com, use Google Cloud Platform
     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. Click Next.

Enable Synerise Web SDK on the store’s site

In this part of the configuration, you will enable tracking the customer activity and using other Web SDK features in your store (excluding the checkout page) by pasting the Tracking code for VTEX store page you generated in “Generating the tracking code”.

2. In the Tracker code field, paste the Tracking code for the VTEX store page tracking code you created in this part of the process.

   

3. Click Next.

Define additional settings

In this part of the configuration, you will:

• enable tracking of the backend events related to customers and products
• select order statuses which will overwrite transaction information
• select customer attributes to be added to the transaction event metadata
• select additional customer attributes to send to Synerise
• setting up web push notifications

Enabling tracking of backend events

From Customer/product tracking events, select the events you want to track and send to Synerise. The events connected with creating, registering, and updating customers will be configured later in the process.

Selecting order statuses for overwriting transaction events

From the Order statuses for data updates dropdown list, select the status or statuses that will update the transaction information in Synerise. As a result, the existing transaction.charge and product.buy events generated by that order will be updated. Refer to the tables below to see which parameters are overwritten:

• product.buy

  Event parameter	Explanation
  $quantity	- When an item is removed, the value of the parameter is set to 0. - 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.

Selecting customer attributes added to orders

In the Customer attributes added to orders field, you can add customer attributes which will be added to the metadata of the transaction events.

Selecting additional customer attributes

In the Additional customer attributes field, select the VTEX attributes which will be sent to the Synerise. These attributes will be saved in the customer’s profile.

Configuring web push notifications

If you want to implement web push notifications in your shop, you must first configure them in Synerise. You can find instructions how to do it in “Setting up web push notifications” section in this document. If you already have done it, perform the steps below:

2. In the Web push notification configuration, enter the contents of the snr-sw.js file you downloaded while setting up web push notifications in Synerise.
3. In the upper right corner, click Save.
   Result: You are redirected to the summary of the plugin configuration.

Review summary of configuration

At this stage, you are already tracking the activity of your customers on your website and these data are sent to Synerise, however tracking on the checkout page is still disabled. You can find instructions how enable it in “Enable Synerise Web SDK on the checkout page” section in this document.

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 catalog in Synerise.

This part includes the following sub-procedures:

• mapping required and additional parameters
• enabling feed generation
• adding the feed to Synerise

Mapping parameters

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. The field names and values that you send to Synerise must meet the requirements of the Google Merchant XML feed.

Ensure that your feed includes the item IDs and the size attribute values as an array, along with other attributes of the item variants also presented as an array. Otherwise, the first available item variant in the product feed will be sent to the Synerise catalog which will make personalizing items in a recommendation according to the size (or other attributes) impossible.

For each mapping:

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

1. In your VTEX workspace, go to Apps > (Synerise) Product Feeds.
2. In all fields that indicate prices, add the currency.
   By default, this field is g:price and this field doesn’t contain currency. For example, to add EUR to the price, enter: `{% product.selling_price %} EUR
3. In the link field, add your store’s hostname to the link.
4. If you want to add a new field, click Add field.
   1. In the Name field, enter the field name.
   2. Enter the Value field, enter the value.
      To add an insert that retrieves data from the VTEX database, click the icon and select an insert. The inserts include Metadata, which is the list of additional transaction parameters and Specification which is the list of additional properties that can be added to your items or item variants.
      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.
5. If you want to remove a field, click the icon to the right of the field and then Delete.
6. If you want to replace a value or its fragment (for example, to change the Portuguese gender values to English):
   1. Next to the field you want to modify, click the and then Convert.
   2. In Current value parameter, enter the string to replace.
      This field is case-sensitive.
   3. In New value parameter, 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:

      

7. To proceed to the next stage of configuring product feed, click Next.
   Result: The configuration for sending item variants opens.

Configuring product feed

You can enable automatic product feed generation and define its frequency.

1. Enable the Generate feed toggle.

2. By enabling the Only for available products toggle, you can exclude out of stock items.

3. You can set the frequency of generating the product feed and use the predefined or the custom value. We don’t recommend setting it more often that is needed due to performance reasons.

   Important:

   • 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.

4. In Sales channel, select the store from which you want to send the feed.

5. 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.

6. In the upper-right corner of the page, click Save settings.
   Result: You are redirected to the review of Item feed settings.

7. If you want to review the feed after saving the settings, open the link in the Product feed link field:

   

8. Copy the link from the Product feed link field and save in the notepad. You will need this for Adding the feed to Synerise.

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 the link to the product feed which which you can get after enabling automatic product feed generation.
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.

Historical data synchronization

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 it 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 “Pre-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.

Create a role

You must first create a role which allows for sending historical data to Synerise.

1. In your VTEX workspace, create a 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

Schedule synchronization

1. In your VTEX workspace, go to Apps > (Synerise) Access to VTEX.

2. 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. Assign the role you created to the VTEX API key.
   4. Paste values from step 2 in VTEX API key and VTEX app token, respectively.
   5. Return to the tab where you need to enter the app key and token in the Synerise plugin.
   6. Paste the key and token into the corresponding fields.
   7. Click Save.

3. If you want to synchronize marketing consents:

   1. Enable the marketing consent toggle.
      This works in both directions; any changes in marketing consent in either Synerise or VTEX will be synchronized.
   2. To create a new user who doesn’t exist in VTEX database, but exists already in Synerise, select the Adding new users while synchronizing marketing consents checkbox.

4. Select the Synchronization tab.

5. Click New synchronization.
   There is a limit of 2 active synchronizations.

6. In the pop-up that opens:

   1. 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.
   2. Select the date range for the export.
   3. Click OK.

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

Optional

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.

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 “Generating the tracking code” section.
   
   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 Synerise tracking code from “Generating the tracking code” section.

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 Synerise tracking code from “Generating the tracking code” section.