Integration with PrestaShop 1.7

PrestaShop is a popular eCommerce platform that allows you to sell online. By integrating it with our system, you can send important data from PrestaShop to SALESmanago. It will be used to automate marketing activities and, in turn, boost sales in your e-shop.

To download the plugin, click here.


Contents

1. Basic information
2. Scope of integration

3. Installation
4. Configuration
5. Technical description
6. Information for developers


1. Basic information

In the article, you will find detailed information about integration with the PrestaShop 1.7 platform. SALESmanago has created a plugin for this purpose. In addition, it is under constant development to match the latest versions of the PrestaShop platform. This plugin also supports multistore, a native tool of the PrestaShop platform.

The integration allows you to track events in the SALESmanago system (such as adding to a cart or a purchase) from all of your stores operating within the multistore. Automatic location detail assignment makes it easier and more convenient to analyze and use these data.

If you are using an older version of PrestaShop, please go to the PrestaShop 1.6 integration article>>


2. Scope of integration

Synchronization and data transfer are performed automatically. The scope of integration includes sending data from the store to SALESmanago:

  • Contacts gained during registration and purchase;
  • Events: CART, PURCHASE;
  • Newsletter subscription status (opt-in, opt-out);
  • Previous actions (archival customer and order data).

Additionally, the following information can be sent from SALESmanago to the store, if desired:

  • Newsletter subscription status (opt-in, opt-out).

3. Installation

Before starting the installation, download the plugin >>

After downloading the plugin, log in to the panel of your PrestaShop store and go to the Module Manager in the side menu:IMPROVE Modules Module manager.

On the next screen, click Upload a module and send the previously downloaded file. If this is successful, the following message should appear:

Proceed by clicking Configure.

In case of problems with the plugin (unable to log in, incorrect integration), return to the previous page and reset the module by clicking Yes, reset it on the pop-up to restore the settings.

Thanks to this, you do not have to reinstall the plugin. You can proceed with the configuration with the initial settings.


4. Configuration

After launching the plugin, you will see a login screen. Enter the data you use when logging into SALESmanago. On the same login screen, you will also find the option to modify the endpoint. If your SALESmanago account is on a different (custom) endpoint, check I want to modify my endpoint.

IMPORTANT: Endpoint is the address where the SALESmanago application is located. Do not add “http://”, “https://”, or a trailing slash (/) to the endpoint address.

NOTE: You will not be able to log in if you are using Two Factor Authentication (2FA). However, this is due to the specificity of this method. Contact Customer Success for more information.


IMPORTANT: If you use multistore, you must integrate each store separately. As a result, information about logging in to a specific store will appear later, as needed. You can navigate between stores in the top menu bar in PrestaShop.

After connecting to the SALESmanago system and completing the authentication process, the integration will become active (contacts and events start sending automatically to SALESmanago). The main screen after logging in is the Dashboard. Here, you will find information about the latest updates, as well as a brief description of the plugin’s operation. In the upper right corner, there is also the Deactivate button, which allows you to turn off the integration. Deactivating the integration will stop sending contacts and events from PrestaShop to SALESmanago.

To change the standard configuration, go to the side menu, where you will find all the integration settings. In the SALESMANAGO category, you can find Account Settings, Platform Settings, and Export.

A. Account Settings

On this page, you will find the integration settings related to your SALESmanago account.

Here, you can find basic values ready to copy: Opt-in callback URL, Opt-out callback URL, Client ID (this is taken from the SALESmanago database), Endpoint, and Shop ID. You can modify the other options as needed.

IMPORTANT: Callback URLs should be pasted into the SALESmanago system (Settings Other Application). These settings allow you to synchronize opt-in/out statuses from SALESmanago to PrestaShop, e.g., when a contact unsubscribes from the newsletter via a link in the footer of the email.

[1] Client email – select an email address from the drop-down list. You can select all the email addresses that are available and configured within the SALESmanago system by having the role of owner, i.e., contact owner.

IMPORTANT: If the email you are searching for is not on the drop-down list, press the refresh button. It will synchronize the current list of contact owners from SALESmanago.

[2] When registering a user, download the consent status from SALESmanago – choose “YES” if you want to check whether the contacts who registered on your platform can already be found in the SALESmanago database. When a contact exists in the database with opt-in status but while registration does not give consent, in both the SALESmanago system and the PrestaShop platform the contact has opt-in status.

[3] Use Double Opt-in when a user subscribes to the newsletter – choose “YES” if you want those who subscribed to the newsletter and have gone through the two-step validation process. This action is in line with the best practices of consent-based marketing, and at the same time, increases the chances of high deliverability, openness, and conversion rates in the indicated channel.

Learn more about user confirmation>>

After making the changes, click Save.

B. Platform settings

On this page, you will find the integration settings related to the PrestaShop platform.

[1] Configure PURCHASEexternal event on your platform

  • Select method:
    • hooks – is a mechanism in many eCommerce platforms that allows you to launch a certain action at a specific moment. In the case of the SALESmanago plugin, this can be, for example, sending a contact to SALESmanago. To ensure correct operation with various payment mechanisms and methods of order fulfillments, our plugin allows you to select the hook that is responsible for the purchase event;
    • other – if you choose this method, information about the purchase will be sent to SALESmanago only after you reload the website following the purchase.
  • Select event:
    • actionValidateOrder,
    • actionOrderStatusPostUpdate,
    • actionPaymentConfirmation,
    • displayOrderConfirmation,
    • actionOrderStatusUpdate.

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

[2] Product ID – this will require you to define the form in which the product identifier will be sent in external events. You can choose from a single variable or a set of variables linked with a custom string. Note the options that appear in both cases:

  • ID – product identifier created within your store;
  • Reference – the trade identifier of the products, i.e., the SKU code.

With your own settings, you can also choose which character will separate both values: “”, “_” or “&”.

[3] Choose how long the CART event will be updated – from the drop-down list, select the time after which the CART event will no longer be updated and what will create a new CART event. In many cases, this will involve customers adding and removing products from the cart. This option allows you to set whether such changes create a new CART event or update a previous one. If you select a specific time from the list, the cart events will be updated in the indicated period, and subsequent changes to the cart will create a new event in SALESmanago:

  • never (CART event will be constantly updated),
  • 3h,
  • 12h (default),
  • 1 day,
  • 2 days,
  • 3 days,
  • 1 week,
  • 1 month,
  • always (each CART event will be assigned to the SALESmanago database as a separate external event).

EXAMPLES: If you want SALESmanago to include only the last cart, select “never”. If you want a new CART event to be created for a customer who changes the contents of the cart after a few days, select the appropriate time, e.g., “3 days”. If you want SALESmanago to save the entire history of the cart (each addition, removal, or change in the number of products), select “always”.

[4] Ignored email domains – you can enter a list of domains (for email addresses), which will not be added to SALESmanago. In particular, you can enter the domains of temporary mail and intermediate mail, such as allegromail.pl.

IMPORTANT: Separate domains with commas, without spaces (e.g., domena.pl,gmail.com).

[5] Set tags that will be assigned to contacts sent to SALESmanago – this setting applies to registration, newsletter, purchase, and guest purchase tags.

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

[6] Cookie lifetime – specify (in days) the lifetime of the smclient cookie. The default period is 3652 days (10 years).

C. Monitoring code

[1] Disable monitoring code – select “YES” if you want the module not to automatically add the monitoring code to your website. In this case, you would need to add the monitoring code yourself in the platform code (e.g., in the footer).

[2] Add ‘smcustom’ flag to your monitoring code – select “YES” if you want the _smcustom variable with true value to be added to the monitoring code, which allows you to use custom scripts written in the SALESmanago application.

[3] Add ‘smbanners’ flag to your monitoring code – check “YES” if you want to add the _smbanners variable with true value to the monitoring code, which allows the use of the script for banners.

IMPORTANT: selecting “YES” in [1] will make it impossible to change the other two options in the module settings. You must configure them manually in the monitoring code.

[4] Currently used monitoring code – a preview of the current monitoring code on your platform.

After making the changes, click Save.

D. Export

This option allows you to export contacts and events from your PrestaShop store to SALESmanago. Before you start any operation, you should know that contacts can be transferred several times, i.e., the contacts data will be updated in the system database with each export order. It is different from events because re-exporting them is associated with the duplication of data. This means that if you export external events a second time, all purchases will have gone to SALESmanago twice.

[1] Contacts to SALESmanago

It is worth knowing that contacts are sent in “packages” of 400 contacts. The more contacts you have on your platform, the greater the chance of overloading the server while exporting. To successfully complete this operation, use the time range contact filter in the advanced settings.

[A] Time range – set the time range that will be taken into account when exporting contacts. By clicking the Count button, you can see how many contacts will be included after applying this filter. This makes it easier to plan the entire data transfer process.

[B] Add tags to exported contacts – enter the tags that will be assigned to the contacts after the export to SALESmanago. Separate them using commas with no spaces.

[C] Export deleted contacts – you can decide whether you want to also transfer those contacts that were previously deleted but remained in the database. Detailed information on this option can be found further in the article.

When you set the appropriate parameters, click Export.

[2] Events to SALESmanago

As in the contacts export, it is worth keeping in mind that events are sent in “packages” of 400 contacts. The more events you have on your platform, the greater the chance of overloading the server while exporting.

After going to the advanced settings, you will find a field for setting the time range (similar to exporting contacts). By clicking the Count button, you can see how many events are included after applying this filter, which will make it easier to plan the entire data transfer process.

IMPORTANT: During export, only purchases with the statuses “Payment approved” and “Delivered” are transferred.

When you have set the appropriate parameters, click Export.

IMPORTANT: Remember that when exporting events a second time, they will have gone to the SALESmanago system twice.

E. Exports archive

The export archive is stored in the database (max. 10 records); if you exceed this number, the oldest record will be deleted and replaced with the new one.

In the archive, you can find the following information:

  • [1] # – identifier of the export action, which is a unique value (example: 4 means that it is the fourth export in the history);
  • [2] Type – specifying the type of export: contacts or events;
  • [3] Date – date of the export execution;
  • [4] Amount – the number of Contacts/Events that were transferred in the export action;
  • [5] Date range – time range from which the data was downloaded and sent to SALESmanago;
  • [6] Packages – takes the X/Y format; determines the number of correctly exported packages in a given export action (X value) and the number of all packages from a given export action (Y value);
  • [7] Status – final status of the export action;
  • [8] Action – if you want to delete data related to a specific export from the archive, click the trash can icon.

5. Technical description

Sending method

A delivery method has been added to the PURCHASE event as detail7. Using this PrestaShop method, the carrier’s ID is retrieved from the cart and a carrier’s name is assigned to the detail7 based on this ID.

Export

In PrestaShop, a contact can have more than one sending address assigned to an account. This is because the platform allows you to add more than one address. When ordering, the customer selects the correct address from the list. Only the default account address is sent to the SALESmanago database.

If the data export is unsuccessful, the progress bar stops, and you will see a red alert in the upper right corner stating the error.

More information on the export status can be found in the console (you can access it with the Ctrl+Shift+I keyboard shortcut) and in the Network tab by selecting the appropriate request. In case of issues, contact our Customer Success department.

Abandoned Export

If an error occurs while exporting, you will see the following message after refreshing the page:

In such a situation, the SALESmanago system will receive those packages that were sent before the error occurred. However, you can resume the export to transfer the rest of the data.

Translations

By default, the module translations include PL and ENG language versions. To translate the module into another language, use the native PrestaShop “translations” tool. Select the module translation option, choose the SALESmanago module, and then translate the blanks as needed.

Purchase hooks settings

Hooks selected in the module settings are responsible for the moment the PURCHASE event is sent:

  • actionValidateOrder (classes/PaymentModule.php:535) – runs when the order has successfully passed the validation stage;
  • actionOrderStatusPostUpdate (classes/order/OrderHistory.php:411) – runs after order status changes.

IMPORTANT: The second hook is run BEFORE the new order status is sent to the database.

  • actionPaymentConfirmation (classes/order/OrderHistory.php:103) – runs when the payment has successfully passed the validation stage;
  • actionOrderStatusUpdate (classes/order/OrderHistory.php:107) – runs after order status changes;

actionPaymentConfirmation – runs when the completed order summary is displayed.


6. Information for developers

Recommended PHP version on the server: 7.1–7.4

Set the version of the PHP interpreter depending on the version of the PrestaShop platform you use:

  • PrestaShop 1.7.0–1.7.4.X PHP 7.1;
  • PrestaShop 1.7.5–1.7.6.X PHP 7.2;
  • PrestaShop 1.7.7.X PHP 7.3;
  • PrestaShop 1.7.8.X PHP 7.4.


Tips on modifying the plugin

When removing a user from the shop platform panel, you have two options:

  • Remove all customer data from the database, which allows re-registration with this email address;
  • Remove the customer only from the list of customers in the store’s panel, while leaving the corresponding data in the PrestaShop database, which means that it will not be possible to re-register with this email address.

Hooks using

The newsletter subscription in PrestaShop 1.7.0–1.7.6.X versions is assigned to hook displayFooter, and in 1.7.7 and newer versions – actionNewsletterRegistrationAfter.

IMPORTANT: The actionNewsletterRegistrationAfter hook from the native PrestaShop module and is available from the ps_emailsubscription version 2.6.0.

If you use PrestaShop version 1.7.7 and newer, the native ps_emailsubscription module must be enabled in version 2.6.0 or higher.

During client registration, the ActionObjectCustomerAddBefore hook is run.

List of used hooks:

  • moduleRoutes,
  • displayFooter,
  • actionCartSave,
  • backOfficeHeader,
  • actionAuthentication,
  • actionObjectAddressAddAfter,
  • actionObjectAddressUpdateAfter,
  • actionObjectCustomerAddBefore,
  • actionObjectCustomerAddAfter,
  • actionObjectCustomerUpdateBefore,
  • actionObjectCustomerAddressAddAfter,
  • actionObjectCustomerAddressUpdateAfter,
  • actionValidateOrder,
  • actionOrderStatusPostUpdate,
  • actionPaymentConfirmation,
  • displayOrderConfirmation,
  • actionOrderStatusUpdate,
  • actionNewsletterRegistrationAfter,
  • displayBeforeBodyClosingTag.


Database

When installing the module in the PrestaShop database, the ps_sm_subscribers table is created (in some cases, the prefix may be different than “ps”). Adding this table resolves the following problem:

EXAMPLE: The contact subscribes to the newsletter (via the form in the footer), and prefix_emailsubscription is added to the table. When they make a purchase and want to create an account for the same email, PrestaShop removes it from the table (prefix)_emailsubscription. If they do not select the newsletter on the registration form, it is sent to the database (prefix)_customers as an opt-out. In SALESmanago – thanks to new API methods – it is still listed as opt-in (they did not unsubscribe explicitly, but they did not select the checkbox). If such contact would like to edit their data, in the account editing tab, the checkbox with the newsletter will be deselected because the contact in the store is listed as opt-out (they did not select the checkbox on the registration form). After sending such a form, the contact will be opted out in the SALESmanago database.

To avoid this, when registering a contact on checkout, the module checks whether a particular email is in the table (prefix)_emailsubscription. If so, its data is saved in a new temporary table (prefix)_sm_subscribers.

If a contact edits their account details, it will be checked whether they already appear in this table. If so, the module downloads the contact status and overwrites the newsletter status taken from the form with it. If they do not appear and have not subscribed to the newsletter, they will be considered an opt-out in the SALESmanago system.

The second table added to the database is the ps_sm_archive_export table (in some cases, the prefix may be different than “ps”) and stores data related to historical exports. More about them can be found in the section “Abandoned export”.

If these tips prove insufficient, please contact our Customer Success department. Our developers will be happy to help you modify the plugin and solve any problems.

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