Skip to main content
This guide is intended to be used alongside the core documentation for implementing the Engage–Elevate integration. For full reference on how discoveryKey works and how to implement it correctly, see Engage with Elevate.

​
Purpose

To identify why Elevate sessions are not matching Engage contacts, resulting in a low share of connected sessions. Typical symptoms include:
  • Very low share of connected sessions (<5%)
  • Returning customers not being recognised
  • Limited personalisation impact

​
Core principle

A session becomes connected when: Elevate session: customerKey = X matches Engage contact: discoveryKey = X Three conditions must all be true:
  1. The session contains a customerKey
  2. The Engage contact has a discoveryKey
  3. customerKey = discoveryKey
Some of the investigations below require access to Elevate Health Overview or Engage contact data. Depending on the access available to the developer or implementor, these steps can be carried out together with Voyado.

​
Step 1 — Establish the current state

Start by:
  • Checking the share of contacts in Engage with a discoveryKey assigned, this is the most important indicator and the right place to start. A well-implemented setup should have 90%+ coverage. If in-store registration is part of your model, see step 6 for how to handle this correctly.
Then check:
  • Share of connected sessions in Elevate Health Overview
  • Share of customers with purchases without a discoveryKey
  • Whether all purchases are sent to Engage or only member purchases
Connected sessions typically range 5–40%. Where you sit in that range depends heavily on:
  • The share of contacts in Engage with a discoveryKey
  • How often visitors are identified, a loyalty-heavy retailer with mandatory login should be at the high end; a guest-checkout-heavy retailer will naturally sit lower.

​
Step 2 — Verify discoveryKey assignment

Is discoveryKey being set, and is it set correctly? When a user is identified, customerKey in Elevate and discoveryKey in Engage must have the same value. Check:
  • Which identifier is used as customerKey
  • Whether the same value is used as discoveryKey in Engage
  • When discoveryKey is set (login, checkout, purchase, etc.)
  • Whether discoveryKey is included in all Engage API requests that support it — discoveryKey is supported on contact create, update and bulk endpoints only
Verify by inspecting the contact create/update API requests sent to Engage upon identification. Common issues:
  • discoveryKey not included in all Engage requests
  • discoveryKey set too late in the flow
  • customerKey and discoveryKey using different identifiers
  • A new customerKey generated instead of reusing the existing one
  • Existing Engage contacts missing discoveryKey entirely
Resolution:
  • Send discoveryKey consistently in all Engage calls
  • Set discoveryKey as soon as the user is identified
  • Align customerKey and discoveryKey to the same identifier
  • Reuse the existing customerKey for returning visitors
  • Update existing contacts when they are next identified

​
Step 3 — Verify ID consistency across systems

Is the same identifier used consistently everywhere? Even if discoveryKey is being set correctly, inconsistent identifiers across systems will prevent sessions from connecting. The same identifier must flow through:
  • Elevate session → customerKey
  • Elevate events → customerKey
  • Engage contact → discoveryKey
  • Engage events (including purchase) → discoveryKey
Common issues:
  • Different identifiers used across systems
  • The existing customerKey not being reused when a visitor is identified (e.g. at login), causing a mismatch with the discoveryKey in Engage
  • A new customerKey generated instead of reusing the existing one
  • Purchase events sent to Engage before discoveryKey has been applied in the same flow
Resolution:
  • Use one stable identifier for both customerKey and discoveryKey
  • When a visitor is identified (e.g. at login), reuse the existing customerKey — or if a known customerKey is retrieved from the user account, switch to that and update the client side accordingly
  • Ensure discoveryKey is set and purchase events are sent in the correct order within the identification flow

​
Step 4 — Analyse unmatched customerKeys

Elevate Health Overview can provide a sample of customerKeys for returning customers (purchase within last 6 months) that don’t match any discoveryKey in Engage. This step can be done together with Voyado if access to Health Overview is limited. For each customerKey in the sample, check:
  • Does the customerKey exist in the ecom system, and which contact does it belong to?
  • Does that contact exist in Engage?
  • Does the Engage contact have a discoveryKey?
  • Does the discoveryKey match the Elevate customerKey?
  • Are multiple contact profiles present for the same user?
Possible explanations:
  • discoveryKey missing
  • discoveryKey ≠ customerKey
  • Only member purchases sent to Engage
  • Incorrect identification at checkout
  • customerKey regenerated instead of reused
If the volume is large, consider a bulk update. If your system holds both the Elevate customerKey and the Engage contactId, a bulk import can backfill discoveryKeys for existing contacts quickly.

​
Step 5 — Verify soft ID / email channel identification

Visitors arriving via email links should be identified automatically via the soft ID (eclub) parameter. This is one of the highest-leverage identification touchpoints and a common gap. The following checks require Voyado’s involvement, raise these with your Voyado team:
  • Is soft identification enabled for this environment?
  • Does the decrypted soft ID payload include the discoveryKey field? (Not on by default — requires explicit activation by the Voyado team)
Depending on the configuration, identification works as follows:
  • If soft ID is active and discoveryKey is included in the payload, the website can use it directly as the customerKey in Elevate
  • If discoveryKey is missing from the payload, the website can still identify the visitor via the contactId and retrieve the associated customerKey from the ecom system
  • If soft ID is not used at all, identification relies on whether a customerKey is already available client-side, for example from a cookie

​
Step 6 — Check in-store recruits

Members recruited in-store often have no discoveryKey because there is no browser session at the point of sign-up. This can be a significant source of unmatched contacts, particularly for retailers with large physical store networks. Resolution options:
  • Generate a customerKey at point of in-store registration and store it in Engage immediately
  • If that is not possible, send a verification SMS or email as a double opt-in. If email is used and soft ID is enabled, the visitor will be identified automatically on click. With SMS, add the contactId as a shortGUID in the URL and handle identification on landing.
Read more about this on HelpCenter

​
Step 7 — Verify identification logic in code

A code-level review to confirm the implementation matches the expected behaviour described in steps 2 and 3. Check:
  • On login or checkout, is customerKey aligned with discoveryKey?
  • Is the updated identifier used in all subsequent events and purchases?
Common issues:
  • customerKey generated multiple times instead of reused
  • customerKey not updated after identification
  • discoveryKey not included in Engage events post-identification
  • Purchase events sent before identification has been applied
Expected outcome A well-implemented setup typically delivers connected sessions in the 20–40% range for loyalty-driven retailers. Higher connected session rates directly enable:
  • More relevant product recommendations
  • Audience-based onsite personalisation
  • Behaviour-driven marketing in Engage
For retailers this typically results in improvements to conversion rate, average order value, and revenue per visitor. Read more about the connected capabilities here.