Skip to main content

Configuring the extension

When the extension has been successfully installed, you can start configuring it.

Enabling the extension

In Magento admin, navigate to Stores > Configuration > Integrations and select the "Voyado" tab.

Inside this configuration space, you'll be able to enable or disable the functionality supported by the extension.

Start by enabling the extension under “General” settings as seen in the video below.

Websites

You can connect your Voyado Engage environment/s to all your websites.

In the top left corner, change the website under “Scope”. You can choose to have a default setup for all websites, connected to one Voyado Engage environment (recommended), or configure websites separately, connecting each one to a separate instance.

Establish your connection settings

Next, you'll need to input the credentials for your Engage environment.

  1. Base URL: Input the Base URL of your Engage environment (For example: https://tenantid.staging.voyado.com).

  2. API key: Input your Engage API key (for example: 00000000-0000-0000-0000-000000000000).

  3. Source: Input the source of contact registration to use as a filter when triggering marketing automation acquisition journeys in Engage. (Example: ecom-eu).

  4. StoreExternalId: Input the external ID of the Engage store that you want to connect your customers and orders to.

Configure the contact sync

This integration with Engage supports the sync of customers, guests and newsletter subscribers. These different types of customers are each stored in Voyado Engage as separate contact types.

Caution

All contact types must be created in Engage by the Voyado team before contact exports are enabled.

To allow syncing of the Customer entity in Magento you will have to:

  1. Enable the customer export, found under Export > Enable customer export.

  2. Go to the “Customer Specific Settings” section and enable “Create Voyado contact as member”.

If you want to sync your guest customers and store them in Engage, follow these steps:

  1. Enable the customer export which can be found under Export > Enable customer export.

  2. Go to the “Customer Specific Settings” section and enable Create Voyado contact also from Guest Customer.

If you want to store your newsletter subscriptions in Engage:

  1. Enable the newsletter subscriber export under Export > Enable newsletter subscriber export.

Sync all contacts to Engage as type "Member"

With this setting you can choose to save ALL contacts - customers, guests and newsletter subscribers - as contact type "Member" in Engage.

magento_config_all_member.png

The benefit of doing this is to minimize confusion and make for a cleaner integration. By only having the contact type "Member" it also means fewer calls to the Engage API. Voyado recommends this approach.

Arguably, using three different contact types might be useful if you want to separate different customers from each other in Engage. If you have a loyalty program, for example, and want that only account holders should be part of it, then it might be easier to have three types. However, this can also be done by making every customer have the contact type Member and using a HasAccount consent to tell them apart.

Phone number validation

Voyado Engage requires a phone number to have a country calling code. If no validation for this is done in the front-end, and a phone number without a country calling code is input in checkout, the extension will validate that phone number based on the code of the country chosen in checkout.

For example:

  • A customer chooses country “Sweden” and gives the phone number “0701234567” in checkout.

  • The extension validates to check if the number is a valid Swedish number.

  • If it is, we add a country calling code and format the number to “+46701234567” before we send it to Engage.

  • If not, we just exclude the phone number from the request sent to Engage.

Enable Engage to update customers in Magento 2

In the configuration area you have the option of activating a two-way sync, allowing Engage to update customers in Magento 2. The two-way sync is connected to the login event in Magento 2, meaning that data is fetched from Engage and used to update the customer whenever they login to their account.

You can sync any or all of the name and address data or the newsletter subscription flag from Engage.

Note

Two-way sync is only applicable if you have the “Require Email Confirmation” setting enabled in Magento 2. This can be found in Stores > Configuration > Customer Configuration.

Tip

Voyado recommends that you at least enable the “Sync newsletter subscription” setting connected to the two-way sync. This is so that both platforms are in sync and so that there is no mismatch in the newsletter subscription field.

Follow these steps to enable to two-way sync:

  1. Enable the “Sync after login” setting which can be found under Customer specific settings > Sync after login.

  2. Enable “Sync name and address” if you want Engage to update this information in Magento 2.

  3. Enable “Sync newsletter subscription” if you want Engage to update this information in Magento 2 (recommended).

Contact data model

Here are the fields in the contact model:

Contact:

First name

Last name

Street

City

Zip code

Country code

Gender

Recruited in store (the store at which the contact signed up)

Preferences:

Accepts email marketing

Note

The contact data model can be extended by developing a custom patch.

Configure syncing of purchases and returns

To sync purchases (called invoices in Magento) and returns (called credit memos in Magento) you must enable two separate exports. Activating these will allow you to create segments based on the contact's order history in Voyado Engage.

You can enable the invoice export at Export > Enable invoice export.

You can enable the credit memo export at Export > Enable credit memo export.

magento3.png

Warning

The order will only be stored for segmentation in Engage after it has been set to "invoiced" in Magento Admin.

{
    "contact": {
        "contactType": "member",
        "matchKey": "f0352103-7143-4a44-a20d-af3300c58d7f",
        "matchKeyType": "ContactId"
    },
    "createdDate": "2022-11-08T12:49:43+00:00",
    "createdDateForXml": "2022-11-08T12:49:43+00:00",
    "currency": "EUR",
    "items": [
        {
            "articleName": "Joust Duffle Bag",
            "articleNumber": "24-MB01",
            "awardsBonus": true,
            "extraData": [],
            "grossPaidPrice": 85,
            "quantity": 2,
            "sku": "24-MB01",
            "taxAmount": "17.0000",
            "taxPercent": "25.0000",
            "type": "PURCHASE"
        }
    ],
    "paymentMethods": [
        {
            "description": "Payment for: 000000034",
            "type": "checkmo",
            "value": 85
        }
    ],
    "receiptNumber": "000000034",
    "storeExternalId": "opensource_demostore",
    "taxDetails": {
        "description": "TAX",
        "percent": "25.0000",
        "totalExcludingTax": 68,
        "totalIncludingTax": 85,
        "value": "19.5000"
    },
    "totalGrossPrice": 85,
    "uniqueReceiptId": "000000034"
}
{
    "contact": {
        "contactType": "member",
        "matchKey": "f0352103-7143-4a44-a20d-af3300c58d7f",
        "matchKeyType": "ContactId"
    },
    "createdDate": "2022-11-08T12:49:43+00:00",
    "createdDateForXml": "2022-11-08T12:49:43+00:00",
    "currency": "EUR",
    "items": [
        {
            "articleName": "Joust Duffle Bag",
            "articleNumber": "24-MB01",
            "awardsBonus": true,
            "extraData": [],
            "grossPaidPrice": 42.5,
            "quantity": -1,
            "sku": "24-MB01",
            "taxAmount": "8.5000",
            "taxPercent": "25.0000",
            "type": "RETURN"
        }
    ],
    "paymentMethods": [
        {
            "description": "Refund payment for: 000000034",
            "type": "Refund",
            "value": -42.5
        }
    ],
    "receiptNumber": "000000034",
    "storeExternalId": "opensource_demostore",
    "taxDetails": {
        "description": "TAX",
        "totalExcludingTax": 34,
        "totalIncludingTax": 42.5,
        "value": "8.5000"
    },
    "totalGrossPrice": -42.5,
    "uniqueReceiptId": "34-20"
}

Configure transactional emails

If you enable the order export in the configuration area, you can choose to trigger transactional communication via Engage which will streamline the graphic design of your emails, whether they are transactional or marketing emails.

Navigate to Export > Enable order export to activate the export.

The following order states are supported “out of the box” by the extension:

  • Order confirmation email

  • Order shipped email

  • Order cancelled email

  • Order returned email

Caution

If you want to trigger “Order returned email”, you must enable the credit memo export (see the previous section).

Each order status can be individually enable and disabled.

Magento4.png

The statuses in default Magento 2 implementation works like this:

  1. Status “Pending” connects to an “Order confirmed” event.

  2. Status “Processing” connects to an “Order shipped” event.

  3. Status “Complete” connects to an "Order invoiced” event.

  4. Status “Canceled” connects to an “Order canceled” event.

  5. Credit memo connects to a “Order returned” event.

Note

Your Magento 2 implementation might trigger these events differently, which means the statuses above might not be relevant for your setup. For example, in some cases a confirmed order sets the initial order state to “Processing” instead of “Pending”, meaning you don’t have to activate the Pending state in the configuration area.

Order data model

Below are the "out of the box" data points included in transactional emails: 

Contact:

MatchKey (contactId)

MatchKeyType (GUID)

Order header:

Currency

Created date

Freight fee

Freight fee VAT

Language

Order number

Order status

Payment methods

Shipping method

Payment status 

Total discounts 

Total gross price

Total VAT

Total original price

Total net price

Total items price

Total discounts

Customer information

First name

Last name

Middle name

Phone

Billing city

Billing country

Billing company

Billing street

Billing zip code

Shipping first name

Shipping last name

Shipping middle name

Shipping phone

Shipping city

Shipping company

Shipping country

Shipping street

Shipping zip code

Order items:

Description

Price

Quantity

SKU

Image URL

Image target URL

VAT amount

VAT percent

Type (PURCHASE or RETURN)

Note

If you want to extend the order payload with the additional product attributes in Magento, follow the instructions in the README.md file in Gitlab under the section "Extending". If you don't have access to the file on Gitlab, try this article.

Shipment settings

Add the Magento tracking URL at Shipment settings > Add the Magento tracking URL also shown in the admin.

Setting this to “Yes” will add the default tracking link provided by Magento 2 which is available in admin.

magento-shipment-settings-yes.png

Setting this option to “No” will allow you to add your transporter's tracking URL. When the transactional email is sent, the first tracking number found will be added to the URL and sent in the payload.

magento-shipment-settings-no.png

Soft identification

When you send a newsletter or email with a link to your customers in Engage, the links are encrypted with a contact identifier (contactId). This functionality can be used for various actions, such as triggering abandoned carts or product views through Engage's tracking script, or to personalize the experience on-site since Engage lets Magento know who the visitor is.

To enable soft identification:

  1. Navigate to Soft Login > Enable and select “Yes”.

  2. Input your decryption key.

Note

The Decryption Key, 32 characters long, is configured in the Engage back-office. AES is the encryption method used. Ask your Voyado team about this.

When the customer arrives on-site via a soft identification link, the extension decrypts it, identifying the customer. When this setting is enabled, the extension then automatically pushes the contact identifier to dataLayer.

If you set the “Display in front-end” setting to "yes", it aids debugging by showing the response payload in the storefront.

Caution

Soft identification only facilitates web-activity tracking and personalization on-site. It is not something that is supported out-of-the-box, since it is tightly coupled to front-end components.

Web activity tracking (BETA)

Enabling this feature in the extension will allow you to act on cart abandonment and abandoned browse (beta). Engage will also calculate and store the ten top products of interest which can be used in segmentation as well as when generating content in emails.

Caution

Web activity tracking is only applicable if using the Adobe Commerce native front-end. If you are running a headless front-end then you'll need to implement this yourself. Go here for more details.

This is a beta release and it's important to keep the following in mind:

  • The feature is in its initial phase, and we are actively seeking user feedback to improve its performance and functionality. We appreciate your support in this process.

  • As a BETA feature, it may undergo frequent updates and enhancements. We encourage you to check for updates regularly to take advantage of the latest improvements.

  • While we have conducted rigorous testing, BETA releases may still contain unexpected issues, bugs, or glitches. Please be prepared for occasional disruptions, and report any issues you encounter to help us refine the feature.

The prerequisites for using web activity tracking are the following:

  • Adobe Commerce native front-end

  • The Voyado/magento2 project version 4.2.0

  • Web activity tracking enabled in Voyado Engage (talk to your Voyado account manager)

Follow these steps to enable web activity tracking:

  1. In the Magento config area, scroll down to the bottom of the page.

  2. Select the "Enable" drop-down and choose the option "Yes".

  3. Input the "Script path" which depends on your environment:

    • In production: https://assets.voyado.com/jsfiles/analytics_0.1.7.min.js

    • In staging: https://assets.voyado.com/jsfiles/analytics_0.1.7.staging.min.js

  4. Input the tenant ID of your Voyado Engage environment.

    Tip

    This string is your unique client (tenant) ID and is the same in production and staging. It is usually the subdomain name in *.voyado.com. For instance, the [TENANT-ID] for "supershop.voyado.com" would be "supershop".Contact your Voyado team if you are unsure about this.

  5. Enable "Product" tracking

  6. Enable "Cart" tracking

  7. Select "Save Config" in the top right corner of the page.

  8. Go to System and then Cache Management in the left menu and refresh "Configuration" and "Page cache".

Here is a video showing the configuration: