Integration for stores using FastStore framework

This guide contains instructions on integrating Synerise with a store built on the FastStore framework. If you are unsure which framework is used in your project, refer to the VTEX documentation.

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.

The article is divided into three main parts, each of which contains procedures for specific platforms:

1. Configuration in the Synerise platform.
2. Configuration in the VTEX platform.
3. Configuration in the application files.

Plugin scope

• Tracking transaction, cart, and customer activity events
• Tracking the checkout page
• Identifying customers after they fill out a form
• Synchronizing data between Synerise and VTEX through webhooks: creating, updating, and removing accounts; marketing consent changes
• Exporting historical data about customers and orders from VTEX to Synerise.

Configuration in Synerise

Generate the tracking code

To enable tracking the customer activity on your website, create a tracking code which you will implement into your code files 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.

   

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

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

To initiate the exchange of data between Synerise and VTEX, you will provide the workspace API key, Synerise API GUID, and select Synerise API host.

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 the workspace GUID.
   Filling out this field results in setting GUID to be a password and Workspace API key a login for basic authentication.
   You can find the GUID in the settings of your API key, after enabling Basic access 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:
   • if your Synerise portal URL starts with https://app.synerise.com/, use Microsoft Azure.
   • if your Synerise portal URL starts with https://app.geb.synerise.com/, use Google Cloud Platform.
4. Click Next.

Skip enabling Synerise Web SDK on the store’s site

1. In the view that opens, leave Tracking code empty.
2. Click Next.
      You will add the tracking code later to the application files. The process is described in the “Add the Synerise tracking code” section further in this article.

Define additional settings

In this part of the configuration, you will:

• leave the Customer/product tracking event section empty - you will enable tracking all events after adding the tracking code to the application file later in the process. It is described in the “Add the Synerise tracking code” section further in this article.
• 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
• leave the Web push notification configuration field empty, this option is non-configurable for the FastStore plugin configuration

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

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

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

Complete the configuration by clicking Configure.

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

Configuration in your application files

This part of the process involves making changes to your application files.

Add the Synerise tracking code

In this part of the process, you will prepare a Synerise tracking code for use with the FastStore framework. Once you add the tracking code in your application files, you will be able to track the following events:

1. Go to the Synerise platform.

2. Go to Settings > Tracking codes.

3. On the list, find the tracking code you generated in the Generate the tracking code part of the process.

4. Open the preview of the tracking code.

5. Copy the value of the trackerKey parameter and save in the notepad.

6. Copy the code below to the notepad and in the trackerKey parameter value, paste the tracker key you copied in the previous step.

7. Implement the code below according to the instructions in Adding the third-party scripts.

       const ThirdPartyScripts = () => {
       return (
           <script
           dangerouslySetInnerHTML={{
               __html: `
                   function onSyneriseLoad() {
                       SR.init({
                           trackerKey: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
                           plugin: "faststore",
                       }).then(function () {
                           SR.event.pageVisit().then(function () {
                               SR.dynamicContent.get();
                           });
                       });
                   }
                   (function(s,y,n,e,r,i,se){s["SyneriseObjectNamespace"]=r;s[r]=s[r]||[],
                   s[r]._t=1*new Date(),s[r]._i=0,s[r]._l=i;var z=y.createElement(n),
                   se=y.getElementsByTagName(n)[0];z.async=1;z.src=e;se.parentNode.insertBefore(z,se);
                   z.onload=z.onreadystatechange=function(){var rdy=z.readyState;
                   if(!rdy||/complete|loaded/.test(z.readyState)){s[i]();z.onload = null;
                   z.onreadystatechange=null;}};})(window,document,"script", "//web.snrbox.com/synerise-javascript-sdk.min.js", "SR", "onSyneriseLoad");
               `,
           }}
           />
       )
       }
       export default ThirdPartyScripts
       

Implement AI recommendations and AI Search

Optionally, you can implement Synerise AI recommendations and AI Search to let you display recommendations in your store and let your customers use the AI-powered search. To do so, refer to the Github documentation.