The on-site search signal captures the search terms visitors use on your website and the number of results returned. This helps identify what users are looking for, discover content gaps and understand search effectiveness.

Reasons to enable:

• Track popular search terms
• Identify zero-result searches for content optimization
• Segment users based on search behavior
• Trigger campaigns for users who can't find what they're looking for

Availability: Premium and Ultimate

Implementation considerations

Data extraction approaches

• From URL query string. Many sites include search terms in the URL (for example, ?searchTerm=headphones). Extract the term by parsing the query string. Remember to decode URL encoding and replace + with spaces.
• From page content. Scrape the search term displayed on the results page. Often shown in headings or result summaries.
• From input field. Capture the value from the search input field. Useful if search doesn't navigate to a new page.

Number of results

The number of search results is typically available in the page body. Consider these scenarios:

• Direct result count. Most sites display total results (for example, "Showing 47 results"). Scrape this number directly.
• Page-based display. Some sites only show number of pages (for example, "Page 1 of 5"). If this is the case, calculate total results: pages × results per page.

• Zero results. Set effect to negative when no results are found. This helps identify content gaps and failed searches.

Relationship to page view signal

If you've already enabled the page view signal, you can adopt a similar approach for the on-site search signal by capturing the URL of the search results page.

Contact mapping

Any signal can be mapped to a contact. Use the audience object to provide a customer ID (contact key) or an addressable attribute (email or phone number). You can provide several identification records in the same signal — for example, a contact key and an email address. For details on how Connect processes identification records, see How behavior signals are processed in Connect.

Several sources of identification are available:

• User identification stored in browser cookies
• Temporary session-based storage
• Persistent client-side storage
• Data layer (for example, Google Tag Manager dataLayer)
• URL parameters passed during navigation
• Login API monitoring (capture identifier during successful authentication)

If none of these options are available, work with your development team to make the identifier accessible to the Connect library.

🚧

Important

We recommend attaching identifiers to as many signals as possible. However, if an identifier is missing, the system falls back on other signals from the same user session in order to identify the website visitor.

Configuration

Method

TLT.logSignal(signalObject)

Sends the signal to the Acoustic Connect endpoint as a JSON object. The Connect library must be initialized before calling this method.

Signal structure

Top-level fields

• audience: Array of objects - Create an object for contact mapping and any number of additional objects to update contact attributes.
• category: String - Valid value - Behavior.
• consent: Object - Consent preferences to update for the contact. At least one of the following channel fields is required: email, sms or whatsapp.
• description: String - Description of the signal
• effect: String - Describes the effect of the signal on engagement. Valid values: negative, positive. If a search term returns results, send positive. If there are no results, send negative.
• name: String - Name to differentiate this signal from others (for example, "onSiteSearch from online store"). Max length - 256 chars.
• signalType (required): String - Valid value - onSiteSearch.

Audience object

Create an object with one or more identifiers for contact mapping (recommended) and any number of additional objects for other contact attributes you want to update.

• name (required): String - Name of contact attribute. To get the full list of available attributes, use the Contact attributes query.
• value: The new value of the contact attribute. Its format depends on the attribute type (text, number, Boolean or date). If you send an empty or null value, it will be ignored and the contact attribute won't be updated.

📘

Note

• For date attributes, use the following format: yyyy-MM-dd'T'HH:mm:ssXXX.
• For phone number attributes, use the ISO E.164 format: +[country code][area code][phone number] — no spaces, dashes or special characters. If the + symbol is omitted, Connect adds it automatically.

• Consent object

Each channel accepts multiple entries to set different consent statuses per consent group in a single call.

• enableOverrideExistingOptOut (required): Boolean - When true, current opt-out statuses will be overridden by new statuses. When false, contacts who have unsubscribed from communications won't have their consent status updated.
• email: Array of objects - Consent entries for the email channel. The objects support the following fields:
  • status (required): Enum - Consent status for the email channel. Valid values: OPT_IN, OPT_OUT, OPT_IN_UNVERIFIED.
  • consentGroupIds: Array of strings - The IDs of consent groups a new status applies to. If you skip this field or send an empty array, the new consent status will be applied to all consent groups.
• sms: Array of objects - Consent entries for the SMS channel. The objects support the following fields:
  • status (required): Enum - Consent status for the SMS channel. Valid values: OPT_IN, OPT_OUT, OPT_IN_UNVERIFIED.
  • consentGroupIds: Array of strings - The IDs of consent groups a new status applies to. If you skip this field or send an empty array, the new consent status will be applied to all consent groups.
• whatsapp: Array of objects - Consent entries for the WhatsApp channel. The objects support the following fields:
  • status (required): Enum - Consent status for the WhatsApp channel. Valid values: OPT_IN, OPT_OUT, OPT_IN_UNVERIFIED.
  • consentGroupIds: Array of strings - The IDs of consent groups a new status applies to. If you skip this field or send an empty array, the new consent status will be applied to all consent groups.

📘

Note

To get the IDs of consent groups, use the dataSets query.

Signal content

• numberOfResults (required): Number - The number of results that matched the search term
• searchTerm (required): String - The word or phrase that the visitor searched for
• signalCustomAttributes: Array of objects - Additional custom attributes. Each object has name and value string fields.

Basic example

// Initialize the Connect library
if (window.TLT) {
    TLT.initPremium({
        appKey: "APP_KEY",
        postUrl: "COLLECTOR_URL",
        callback: function() {
            const signal = {
                // Required fields
                signalType: "onSiteSearch",
                searchTerm: "wireless headphones",
                numberOfResults: 24,

                // Optional fields
                category: "Behavior",
                name: "onSiteSearch from website",
                effect: "positive",

                // Contact mapping
                audience: [
                    {
                        name: "Customer ID",
                        value: localStorage.getItem("customerId")
                    }
                ]
            };

            // Send the signal
            TLT.logSignal(signal);
        }
    });
}

Complete implementation example

This example extracts the search term from the URL query string, scrapes the result count and sets the effect based on whether results were found. The audience identifier is extracted from a URL parameter.

// Initialize the Connect library
if (window.TLT) {
    TLT.initPremium({
        appKey: "APP_KEY",
        postUrl: "COLLECTOR_URL",
        callback: function() {
            const href = window.location.href;

            // Check if we are on the search results page
            if (href.includes("s?searchTerm=")) {
                // Extract and clean search term from query string
                let searchTerm = href.split("s?searchTerm=")[1] || "";
                searchTerm = searchTerm.replaceAll("+", " ");
                searchTerm = decodeURIComponent(searchTerm);

                // Scrape number of results from the page
                const numberOfResults = Number(document.querySelector(".itemCount")?.innerText) || 0;

                const signal = {
                    signalType: "onSiteSearch",
                    category: "Behavior",
                    name: "onSiteSearch generated by website",

                    // Required fields
                    searchTerm: searchTerm,
                    numberOfResults: numberOfResults,

                    // Set effect based on whether results were found
                    effect: numberOfResults ? "positive" : "negative"
                };

                // Add contact mapping from URL parameter
                const urlParams = new URLSearchParams(window.location.search);
                const customerId = urlParams.get("customerId");
                if (customerId) {
                    signal.audience = [
                        {
                            name: "Customer ID",
                            value: customerId
                        }
                    ];
                }

                // Optional: Log signal for debugging
                console.log("onSiteSearch signal:", JSON.stringify(signal, null, 2));

                // Send signal to Connect
                TLT.logSignal(signal);
            }
        }
    });
}

Related pages

How behavior signals are processed in Connect