Dynamic Links

Before you Start

How to create dynamic links

Learn the link structure

Schematically, a Dynamic Link is structured schematically as follows:

        https://feedback.echonovum.com/{surveyAccessCode}?p={encryptedPayload}&t={encryptionSecretReference}\
        

Survey Access Code

The survey access code is a unique identifier for the survey you want to link to.

Encrypted Payload p

Query parameter: p

Holds the profile and link configuration data.

Encryption Secret Reference

Query parameter: t

The encryption secret reference is a unique identifier for the encryption secret used to decrypt the profile data by echonovum.

Define the Payload

Define the payload data according to the following schema.

Single Participation sp

The argument that defines whether a dynamic link can be used once or multiple times.

Possible values: 1 (true), 0 (false).

"Subject" Profile s

The subject profile data that should be attached to the feedback.

The subject profile contains the data of the person who should provide feedback.

"Object" Profile o

The object profile data that should be attached to the feedback.

The object profile contains additional data - usually describing the event in more detail.

Profile Data Object

The profile data object consists of the following properties:

a: The profile attributes as key-value pairs.
i: The name of the identifier attribute of the profile data.
d: The name of the display attribute of the profile data.
s: The profile schema identifier to link the profile data to.

// Example Profile Object
{
    "a": {
        "ID": "da7d5edc-4dd9-4f69-8ce6-036be70007e4",
        "Name": "Petra Muster",
        "First name": "Petra",
        "Last name": "Muster",
        "Salutation": "Ms",
        "Email": "petra.muster@example.com",
    },
    "i": "ID",
    "d": "Name",
    "s": "55bfff24-9728-409f-9527-8436ee1e9351",
}

Encrypt the Payload

Have a look at the following example to see how to encrypt the payload data.

const key = "some-very-secure-key"; // obtained from echonovum
const iv = crypto.randomBytes(16); // must be 16 bytes

const encryptionSecretReference = "some-reference"; // obtained from echonovum
const surveyAccessCode = "EPBpj2";
const surveyLink = `https://feedback.echonovum.com/${surveyAccessCode}`;

// Stringified payload
const payload = JSON.stringify({
        "sp": 1,
        "s": {
            "a": {
                "ID": "da7d5edc-4dd9-4f69-8ce6-036be70007e4",
                "Name": "Petra Muster",
                "First name": "Petra",
                "Last name": "Muster",
                "Salutation": "Ms",
                "Email": "petra.muster@example.com",
            },
            "i": "ID",
            "d": "Name",
            "s": "55bfff24-9728-409f-9527-8436ee1e9351", // profile schema uuid
        },
        "o": {
            "a": {
                "Transaction-ID": "5982617a-c7e3-410e-9bda-6461b578e539",
                "Transaction Name": "Contract signed / Petra Muster / 2021-09-01",
                "Sales Person": "Peter Seller",
                "Sales Person E-Mail": "peter@example.com",
                "Touchpoint": "Contract signed",
                "Contract Nr.": "987654321",
            },
            "i": "Transaction-ID",
            "d": "Transaction Name",
            "s": "3d4bf161-4c32-42f8-a0f0-bd727493fb06", // profile schema uuid
        }
    }
);

const encrypter = crypto.createCipheriv("aes-256-cbc", key, iv);

let encryptedMsg = encrypter.update(payload, "utf-8", "base64");
encryptedMsg += encrypter.final("base64");

const base64EncodedIv = iv.toString('base64');

const urlEncodedEncryptedMsg = encodeURIComponent(`${encryptedMsg}.${base64EncodedIv}`);

const finalLink = `${surveyLink}?p=${urlEncodedEncryptedMsg}&t=${encryptionSecretReference}`;

console.log(finalLink);

<?php
// Required for encryption
$key = "some-very-secure-key"; // obtained from echonovum
$iv = openssl_random_pseudo_bytes(16); // must be 16 bytes

// Other constants
$encryptionSecretReference = "some-reference"; // obtained from echonovum
$surveyAccessCode = "EPBpj2";
$surveyLink = "https://feedback.echonovum.com/" . $surveyAccessCode;

// Stringified payload
$payload = json_encode(array(
    "sp" => 1,
    "s" => array(
        "a" => array(
            "ID" => "da7d5edc-4dd9-4f69-8ce6-036be70007e4",
            "Name" => "Petra Muster",
            "First name" => "Petra",
            "Last name" => "Muster",
            "Salutation" => "Ms",
            "Email" => "petra.muster@example.com"
        ),
        "i" => "ID",
        "d" => "Name",
        "s" => "55bfff24-9728-409f-9527-8436ee1e9351" // profile schema uuid
    ),
    "o" => array(
        "a" => array(
            "Transaction-ID" => "5982617a-c7e3-410e-9bda-6461b578e539",
            "Transaction Name" => "Contract signed / Petra Muster / 2021-09-01",
            "Sales Person" => "Peter Seller",
            "Sales Person E-Mail" => "peter@example.com",
            "Touchpoint" => "Contract signed",
            "Contract Nr." => "987654321"
        ),
        "i" => "Transaction-ID",
        "d" => "Transaction Name",
        "s" => "3d4bf161-4c32-42f8-a0f0-bd727493fb06" // profile schema uuid
    )
));

// Create cipher object and initialize it for encryption
$encryptionMethod = "aes-256-cbc";
$encryptedMsg = openssl_encrypt($payload, $encryptionMethod, $key, OPENSSL_RAW_DATA, $iv);

// Base64 encode the encrypted message and the IV
$base64EncodedEncryptedMsg = base64_encode($encryptedMsg);
$base64EncodedIv = base64_encode($iv);

// URL encode the encrypted message and IV
$urlEncodedEncryptedMsg = urlencode($base64EncodedEncryptedMsg . '.' . $base64EncodedIv);

// Construct the final URL
$finalLink = $surveyLink . "?p=" . $urlEncodedEncryptedMsg . "&t=" . $encryptionSecretReference;

echo $finalLink;

Last modified: 27 May 2024