This document provides integration instructions for the v2.x and higher plugin versions, which support both *single-store* and *multi-store* implementations. 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

From 23 Mar, 2024, we support only the Magento versions that are officially supported by Adobe: 2.4.x and higher; and version 2.3 for backward compatibility. 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

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 - **SEARCH**: - ITEMS_SEARCH_CONFIG_SEARCH_CREATE, - ITEMS_SEARCH_CONFIG_SEARCH_UPDATE, - ITEMS_SEARCH_CONFIG_SEARCH_READ, - ITEMS_SEARCH_SEARCH_READ - **TRACKER** - TRACKER_CREATE - **TRANSACTION** - API_BATCH_TRANSACTION_CREATE - API_TRANSACTION_CREATE

Permissions for the API key required by the Magento integration

6. Confirm by clicking **Apply settings**. 8. On the **General** section, click **Show**. 9. Copy the API key and paste to the notepad.

#### Enable basic workspace authentication (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 workspace authentication requires only the usage of the workspace GUID and API key, eliminating the need for additional requests or timeouts. However, this approach may increase vulnerability. The full instruction is available in ["Basic workspace authentication"](/docs/settings/tool/api#basic-workspace-authentication) ## 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](https://github.com/Synerise/magento2-integration). ### 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 > Synerise > Workspaces**. 2. Click **Add workspace**. 3. From the **Environment** dropdown list, select the option according to your Synerise deployment variant. 4. In the **Api Key** field, enter the API key you [created in the previous steps](#create-an-api-key). 5. If you want to use [basic workspace authentication](/docs/settings/tool/api#basic-workspace-authentication): 1. Set the **Enable** option to **Yes**. 2. In the **GUID** field, enter the GUID you obtained while performing the ["Basic workspace authentication"](/docs/settings/tool/api#basic-workspace-authentication) procedure.

6. To add more workspaces, repeat actions from step 2 onwards. ### 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 **Website** 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 them. 4. In the **Stores** section, you can select stores for event tracking and [data synchronization with Synerise](/docs/settings/tool/magento/synchronizing-data-between-synerise-and-magento).

### Enable page tracking --- In this part of the process, you can enable tracking the customer activity in your store by [a tracking code](/developers/web/installation-and-configuration) 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. 2. On the left panel, select the **Tracking** section. 1. 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

When **Open Graph** is switched off, the `product:retailer_part_no parameter` parameter is not added to the [page.visit](/docs/assets/events/event-reference/web-and-app#pagevisit) events. This means the event doesn't include an identifier of the viewed event, preventing the generation of Synerise recommendations based on the Similar model, if you use any. Cart and transaction events remain unaffected.

3. 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. 4. If multiple subdomains share a single workspace, in the **Cookie domain** field enter the domain of the common cookies. 5. 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. 6. If you use the [tracking code for single page applications](/developers/web/installation-and-configuration), change the **Virtual Page** option to **Yes**.

### Enable event tracking and queuing events --- In this part of the process, enable tracking of the backend events related to customers and products. Also, you can enable [queuing events](#queuing-events) instead of sending them in real time. By default, events are sent in real time. 1. In the left panel, select **Events** section 3. 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](/docs/crm/crm-profile). You can choose from the following events:

We recommend selecting all the events.

Click here to expand the list and description of 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

To synchronize additional data apart from those which are sent to Synerise through customer actions, go to the ["Enable data synchronization"](#enable-data-synchronization) section. 3. If you want to add the parameters from the [_snrs_param cookie](/developers/web/cookies#_snrs_params) to the [cart and transaction events](/docs/assets/events/event-reference/items), set the **Include Tracking Params** option to **Yes**. #### Queuing events Queuing events is based on the [Message Queues implementation](https://developer.adobe.com/commerce/php/development/components/message-queues/). 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.

You can learn more about Message Queues in ["Message Queues logic" article](/docs/settings/tool/magento/magento-message-queues).

1. In the **Message Queues** section, set the **Enabled** option to **Yes**. 2. In the **Events to send by queue**, select the scope of events sent this way. The unselected events will be sent in real time. 3. In the upper right corner, click **Save Config**.

If you define new store views in Magento, execute the `bin/magento setup:upgrade` command.

### Enable data synchronization --- Follow the instructions in the [Synchronizing and exporting data](/docs/settings/tool/magento/synchronizing-data-between-synerise-and-magento) article. ### Define request settings --- In this part of the process, you can define the timeout period for the live and scheduled requests. 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](#enable-event-tracking-and-queuing-events) 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 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.