MENU

Search our knowledge base or contact us:  support@salesmanago.com,  +1 800 960 0640

Integration with Magento 2

Magento 2 is one of the most popular eCommerce platforms on the international market. It allows you to sell products online by creating different language versions of a single store with separate configurations. With the intuitive admin panel, you can manage individual domains and adjust currencies, payment methods, or deliveries to each language version.

To download the plugin from Marketplace, click here.

Contents

  1. Basic information
  2. Scope of integration
  3. Installation
  4. Configuration
    a) Logging in
    b) Account Settings
    c) Magento 2 Settings
    d) Data export
  5. Technical description
    a) Database
    b) Hooks
    c) Monitoring Code

1. Basic information

In this article, you will find detailed information about integrating of SALESmanago with the Magento 2 platform. The plugin is constantly being improved and available for free to our customers.

Integrating Magento 2 with your SALESmanago account will enable you to transfer relevant contact and transaction data between the platforms. You can use this information to automate marketing activities and thus boost your sales in the e-store.

2. Scope of integration

The scope of integration includes:

  • Sending external events (CART, PURCHASE) for contacts who are logged in and contacts who are not logged in but have a previously created smclient cookie.
  • Exporting of archival data (customers, orders).
  • Automatically adding a Monitoring Code to a website.
  • Option to assign tags when a contact registers, logs in, signs up for a newsletter or makes a purchase.
  • Option to automatically add basic functionalities, such as Live Chat, Pop-up Basic and Web Push.
  • Adding a monitoring parameter to users that filled in a contact form.
  • Sending contact data, including the tags assigned to them in the store.
  • Updating a contact’s opt-in status to, and optionally from, SALESmanago.

3. Installation

As with other Magento 2 modules, installation of the SALESmanago plugin requires technical knowledge. Due to this specificity of the Magento 2 platform, the installation should be performed by a developer.

If you already have the module installed, go to the “Configuration” section.

Before starting, add the module to your Magento Marketplace account >>

[1] Edition – select the edition compatible with the version of your Magento 2 store. You can choose from:

  • Open Source (CE).
  • Commerce on-premise (EE).
  • Commerce on Cloud (ECE).

[2] Your store version – select your store version: 2.3 or 2.4.

[3] Add to Cart – add to the cart and complete the order.

To integrate the plugin, turn on the console and in the Magento 2 main catalog install the module by entering one of the commands below:

  • composer require salesmanago/integration:x.x.x

    – for the development environment.

  • composer require salesmanago/integration:x.x.x --no-dev

    – for the production environment.

IMPORTANT: For “x.x.x”, enter the plugin version you want to use.

Check the current version of the plugin >>

Then add the module to the platform by entering the following commands:

php bin/magento setup:upgrade;
php bin/magento setup:di:compile;
php bin/magento setup:static-content:deploy;
php bin/magento cache:flush;

Module installation for Magento version below 2.3

If you have a store version older than Magento 2.3, you can use an alternative method of installing the plugin by going to the Packagist modules repository.

Visit the SALESmanago plugin website on Packagist >>

To integrate the plugin, turn on the console and in the Magento 2 main catalog, install the module by entering one of the commands below:

  • composer require benhauer/salesmanago-integration:x.x.x

    – for the development environment.

  • composer require benhauer/salesmanago-integration:x.x.x --no-dev

    – for the production environment.

IMPORTANT: For “x.x.x”, enter the plugin version you want to use.

Check the current version of the plugin >>

Then add the module to the platform by entering the following commands:

php bin/magento setup:upgrade;
php bin/magento setup:di:compile;
php bin/magento setup:static-content:deploy;
php bin/magento cache:flush;

4. Configuration

A. Logging in

After installing the plugin and going to the Magento 2 admin panel, you will see the login screen. Enter the data you use when logging in to SALESmanago in the appropriate fields [1]. If your SALESmanago account is on a different (custom) endpoint, click Use custom endpoint [2] and enter the appropriate address in the field.

Sometimes, you may experience some minor difficulties when logging in. Possible reasons include:

  • Incorrect login data – to solve this problem, check your data by logging in to the SALESmanago admin panel.
  • Two-Factor Authentication (2FA) – if you are using this login method, please contact Customer Success for more information.
  • Incorrect endpoint – if your SALESmanago account is on a different (custom) endpoint, use the Change endpoint option.

IMPORTANT: You can check the endpoint assigned to your account in the SALESmanago system (Settings → Integration). If the endpoint starts with anything other than “www”, “app2” or “app3”, contact Customer Success.

[3] Scope – on the drop-down list, you will find store views that you can manage within the Magento 2 admin panel. The SALESmanago plugin allows you to change settings for all stores at the same time or only for selected ones.

[A] All Store Views – select if you want to switch the scope to the view of all stores at once.

[B] Main Website Store – select if you want to switch the scope to the view of the selected store. Their names will vary depending on the website’s language or domain, such as “example.com” and “example.net”.

[4] Using the SALESmanago icon in the side menu, you can go to the plugin’s configuration panel.

[A] Here, you will find information about the plugin version you are using, the Client ID, and the Endpoint URL assigned to the logged-in SALESmanago account.

[B] Logout – click to log out of your SALESmanago account. If you do this, the Monitoring Code turns off and the automatic transfer of contacts and events is stopped.

[C] Plugin configuration – click to go to the plugin configuration.

The Scope switch on the configuration screen is responsible for moving between the configurations of individual store views. Default Config is the configuration of all stores.

IMPORTANT: If you want to change settings for only one store, log in to the plugin by selecting all stores view [A]. Then, in the drop-down list, click on the store that you want to configure and log in again.

B. Account settings

[1] Client ID – this is the identifier of your SALESmanago account. Once you are logged in, you can find it in Settings → Integration. This information is added automatically, so you do not need to edit it.

[2] Endpoint – indicates the location of your SALESmanago account. This information is added automatically, so you do not need to edit it.

[3] Contact owner email – in this drop-down list, you will find email addresses of those in the SALESmanago account that have the contact owner role. Select the email address to which new contacts sent from your store will be assigned.

[4] Click here to update owners list – if the email you are searching for is not in the drop-down list, click on the refresh button to synchronize the current list of contact owners from SALESmanago.

[5] Synchronize contact statutes – select “Yes” if you want to check whether a contact who registered on your platform is already in the SALESmanago database. In addition, contacts with opt-in status in the SALESmanago system are added to the group of subscribers in Magento 2.

[6] Double Opt-in – choose “Yes” if you want to activate the Double Opt-in option. This is a mechanism where a user must confirm their email address through another link after subscription. This action is in line with the best practices of consent-based marketing. At the same time, it increases the chances of high deliverability, Open Rate, and conversion rates in the indicated channel.

By default, a confirmation email will be sent in the language version corresponding to that of the user’s browser. If you have configured the sending of confirmation emails in SALESmanago, leave these fields blank so that the data can be downloaded directly from the system. If you want to choose a specific template, complete all 3 fields [A, B, C].

[A] Email template ID – use the confirmation email template created in the SALESmanago system.

[B] Email account ID – indicate the email account in the SALESmanago system from which a confirmation message will be sent.

[C] Email subject – enter the subject of the confirmation email.

Read more about enabling Double Opt-in on eCommerce platforms >>

B. Magento 2 settings

To go to the platform settings, select Magento 2 Settings on the plugin configuration screen.

[1] Callbacks – allow you to synchronize opt-in [A] and opt-out [B] status from SALESmanago to Magento 2, e.g., when:

  • The contact unsubscribes from the newsletter via the link in the email footer.
  • The contact subscribes to the newsletter via Lead Generation widgets (e.g., pop-ups).
  • The contact status is changed manually or on some other integration.

Callback URLs should be copied into the appropriate fields in the SALESmanago system (Settings → Other → Application).

Read more about callbacks >>

[2] Tags – in selected categories, set tags that will be assigned to contacts sent to SALESmanago.

[A] Purchase tag – these tags will be assigned to contacts after purchase.

[B] Subscription tag – these tags will be assigned to contacts after signing up for the newsletter on your Magento 2 store.

[C] Guest purchase tag – these tags will be assigned to contacts after making a guest purchase.

[D] Registration tag – these tags will be assigned to contacts after registering on the platform as customers.

IMPORTANT: All tags should be separated by commas, without spaces (e.g., MAGENTO2_NEWSLETTER,MAGENTO2_SUBSCRIPTION).

[3] Contacts – settings related to contacts.

[A] Email domains to ignore – contacts whose email addresses contain the domains entered in this field will not be transferred to SALESmanago. In particular, you can enter temporary emails and indirect emails domains, e.g., randomized email addresses used by Marketplace providers. 

IMPORTANT: Separate particular domains with commas, without spaces (e.g., example.com, domain.com).

[4] Events – set options related to products and external events.

[A] Location/SALESmanago Store ID – is the Product Feed ID that allows you to match orders and transactions from your Magento 2 store to the Product Feed added in SALESmanago. The value of this field should match the location field configured in the SALESmanago system (Settings → Integration → Product Feeds). It is important to make any necessary edits so that they both have the same value. This data will be used to display products in the recommendation frames, newsletters, and Web Push notifications.

[B] Product type ID – choose the type of product identifier transferred as the product’s External ID. You can choose:

  • ID – product identifier created within your store,
  • SKU – the trade identifier of the products.

[C] Event cookie lifetime – select the time after which the CART event will no longer be updated. Whenever a customer adds a product to the cart, this creates a CART event in SALESmanago and a smevent cookie in your e-store. The selected cookie lifetime is the period over which the CART event is updated. You can choose:

  • 3h. 
  • 12h.
  • 24h.
  • 48h.
  • 72h.
  • 100h.
  • 200h.
  • 300h.
  • 400h.
  • 500h.

EXAMPLE: If you select a 12h cookie lifetime, the CART event keeps updating for 12 hours from the time of adding the product to the cart. After this cookie expires, the event is no longer updated and a new CART event is created for the contact.

[5] Cart – additional settings related to a cart.

[A] After cart recovery redirect to – indicate the place to which the user will be redirected after launching the cart via the link sent in the email. You can choose:

  • Purchase summary page – redirects to the purchase summary page.
  • Cart page – redirects to the cart page.

 

[6] Purchases – configure settings related to external PURCHASE events.

[A] Purchase events processing type – indicate which hook will be used to send PURCHASE events to the SALESmanago system. A hook is a mechanism used by many eCommerce platforms that allows you to launch a certain action at a specific time. In the case of the SALESmanago plugin, this can be, for example, sending a contact to SALESmanago. To improve various payment mechanisms and order fulfillment methods, our plugin allows you to select the hook that is responsible for the purchase event.

  • Default – the default option that will send events to the system at the very beginning of the order validation stage.
  • System event – an option that allows you to choose the hook responsible for sending events from a list of system events [B].
  • After all system events – an option that will send events to the system after the order has been finalized.

[B] System events list – list of hooks that send PURCHASE events to SALESmanago.

Detailed descriptions of the hooks can be found further in the article.

IMPORTANT: Some Hooks only work in certain situations (e.g., when a store admin modifies an order invoice).

NOTE: Due to the specificity of Magento 2, the default configuration may not work properly, i.e. events will not be sent to SALESmanago. In that case, use the System event option and select the hook manually.

[7] Monitoring Code features – configure the Monitoring Code settings.

[A] Disable Monitoring Code – check if you do not want the module to add the Monitoring Code to your website automatically. This option is useful when the script loading order causes technical problems or when you do not want contacts to be monitored on all pages.

IMPORTANT: If you decide to disable the Monitoring Code, be sure to add it manually, e.g., in template files.

[B] Custom JS – check “Yes” if you want to add the _smcustom flag to the Monitoring Code, which allows you to include JavaScript code from SALESmanago.

[C] Banners – check “Yes” if you want to add the _smbanners flag to the Monitoring Code. It allows you to display personalized banners created in SALESmanago on the website.

[8] Cookies features – set the option for cookies.

[A] Cookies life time – specify (in days) the lifetime of the smclient cookie. The default period is 3652 days (10 years). Choose a number between 1–8760.

D. Data export

From the moment you install the plugin, contacts and events will be sent to SALESmanago automatically. To export the data from before the module installation, go to the plugin configuration panel (you can click the SALESmanago icon on the side menu) and select the Export Data tab.

In this screen, you can set the export of contacts and events from your Magento 2 store to SALESmanago.

Before you start exporting, there are three things to note:

  1. You can export contacts multiple times, i.e. the contact data will be updated in SALESmanago during each transfer.
  2. You should export contacts before exporting external events. Make sure your contacts are in the SALESmanago database before transferring orders.
  3. You should export external events only once, otherwise the data sent to SALESmanago will be duplicated.

IMPORTANT: If you export from the Scope: All Store Views, the data from each store will be sent to the SALESmanago account that you are logged in at a given time.

[1] Export contacts – click to export contacts. This type of export includes three groups of contacts:

  • Registered users who have an account in your store (customers).
  • Users who purchased as a guest (without registration).
  • Users who subscribed to the Magento newsletter (subscribers).

IMPORTANT: Email addresses can duplicate within these three groups, e.g., when the email address of a registered contact is used before creating an account to make purchases as a guest, or to subscribe to the newsletter. Data of users belonging to more than one group will be merged in SALESmanago.

[A] Start/end date – set the date range for the export. You can use this option to export both contacts and events.

[B] Export tag – enter the tags that will be assigned to the contacts following the export to SALESmanago. Separate them using commas with no spaces.

[2] Export event – click to export PURCHASE events. By default, this type of export includes orders with the status Closed, Complete, and Pending. You can select the desired statuses from the list [C].

[C] Additional configuration for events export – this option will allow you to manually select the status of orders sent to SALESmanago as PURCHASE events. You can choose the statuses from those available on the list or enter your own names, separating them with commas.

[3] Export Quotes as CART – click to export Quote events as CART events. They only relate to users who have an account in your Magento store.

5. Technical description

A. Database

The same mechanism that is used by the Magento 2 platform is used to store the plugin configuration data. Apart from this type of data, SALESmanago does not use the Magento 2 database.

B. Hooks

The SALESmanago plugin uses hooks from the Magento 2 system:

  • customer_login – runs when a contact logs in. It allows you to send contact data to SALESmanago.
  • customer_register_success – runs during registration. It allows you to send contact data to SALESmanago.
  • customer_account_edited – runs when data are edited from the customer panel. It allows you to send contact details to SALESmanago.
  • newsletter_subscriber_save_after – runs when a user has subscribed to the newsletter (usually by using a link from the footer or selecting a checkbox in the registration form). It allows you to send contact data and opt-in status to SALESmanago.
  • customer_address_save_commit_after – runs when data are edited from the customer panel (the addresses tab). It allows you to send contact data (email address) to SALESmanago.
  • customer_address_save_after – runs when data are edited from the customer panel (the addresses tab). It allows you to send contact details (postal address) to SALESmanago,
  • checkout_cart_save_after – runs when the cart is saved. It allows you to send CART events to SALESmanago and update them.
  • adminhtml_customer_save_after – runs when customer data are saved (when creating or editing an account) in the Magento 2 admin panel.
  • checkout_onepage_controller_success_action – runs during the order finalization. It allows you to send PURCHASE events to SALESmanago (this is the “Default” option from the list of system events).
  • multishipping_checkout_controller_success_action – runs during finalization of the order with the multishipping option enabled (and selected by the user), i.e., sending one purchase to different postal addresses. It allows you to send PURCHASE events to SALESmanago.
  • checkout_submit_all_after – runs as the last hook during the order finalization. It allows you to send PURCHASE events to SALESmanago (this is the “After all system event” option from the list of system events).

Hooks sending PURCHASE events to choose from:

  • restore_quote.
  • sales_convert_order_to_quote.
  • sales_order_invoice_register.
  • _set_sales_order.
  • checkout_type_onepage_save_order_after.
  • checkout_type_multishipping_create_orders_single – runs when the multishipping option is enabled and selected by the user.
  • paypal_express_place_order_success – runs when choosing the option to pay by PayPal (requires the Magento 2 integration with PayPal).
  • sales_convert_quote_to_order – starts when the cart is converted into an order.

Hook of the SALESmanago integration module:

  • sm_pwa_cart_interceptor – runs when adding to or modifying the cart using graphQl (when using the Progressive Web App method).

Each hook that sends contact data uses the smclient cookie, which is necessary for the proper functioning of the Monitoring Code.

All hooks that send PURCHASE events also send contact data. Hooks that send CART events do not transmit contact data.

C. Monitoring Code

The Monitoring Code is added to the source code of the website only in the case of a standard Magento 2 installation. In the case of the Progressive Web App method, the code should be added by the client’s developer.

If you need more information about the topic mentioned above, please contact us: support@salesmanago.com +1 800 960 0640