Engage and Elevate

Voyado Elevate is a powerful search and merchandising solution, tailor-made for online shopping. Elevate gives retailers advanced merchandising capabilities while delivering a fast, relevant, and seamless experience for end customers.

Clients running both Elevate and Engage unlock a set of connected features where the two products work together in ways that aren’t possible on their own. This integration is powered by shared identification, contact data, and behavioral signals, enabling smarter personalization across channels. Examples include:

• Connected recommendations – Elevate generates dynamic product recommendations that can be used directly in Engage’s Design Studio.
• Audience-driven personalization – Elevate personalizes the on-site experience based on audiences created in Engage.
• Current interest audiences – Engage audiences can be built using real-time behavioral data from Elevate.
• Smarter recommendations – Elevate’s recommendations are enhanced with in-store purchase data captured by Engage.

By making Engage and Elevate agree on who a particular contact is, data such as audiences and behavior can be easily shared between the two products. This is done with a unified identifier called discoveryKey.

The discoveryKey attribute is used to connect the same contact in Engage and Elevate.

This article looks at how this integration between Engage and Elevate is done.

Customer key in Elevate

In Elevate, the customerKey is the unique identifier for a visitor on the website.

A customerKey is required for every request to the Elevate API, whether for notifications or queries. To link a visitor in Elevate to an Engage contact, the customerKey from Elevate should be stored in the discoveryKey contact attribute within Engage. This enables cross-platform understanding of the visitor and enhances personalization capabilities for both Elevate and Engage.

Identifying the visitor

There are two general ways a visitor can be identified:

• Upon entry
• During the session

1 - Identification upon entry

When a visitor enters the site, they may arrive wither organically, from a referral or through a newsletter.

What happens next in this case depends on the customerKey:

• If a customerKey is already available (stored client-side or retrieved from softId), use it in all Elevate calls
• If no customerKey exists, create one, store it client-side (localStorage or cookie) and then use it in Elevate calls
• If a visitor arrives via softId (from an Engage newsletter), you’ll need to decode the softId, retrieve the matching customerKey, and overwrite the local value of customerKey if it is different

For detailed behavior, see the specific visitor types below.

2 - Identification during session

If the customer is not identified at entry (see above), they can be identified during the session if they:

• Creating an account
• Logging in to an existing account
• Signing up for a newsletter, wishlist, or reminder
• Placing an order

After identification

When the visitor has been identified, check if they exist in Engage.

• If they don’t exist, create the contact and assign discoveryKey to the customerKey value
• If they do exist, retrieve and compare the discoveryKey to the client’s customerKey and if the values are different, overwrite the client-side customerKey with the Engage discoveryKey

For detailed behavior, see the specific visitor types below.

Best practices for identification

• Ensure Engage is updated with the discoveryKey for all members (visitors who can sign in)
• All discoveryKey values must be unique; duplicate values in Engage prevent personalization
• Always call Elevate with the existing customerKey when a visitor is identified
• Use Engage’s softId for newsletters to maximize identification rate and cross-system linking
• Define a single source of truth for the customerKey, for example the discoveryKey in Engage, to resolve conflicts between local and server values

Integration flows

Now we will examine the different flows for the three types of visitor:

• New visitors
• Returning visitor
• Newsletter visitors

New visitor flow

1. The visitor enters

   When the visitor enters the site:

   • Generate a new customerKey
   • Store that customerKey value on the client side
2. The visitor browses

   When the visitor browses, for example, a category or product page:

   • Read customerKey from the client side
   • Call Elevate API with customerKey
3. The visitor clicks

   When the visitor clicks on, for example, a navigation link, add to cart or add favorite:

   • Read customerKey from the client side
   • Call Elevate API with customerKey
4. The visitor signs up

   When the visitor signs up:

   • Read customerKey from the client side
   • Create user account with customerKey
   • Call Engage API to create new contact with discoveryKey
   • Update user account with contactId from Engage This should create a mapping between the user account, the Elevate customerKey, and the Engage contactId.

This scenario also covers situations where an unknown visitor makes a purchase and a contact is created in Engage.

Returning visitor flow

1. The visitor enters

   When the visitor enters the site:

   • Read customerKey from the client side
2. The visitor browses

   When the visitor browses, for example, a category or product page:

   • Read customerKey from the client side
   • Call Elevate API with customerKey
3. The visitor clicks

   When the visitor clicks on, for example, a navigation link, add to cart or add favorite:

   • Read customerKey from the client side
   • Call Elevate API with customerKey
4. The visitor signs in

   When the visitor signs in:

   • Read customerKey from user account
   • Call Engage API to update contact with discoveryKey
   • Update the client side with customerKey The visitor is now identified, and the existing customerKey from the user account may differ from the customerKey on the client side. Therefore it is important to use the customerKey from the user account when calling the Engage API and to update the client side value accordingly

Newsletter visitor flow

1. The visitor enters

   When the visitor enters the site:

   • Decode softId and identify visitor
   • Read discoveryKey or customerKey from decoded softId or from user account
   • Update the client side with customerKey
2. The visitor browses

   When the visitor browses, for example, a category or product page:

   • Read customerKey from the client side
   • Call Elevate API with customerKey
3. The visitor clicks

   When the visitor clicks on, for example, a navigation link, add to cart or add favorite:

   • Read customerKey from the client side
   • Call Elevate API with customerKey
4. The visitor signs in

   When the visitor signs in:

   • Read customerKey from user account
   • Call Engage API to update contact with discoveryKey
   • Update the client side with customerKey

Identifying email traffic by discoveryKey

The discoveryKey is an integral part of the Engage soft login (previously called auto-login) and needs to be activated by your Engage specialist.

Soft login is critical for maximizing identification across Engage, Elevate, and between the two products. A high identification rate is the foundation for realizing the full value of the integrated Engage–Elevate setup.

The soft login happens via an encrypted query string parameter named “eclub” which holds information about the contact who has clicked on a link, such as a URL in an email campaign.

The target site back-end can listen to 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:

Example of soft login

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.

Decrypted payload

{
    "id": "60333",
    "email": "[e-mail]",
    "contactId": "d35ec9f5-2df7-4d44-b92b-a90c001ce732",
    "dateTime": "2022-05-11T13:15:40Z",
    "discoveryKey": "0b05119e-eeb8-418a-bbfb-defa0dde417e"
}

Engage soft identification on Elevate powered websites

A customer website running both Engage and Elevate must decrypt the soft login server-side and use the resulting discoveryKey as the customerKey in all subsequent calls to Elevate.

This ensures that traffic originating from Engage (for example email campaigns) is correctly identified in Elevate, allowing personalization, tracking, and recommendations to be applied consistently from the first page view.

If the decrypted payload does not contain a discoveryKey, it indicates that the contact has not previously been identified in Elevate and should be treated as a new or anonymous visitor.

SKU and variant key need to match

In Engage the SKU (stock-keeping unit) is a standard article property. Elevate, however, refers to articles as products, and the variations of products as variants.

Read about variants in Elevate

Each product and variant in Elevate has a unique key and must use a variantKey that corresponds to the article SKU in Engage.

Several features depend on these values being aligned. For example, Engage retrieves product metadata from Elevate to render product recommendations, and matching keys are also required for Elevate to consume in-store purchase data from Engage.

If the Engage and Elevate feeds are not aligned, contact your Engage representative to discuss next steps. Be aware that some features will be unavailable until the feeds are aligned.

Verifying discoveryKey implementation

The e-com platform/site should include discoveryKey in every create/update contact request made to the Engage API.

There are three ways this identification can be done:

Verify by API

Verification can be done by API requests. The following endpoints include discoveryKey in the response:

GET /api/v3/contactoverview

GET /api/v3/contacts

Verify end-to-end

This is a simple way to test the discoveryKey implementation end-to-end.

1. Go to the contact card in Engage for your user. Note that the “Discovery key” field is empty.

2. Go to the storefront of the retailer
3. Identify yourself on the site, either by signing in or creating an account. If possible, take note of the customerKey or ID if that is stored for a contact in the e-com/back-end system. This may be needed for future reference or troubleshooting.
4. Now back to the Engage tenant. Confirm that the discoveryKey has been applied to the contact by checking the field in the contact card. If you have noted the customerKey or ID in step 3, verify that it matches.

5. This is an optional step you can do if the e-com/website creates a pre-membership account during newsletter sign-up. You can verify if the discoveryKey has been assigned to the pre-membership contact in the Engage tenant by signing up for a newsletter and checking the discoveryKey of the newly created contact in the Engage tenant.

Verify in dev tools

Sometimes it is possible to verify that the Elevate customerKey matches the discoveryKey in the Engage contact card by using the browser’s developer console. Here you can analyze network communication and browser storage for clues to confirm the match between the customerKey and discoveryKey.

This ensures that the correct user data is being used for current interests.

Handling duplicate discoverKey values

All contacts in Engage must have unique a discoveryKey value. If a discoveryKey is not unique, this can block contact creation and prevent personalization from working correctly.

When a validation error occurs

A discoveryKey validation error means that the discoveryKey you tried to save already exists in Engage. New or updated contacts are validated when added through the Contact API v2/v3. Other interfaces for creating or updating contacts, such as bulk endpoints, are not affected by this validation.

In this case, an error will be returned:

Error when discoveryKey is already in use

{ 
  "errors": [ 
    { 
      "code": "DuplicateDiscoveryKey", 
      "message": "The discoveryKey already exists and must be unique." 
    } 
  ] 
}

If you receive this error repeatedly, it may indicate that your website is not assigning unique discoveryKey values to visitors. This can sometimes be related to how your site generates and stores identifiers, including through connection with integrations (for example, to Voyado Elevate).

Resolving the issue

Your site must always assign visitors a new, unique discoveryKey. Once generated, this new discoveryKey must be used in:

• Contact API requests
• The visitor’s cookie
• Any other system where discoveryKey is stored (such as databases, Engage, Elevate)

How this is implemented is site-specific, but the goal is always the same: to ensure that every visitor and member has a unique discoveryKey across all systems.

Cleaning up duplicates

Before cleaning up existing duplicates:

• Make sure no new duplicates are being added.
• Confirm that the normal flows for adding and updating contacts work correctly (without disabling validation)

Here are three imoportant cases when handling duplicates:

When e-com / 3rd party system is the master

If your e-commerce platform or another system is the master of discoveryKey, duplicates must be resolved there first. Once corrected, you will then send the updated discoveryKey values to Engage.

When Engage is the master

If Engage is the master of discoveryKey, duplicates can be removed directly within Engage. Contact Voyado Support for assistance with this process.

Updating duplicates instead of removing them

If you prefer to update duplicate records rather than remove them, the master system must:

• Identify which contacts to update.
• Send the changes to Engage (via API or integration).

Depending on the scale and complexity, this process may require assistance from Voyado Support to export duplicate lists or perform bulk updates.