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 General section, click Show.

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

    Details of the API key
    Details of the API key

Enable basic authorization (optional)

By default, the authorization process involves obtaining a token with a limited lifespan. To acquire this token, you must send a request. Alternatively, basic authorization requires only the usage of a GUID and API key, eliminating the need for additional requests or timeouts. However, this approach may increase vulnerability.

  1. If you want to authorize requests only by API key and GUID (workspace login), in the Basic authorization section, click Show.
  2. Switch the Enable basic access authentication toggle on.
    Result: A GUID field appears.
  3. Copy the value of the GUID field and save it in the notepad.
    This value serves as a workspace identifier which will be used as a login in the authorization requests. To learn more about basic authorization, read “Basic access authentication”.
  4. Confirm by clicking Apply.

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. In the Api Key field, enter the API key you created in the previous steps.

  4. If you want to use basic authorization, in the GUID field, enter the GUID you obtain while performing the “Enable basic authorization (optional)” procedure.

    Adding a workspace
    Adding a workspace
  5. 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:
    Important: We recommend selecting all the 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. marketingAgreement.turnOn / marketingAgreement.turnOff / newsletter.unsubscribe
    The list of events
    The list of events

    To synchronize additional data apart from those which are sent to Synerise through customer actions (synchronization is triggered by cron jobs), go to the “Enable data synchronization” section.

  3. If you want to add the parameters from the _snrs_param cookie to the cart and transaction events, set the Include Tracking Params option to Yes.

Enable queuing events


In this part of the process, you can enable queuing events instead of sending them in real-time. This option is based on the Message Queues implementation. When this option is enabled, the events are queued up and then sent through a consumer process. When this option is disabled, the events are sent in real time. This option is disabled by default.

To enable queuing events:

  1. Go to Stores > Synerise > Message Queues.
  2. Set the Send by queue option to Yes.
  3. From the dropdown list, select the connection:
    • db - Select this option to use queueing based on your database.
    • amqp - Select this option to use queueing based on RabbitMQ.
      WARNING:
      • Before you start using amqp as the connection type, make sure you have access to RabbitMQ and that the connection is properly setup in env.php, as stated in the Magento documentation.
      • Changing the connetion type may result in loss of some events.
  4. In the Events to send by queue, select the scope of events sent this way. The unselected events will be sent in real-time.
  5. In the upper right corner, click Save Config.
    The Message Queue tab in the Mageto plugin
    The Message Queue tab in the Mageto panel
  6. To make sure the topics are updated, clean the caches and execute the bin/magento setup:upgrade command.

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,

To enable sending the text values of the attributes which can take more than one value, set the Labels as Values to Yes. If this option is disabled, the values are sent to Synerise in the form of IDs, for example, for the color attribute, Magento sends the following values: 1, 2, 3 instead of black, white, grey.

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.

Define request settings


In this part of the process, you can:

Define timeout

A timeout defines the time to wait for a response. If the waiting time exceeds the value specified in the configuration, the request will be canceled. In the case of live requests, data may not be sent, hence using event queuing is recommended.

  1. Go to Stores > Configuration > Synerise > API.
  2. To define the timeout period for live requests, in the Live requests section, in the Timeout field, enter the value.
  3. To define the timeout period for scheduled requests, in the Scheduled requests section, in the Timeout field, enter the value.
  4. In the upper right corner, click Save Config.

Enable basic authentication

In this section, you can enable authentication by providing GUID and API key in request. To do so, set the Enable basic authentication option to Yes.

Important: The workspaces must also have GUIDs assigned to them in the Marketing > Workspaces menu in Magento.

Enable request logging


You can enable logging all activities in the Synerise module in Magento and easily access the log files in Magento. Each occurrence that needs to be logged, such as an error, triggers the generation of a corresponding log file.

In this part of the process, you can:

  • enable logs of all activities in the Synerise module, which you can later download
  • enable saving full API request and response from Synerise API
  • exclude data from logs
  1. In the Debug section, set the Enable logging option to Yes.

  2. Go to Content > Logs.

  3. On the list of files, find the one you want to download.

  4. In the Action column, click Download The files contain data such as error descriptions, warnings, and so on.

    The Synerise logs section in the Magento panel
    The Synerise log section in the Magento panel
  5. To enable saving full API requests and responses from Synerise API, in the Debug section, set the API request logging option to Yes.
    This option can be enabled only when the enable logging option is active. In such case, the requests and responses will be included in the log files.

  6. To eliminate unnecessary data from logs, you can add these data to or delete the data in the Debug section on the Exclude from logging list. Any data included in this list will not appear in the logs.

The Debug section in the Magento panel
The Debug section in the Magento panel
😕

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