Integrating Magento with Synerise (multistore support plugin version)

Important: This document covers integration instruction for the v2.x plugin version. For the documentation for v1.x plugin version, go here.

The Synerise users can integrate their websites built on the Magento platform. The scope of integration involves the transmission of the following data from Magento to Synerise:

  • information about the customers (their activity, identification of a customer throughout the whole journey),
  • information about the transactions,
  • information about the items
WARNING:

From now on, we support only the Magento versions that are officially supported by Adobe: 2.4.x; and version 2.3 for backward compatibility. Read more about lifecycle policy here.

We recommend to always keep up with the Magento updates, as suggested by the Magento team.

Prerequisites


  1. You must be granted user permissions to access API key section and add the key in Synerise.
  2. You must have access to admin panel in the Magento platform.

Configuration in Synerise


Log in to your workspace in Synerise and perform the steps described below:

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).
    Adding a new API key for the Magento integration
    Adding a new API key for the Magento integration
  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
    Permissions for the API key required by the Magento integration
    Permissions for the API key required by the Magento integration
  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.

    Details of the API key
    Details of the API key

Configuration in the Magento panel


Log in to your administration panel in Magento and perform the steps described below:

Download the Synerise plugin


To download the Synerise plugin in Magento, click here.

Add a workspace


In this part of the process, you need to add a Synerise workspace to your Magento administration panel by using the API key of a workspace. This will allow you to exchange the data between Synerise and Magento.

  1. In your Magento administration panel, go to Marketing > Workspaces.

  2. Click Add workspace.

  3. On the pop-up, in the Api Key field, enter the API key you created in the previous steps.

    Adding a workspace
    Adding a workspace
  4. To add more workspaces, repeat steps 2 and 3.

Assign workspace to your website


In this part of the process, assign the workspace you added to the Magento administration panel to the website you manage in Magento. This way, you can exchange data between Synerise and a website in Magento.

  1. Go to Stores > Configuration > Synerise.
  2. In the Workspace section, assign a workspace to your website by selecting a workspace from the dropdown list.
  3. If you have more websites, you can assign more workspaces to the websites.
Assigning a workspace to a website
Assigning a workspace to a website

Enable page tracking


In this part of the process, you can enable tracking the customer activity in your store by a tracking code which is added automatically as you assign workspaces to the websites. You can also set advanced options related to page tracking in this section as well.

  1. On the left panel, select the Tracking section.
  2. Set the Enabled option to Yes.
  3. Recommended: Set the Open Graph option to Yes.
    Result: Magento sends the following OG tags to Synerise:
    - product:retailer_part_no which is the SKU of the item,
    - product:original_price:amount which is the original price (before discounts, if any)
    - product:price:amount which is the current price of the item
    WARNING: When Open Graph is switched off, the product:retailer_part_no parameter is not added to the pages and you cannot track which product pages are visited.
  4. In case you need to customize the tracking code, in the Custom script subsection, set the Enabled option to Yes. And then, make changes to the code.
  5. If multiple subdomains share a single workspace, in the Cookie domain field enter the domain of the common cookies.
  6. If you need a custom implementation of the page.visit event, in the Custom Page Visit field select Yes. And then make changes to the code.
  7. If you use the tracking code for single page applications, change the Virtual Page option to Yes.
The Tracking section
The Tracking section

Enable event tracking


In this part of the process, enable tracking of the backend events related to customers and products.

  1. In the left panel, select Events section

  2. Select the scope of tracked events.

    1. Set the Enabled option to Yes.
    2. Select the events (command + click or ctrl + click) that will be tracked by Synerise and available in the customers’ profiles. You can choose from the following events:
      Event Description Action name in Synerise
      Customer login This event is generated when a customer logs in to
      their account on your website.
      client.login
      Customer logout This event is generated when a customer logs out from
      their account on your website.
      client.logout
      Customer updated This event is generated when a customer makes changes to their account (for example, updates information about birthday, location, and so on). client.updateData
      Customer registration This event is generated when a customer creates an account on your website. client.register
      Customer added product to cart This event is generated when a customer adds an item
      to the cart.
      product.addToCart
      Customer removed product from cart This event is generated when a customer removes
      an item from the cart.
      product.removeFromCart
      Cart updated This event is generated when a set of items in the cart changes - a customer deleted or added items. cart.status
      Cart quantities updated This event is generated when the customer changes the amount of a particular item already present in the cart. cart.status
      Order updated This event is generated when a customer changes the order. transaction.charge
      Product updated This event is generated when a product has been edited - then the product is added to queue to be synchronized. n/a
      Product deleted This event is generated when the product is removed from Magento. The product stays in the Synerise catalog and the deleted=1 parameter is added. n/a
      Product import This event is generated when a product has been edited through the import of data. n/a
      Product “is salable” value changed This event is generated when the value of the is_salable parameter changes (this parameter defines whether a product can be sold) - then the product is added to queue to be synchronized. n/a
      Product stock status changed This event is generated when the stock status of the product changes (stock status and is_salable parameter are not equivalent) - then the product is added to queue to be synchronized. n/a
      Subscription updated This event is generated when a customer changes their marketing agreements. newsletter.subscribe / newsletter.unsubscribe
    Important: We recommend selecting all the events.
    The list of events
    The list of events

Synchronize additional data apart from those which are sent to Synerise through customer actions (synchronization is triggered by cron jobs). Go to the Synchronization section.

Enable data synchronization


WARNING: Synchronization is disabled by default. Before enabling, verify the configuration of each item attribute to make sure it contains all data you want to include.

In this part of the process you can synchronize the data collected before integration. You can synchronize Models and Store Views (variations of the same store in different languages). By default, all models and store views are selected to be synchronized.

If you want to exclude some models from synchronization, go to Stores > Configuration > Synerise > Data and deselect them from the lists. Below you can find the table that describes each model.

If you want to exclude store views from synchronization, go to Stores > Configuration > Synerise > Workspaces.

Model Description Place of storage in Synerise
Customers Customer attributes in Magento are qualities assigned to customers. You can send to Synerise all attributes, including those which are custom. The list in the Attributes section excludes required attributes which are sent by default:

- email,
- entity_id,
- firstname,
- lastname,

The changes of attribute selection will apply only for customers who haven’t been sent to Synerise yet. To apply the changes to all customers go to Marketing > Synerise > Dashboard
and use Resend all items option.
The Profiles module
Orders Information about orders are stored as product.buy/transaction.charge events. Activity list on the profile of a customer in the Profiles module
Products Product attributes in Magento are qualities assigned to items. You can send all attributes to Synerise, including those which are custom. The list in the Attributes excludes the required attributes which are sent by default:

- itemId (sku),
- price,
- productUrl,
- parendId,
- deleted,
- category,
- additionalCategories,
- image,

The changes of attribute selection will apply only for products which haven’t been sent to Synerise yet. To apply the changes to all products go to Marketing > Synerise > Dashboard
and use Resend all items option.
Data Management > Catalogs
Subscribers The value of the subscription attribute of a customer. Profile of a customer in the Profiles module

To schedule synchronization:

  1. Go to Stores > Configuration > Synerise.
  2. On the left panel, select Synchronization.
  3. Set the Enabled option to Yes.
  4. In the Cron expression field, enter the time of the synchronization in the form of a cron expression.
  5. In the Page size field, enter the size of a batch of items that will be sent in a single request.
    Important: Extending the default size might speed up synchronization process, but it also means heavier database usage.

On the first run, the last item ID of each data type (before the integration) is recorded to mark the end of the data sets that need to be synchronized. You can also reset last ID to current one manually from integration dashboard, using the Send additional option.

This process is also responsible for resending the full data sets, which can be triggered through integration dashboard by using the Resend all items option in Magento > Marketing > Synerise > Dashboard.

The Synchronization section in the Magento panel
The Synchronization section in the Magento panel

Update Synchronization

This subsection allows you to synchronize ongoing item updates. It is based on the item queues, which are built by data update events (such as product.updated event).

Important: It is highly recommended to keep the update synchronization process running, while the data synchronization can be disabled when unused.
  1. Set the Enabled option to Yes.
  2. In the Cron expression field, enter the time of the synchronization in the form of a cron expression.
  3. In the Page size field, enter the size of a batch of items that will be sent in a single request.
    Important: Extending the default size might speed up synchronization process, but it also means heavier database usage which can slow down the work of the service.
😕

We are sorry to hear that

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

😉

Awesome!

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

Close modal icon Placeholder alt for modal to satisfy link checker