Contact identification by discoveryKey
Any integrations between Engage and Elevate dated after 2022-06 must use the discoveryKey contact attribute in Engage to be considered valid. Even if the value of the contactId attribute in Engage is the exact same as the customerKey value in Elevate (one-to-one equivalence) it is still important to set the discoveryKey attribute in Engage 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 created 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 needs 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 who has clicked on a link, such as a 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"
}Engage soft identification on Elevate powered websites
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 (such as 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.
Validating the discoveryKey integration
For in-depth information about the Voyado API refer to the API documentation and your OpenAPI (Swagger) page.
Setting or updating a contact's discoveryKey
You should always provide the discoveryKey value during the creation of a new contact in Engage. When updating an existing contact, these is no need to send discoveryKey unless it has changed. See the documentation on the /contacts endpoint for more details.
To update the discoveryKey, a call like this is made:
POST /api/v2/contacts/{contactId}
With a payload of this form:
{
"discoveryKey": "64fe7cb7-4792-44f6-900e-c9dc8e27aaaa"
}The response of a successful update will contain the contact data, including the newly updated discoveryKey listed under attributes:
{
"id": "aac97fa0-23e7-1111-ba7e-af1200ecede0",
"attributes": {
"firstName": "Example",
"discoveryKey": "64fe7cb7-4792-44f6-900e-c9dc8e27aaaa",
…
}
Retrieving a contact's discoveryKey
To fetch a contact's discoveryKey, the /contacts endpoint is also used:
GET /api/v2/contacts/{contactId}
If the specifed contact exists, the response will contain the discoveryKey attribute. All contact data will be returned.
{
"id": "aac97fa0-23e7-1111-ba7e-af1200ecede0",
"attributes": {
"firstName": "Example",
"discoveryKey": "64fe7cb7-4792-44f6-900e-c9dc8e27aaaa",
…
}