Skip to main content

Voyado Engage

Integrating with Voyado Elevate

Engage contains a standardized integration to its product discovery suite, Elevate (formerly known as eSales). When connecting the two systems, we encourage you to read and follow these instructions.

There are two considerations in a successful integration:

  • Identifying a customer across both systems (via contactId and customerKey)

  • Linking an article's SKU in Engage with the variantKey in the Elevate product feed

Identification of customers

Engage and Elevate both identify the contact/customer by a unique alphanumeric identifier, a GUID/UUID(4), that looks something like this: 5c9b35d6-28d8-4520-8900-a89600f7f0c5.

In Engage this is known as the contactId.

In Elevate it’s called the customerKey

To link a contact across both platforms, the contactIdin Engage and customerKey in Elevate must be connected. This linking requires that the discoveryKeycontact attribute is included in the Engage Auto-login data and that its value is used as the customerKey in Elevate.

Inclusion of the discoveryKey is enabled in the Module settings in the Engage Tenant configuration by selecting "Include Discovery key in autologin data". Reach out to your Voyado Engage product specialist or the technical expert team for the Elevate product if you have any questions about this.

Note: A previously used workaround for integrating Elevate with Engage was the use of a custom contact attribute for Engage contacts (usually referred to as the “apptusId”) to store the Elevate customerKey. This method of integrating the products should be seen as deprecated.

Customer identification by discoveryKey

Any integrations between Engage and Elevate dated after 2022-06 must use the the discoveryKey contact attribute in Engage to be considered legitimate. Even if the value of the contactId attribute in Engage is the exact same as the customerKey value in Elevate (one-to-one) it is still important to set the discoveryKeyattribute to the same value as the customerKey in Elevate.

Note: Any future features making use of the discoveryKey attribute will not be supported by integrations done before discoveryKey existed as a custom contact attribute.

The discoveryKey is now an integral part of the Engage soft login (previously called auto login). It has to be activated in the settings of the “Auto login” module in order to appear in the decrypted soft login object.

The soft login is an encrypted query string parameter named eclub, which holds information about the contact/customer who has clicked a link (such as an URL in an email campaign).

The target site backend can listen for this query parameter and decrypt it. The decryption of the soft login should never be done on the client side for security reasons and GDPR concerns. The encryption key property in the module settings should also never be shared or made accessible in client implementations.

A soft (auto) login URL might look like this:

https://ourdemostore.com/?vtid=9cle0_ctRE25K6kMABznMg&eclub=FwoE65oCjhuc70IBFnszvhZJ0R37pdOYIy0x3KYzsbj3kWtwP2ByD2KP4kuRvWtx7JlyrJpaYnIvI4yAnDbFcVfMJDsXW24MgIrDyqoSw09_7KIMxGri8dYkIhW7FdFFm98n4Vq87I77mA9EsBWI6ExC_MQQkHHqa0h-7pmicZtpQMl7-WJOZCsVV0aEU6E6EX7REldFBFGfHpoWw5fukAaK7nJcg68j_f1OlBgHnwM

The result of the server-side decryption will be an object with the following properties, containing the discoveryKey which is the identification key (customerKey) used in interactions with Elevate.

{
    "id": "60333",
    "email": "withnail@voyado.com",
    "contactId": "d35ec9f5-2df7-4d44-b92b-a90c001ce732",
    "dateTime": "2022-05-11T13:15:40Z",
    "discoveryKey": "0b05119e-eeb8-418a-bbfb-defa0dde417e"
}

Reminder, make sure the discoveryKey property is activated in the Voyado Engage configuration area (your implementation specialist at Voyado can help you here).

A customer website using both Engage and Elevate needs to decrypt the soft login and further apply the discoveryKey value as the customerKey when calls to Elevate are made (e.g. through an email campaign URL). The customer identification in both software suites is now linked, and the flow of information is kept intact. The customer website can also detect if the contact has never been active in any Elevate session. An empty or nonexistent discoveryKey would be an indicator of this.

Identification of products/articles

Elevate unleashes powerful features, but to utilize them, both Engage and Elevate must be able to identify the stock keeping unit (SKU) code of a purchasable item.

In Engage the SKU is a standard article property. Elevate, however, refers to articles as products, and the variations of the products as variants. Each product and variant has a unique key in Elevate. An Elevate variant must have a variantKey value corresponding to the article SKU in Engage.

Tracking events -- product views, product clicks, purchases, adding to favorites -- use the SKU/variantKey to share valuable customer interactions. To be able to exchange such data between Engage and Elevate, both systems need to be able to identify the product code (SKU/variantKey). That’s also the case for purchase data in a receipt for brick and mortar store. The receipt will contain the SKU and/or EAN code.

Here is an example of an Engage productview tracking event:

{
    "t": "productview",
    "i": "art-321-1123",
    "ca": "WOMEN > SHIRTS > Coco ",
    "ci": null,
    "ti": "2022-05-20T18:08:58.926Z",
    "te": "coco",
    "id": "VA507.2050216525",
    "s": "VA507.1012665165",
    "ns": false,
    "ua": "Mozilla/5.0",
    "l": "en-us",
    "re": "https://test.com/en/coco",
    "url": "https://test.com/sv/women/shirts/coco"
}

And this is an example of an Elevate purchase (order) event payload:

{
  "lines": [
    {
      "variantKey": "art-321-1123",
      "quantity": 1,
      "sellingPrice": 60
    }
  ]
}

An AI/ML module will be able to recognize the article with art-321-1123 in both suites and realize it is the same one. Each system can relate to the article if they both use the same SKU / variantKey.