SDKs
Help centerCommunityDevelopersAcademyStatus

Enable error signals in the Connect web library

Suggest Edits

You can enable the Connect library to generate an error signal each time a user encounters an error on your site. We suggest focusing on payment, promo code, and account registration errors - anything that leads users away from the happy path and results in lost sales opportunities.

🚧

Important

The error signal doesn't replace an error monitoring solution. Its aim is to let marketers segment out users who have ran into issues during the order process. Also, marketers can set up the delivery of personalized messages triggered by the signal.

Availability

The error signal is supported by Premium and Ultimate subscriptions.

Configuration

The Connect library provides a method, TLT.logSignal() with which to send the signal to the Acoustic Connect endpoint, as a JSON object. The Connect library must be initialized before the method is called.

Two errorType values are supported, application and user.

User errors include form validation errors, errors caused by users entering incorrect payment details, invalid promo codes, and so on. These could be checked for on page load or after a particular button click, for example.

Application error messages are those created by the application itself, including displaying 4xx and 5xx error pages to the user. Note that for the Connect library to be able to capture 4xx and 5xx errors your application must be configured to display error placeholder pages on which the library is included.

📘

Tip

Make sure all important user errors are communicated in the interface. If something happens quietly under the hood, it won't be reported on.

Required fields

You must provide values for all required fields, or the signal will be ignored. These are the error ID, error message and error type.

FieldValuesDefinition
categoryString. Valid value - Behavior.The category of the signal. Do not edit.
effectString. Valid values:

- negative
- positive		Describes the effect of the signal on engagement. It is intended to be used for engagement index scoring.

We suggest sending negative for all error signals.
errorIdentifier StringAn identifier assigned to the error. Example: "promoCode".
errorText StringThe content of the error message received
errorType String. Valid values:

- application
- user		Application errors are server-side or system errors. User errors occur when user input doesn't pass client- or server-side validation.
nameString, up to 256 charactersAssign a name to the signal to differentiate it from other signals.
signalTypeString. Valid value -
error.		The type of signal to enable. Do not edit.

Optional fields

FieldValuesDefinition
signalCustomAttributesArray of objectsAllows for additional custom attributes. For each custom attribute, add an object with two string fields:name and value.

Example

// Check that the Connect SDK is present
if (window.TLT && window.TLT.isInitialized()) {
    const signal = {
            signalType: "error",
            name: "error generated by web site",
            category: "Behavior",
            errorType: "", // Required, must be "application" or "user"
            errorText: "", // Required
            errorIdentifier: "", // Required
            effect: "negative", // Required, must be "positive" or "negative"
            signalCustomAttributes: []
        },
        href = window.location.href;

    // Coupon code errors result in message in query string
    if (href.includes("/checkout/?CouponCodeErrorMessage=")) {
        signal.errorText = href.split("checkout/?CouponCodeErrorMessage=")[1];
        if (signal.errorText) {
            // Tidy up the message text
            signal.errorText = signal.errorText.replaceAll("%20", " ");
            // A coupon code error is of type "user" rather than "application"
            signal.errorType = "user";
            signal.errorIdentifier = "promoCode";
            window.TLT.logSignal(signal);
        }
    }

    // In the checkout, payment errors are styled with a particular class. Because the
    // page reloads on form submission they appear after load if that submission fails
    // so on this site we can check for them on load rather than listening for a click, for example.
    if (href.includes("/checkout/")) {
        signal.errorText = document.querySelector('form[action="/checkout/Payment/"] > div.notice-error').innerText || "";
        if (signal.errorText) {
            // Tidy up the message text
            signal.errorText = signal.errorText.replaceAll("\n", " ");
            // A payment validation error like this is of type "user" rather than "application"
            signal.errorType = "user";
            signal.errorIdentifier = "payment";
            window.TLT.logSignal(signal);
        }
    }
}

Updated 4 days ago