The product configuration signal captures user interactions with a product that suggest evaluation and preparation to purchase — for example, selecting a colorway or adjusting quantity in retail, choosing a seat or meal preference in travel, or selecting a coverage level in financial services. It tracks engagement beyond the product view, identifying users who are actively considering a product. In Connect, the signal enables segmentation by configuration type, product, and product category.

Availability: Premium and Ultimate

Languages: Kotlin and Java

Implementation considerations

Relationship to the product view signal

The product view and product configuration signals work together:

• productView — fires when the product detail screen loads
• productConfiguration — fires each time the user interacts with a product element

Use the same productId and productName values in both signals to ensure consistent tracking.

Product catalog

The product configuration signal automatically updates your product catalog in Connect:

• If the product ID is new, Connect creates a catalog entry from the signal data.
• If the product ID already exists, Connect updates the following catalog attributes from the signal: productName, unitPrice, productCategory, productDescription, currency, discount, inventoryQuantity, imageUrls, and productUrls.
• Connect matches categories by the productCategory string — if a category with that name already exists, the signal maps to it; if it's new, Connect creates a catalog category entry and assigns it an internal ID.

Null values do not overwrite existing catalog data. Empty strings update the field to blank. Zero values update numeric fields to zero.

When to fire the signal

Fire the signal each time a user interacts with a product element on the product detail screen. Common interactions in Android apps:

• Selecting a colorway or variant chip
• Adjusting quantity
• Tapping to view additional images
• Expanding product details or reviews

For interactions that fire rapidly in sequence — such as a quantity stepper — consider debouncing to avoid sending a signal on every tap.

Configuration type labels

Use the configurationType field to identify what the user interacted with. You can label by product parameter, UI element, or action:

Choose a consistent approach across your implementation for better analytics.

Contact mapping

Use the audience field to map the signal to a contact in Connect. Commonly used identifiers are email address, phone number, and customer ID.

📘

Note

A customer ID mapped to the Contact key attribute in Connect is the most reliable identifier for known contacts. However, if no matching contact exists and the only attribute is a contact key, the signal is discarded — contact keys alone cannot create new contacts.

Sources of the identifier in an Android app:

• In-memory session object (for example, UserSession.email)
• SharedPreferences for persisted login state
• Room database or other local store

The value must be a JSONObject where each key is a contact attribute name as it appears in Connect (including capitalization and spacing) and each value is the attribute value. For phone number attributes, use the E.164 format: +[country code][area code][phone number] — no spaces, dashes, or special characters. If the + symbol is omitted, Connect adds it automatically.

📘

Note

We recommend attaching identifiers to as many signals as possible. If the user is not authenticated, omit audience — Connect will attempt to identify the visitor using other signals from the same session.

Configuration

Method

Connect.logSignal(data: HashMap<String?, Any?>?): Boolean

Sends the signal to the Acoustic Connect endpoint. The Connect SDK must be initialized via Connect.enable() before calling this method.

Pass all fields as a flat HashMap. The SDK handles the signal structure automatically — you do not need to construct a nested object.

Signal fields

Required

Optional

✅

Things to know

• Fields with schema type Number must be passed as strings. The SDK serializer silently drops numeric values.

• Pass audience as a JSONObject, not a HashMap. A HashMap value is silently dropped by the SDK serializer and the contact will not be mapped.

• Pass imageUrls and productUrls as a JSONArray of strings.

• If a required field is missing or invalid, the entire signal is discarded. If a required field isn't applicable to your business, use a placeholder value.

Required imports

import org.json.JSONArray
import org.json.JSONObject

Basic example

val data = hashMapOf<String?, Any?>(
    "signalType" to "productConfiguration",
    "productId" to "SKU-12345",
    "productName" to "Wireless Headphones",
    "configurationType" to "color"
)
Connect.logSignal(data)

Complete example

This example fires a product configuration signal from a product detail bottom sheet when the user selects a colorway. It includes pricing, category, and optional contact mapping.

import org.json.JSONObject
import com.acoustic.connect.android.connectmod.Connect

private fun sendProductConfigurationSignal(configurationType: String) {
    // Fields with schema type Number must be passed as strings
    val data = hashMapOf<String?, Any?>(
        "signalType" to "productConfiguration",
        "productId" to product.id,
        "productName" to product.name,
        "configurationType" to configurationType,
        "unitPrice" to product.price.toPlainString(),
        "productCategory" to product.category.displayName,
        "currency" to "USD",
        "effect" to "positive"
    )

    // audience must be JSONObject — HashMap values are silently dropped
    UserSession.email?.let { email ->
        data["audience"] = JSONObject().put("Email Address", email)
    }

    Connect.logSignal(data)
}

Call sendProductConfigurationSignal("color") from the colorway chip's checked-change listener, sendProductConfigurationSignal("quantity") from the quantity stepper, and so on.

Troubleshooting

Signal not appearing in Connect?

• Confirm Connect.enable() is called before logSignal.
• Check that logSignal returns true. A false return indicates the SDK rejected the call.
• Verify the appKey and postMessageUrl match the Connect org you're checking.

Signal marked as invalid in Connect?

• Confirm all required fields are present: signalType, productId, productName.
• Verify that Number fields are passed as strings — use price.toPlainString().

Contact not created or updated?

• Confirm audience is a JSONObject, not a HashMap.
• Verify attribute key names match exactly how they appear in Connect — including capitalization and spacing.

Too many signals firing?

• For interactions that repeat rapidly (such as quantity steppers), add debouncing logic to avoid sending a signal on every tap.

Related pages

• Connect Android SDK: event and data logging
• How behavior signals are processed in Connect