With rule-based form listening in BlueConic, you can set a value for a property in a visitor's profile based on visitor input. You can use the interaction both to set the value of an existing profile property to a particular value and also to add a value to a profile property that supports multiple values. The input from the visitor is derived from a form submitted on a web page.
In this listener, you define which form field contains the data to be written to the profile property, the profile property it is written to, and the circumstance that triggers the submission of the data to the profile property.
Configuring a Rule Based Form Listener
Follow the steps in the following sections to configure form listening.
Open the Listeners page and click Add listener.
Choose Rule Based Form Listener and enter a name for the listener.
In the Where field, define the channels and optionally the URLs where the listener will be active.
Click Add rule to define the listening rule(s).
Defining listener rules
A listen rule defines the form field from which the text or value is taken, the profile property to which the text or value is added or set, and the event that triggers the setting or addition of the text or value to the profile property:
Value: Used for input elements.
Text: Used for other text elements, such as titles or paragraphs.
The text or value can also be converted according to a defined mapping before it is written to the visitor profile.
If you set the value of a profile property, the current text or value is replaced by the new text or value. An option to set "only if empty" exists to ensure that only the first occurrence of a value is stored in the specified profile property.
If you add the text or value to a profile property, the profile property will contain multiple entries. You must create a listen rule for each form field that you want to write to a profile property.
Listening rules: You can create several types of listening rules. They differ in the circumstance that triggers the submission of the data in a form field to a profile property. The different listen rule variations are:
Note: The permission level of the website visitor and the profile property must be sufficient to allow the text or value to be written to it. For example, if the permission level of the profile property is Level 2 and the visitor has selected Level 1 permission, the text or value will not be written to the profile property.
Writing data to a profile property when a surrounding form is submitted
This listen rule is triggered when an entire form is submitted. The data from the form field you specify is written to the profile property you specify. (Note: This option is currently available for web channels, but not for native app channels.)
Click Add Rule.
Select whether this rule is an add or set operation. An add operation keeps the existing data in the profile property and adds the new data to it. A set operation substitutes the existing data with the newly submitted data, unless the "only if empty" option is checked.
Select whether this rule deals with text or a value.
Click the "define form field" link. This is the form field from which you want to take the data that is written to the profile property.
For this form field, complete these steps:
Enter a name for the form field in the "Name" text box. This is an internal name for the form field that you choose to use identify it — it is not the name of the form field in the source code.
Enter a valid jQuery Selector to define the form field. For complete information on jQuery Selectors, follow this link: https://api.jquery.com/category/selectors/
To define the area using the Visual Picker, click Visual Picker.
Click OK.
Click the "define profile property" link. You can use an existing profile property or enter a new profile property name to create a new one here. See Profile properties for complete information on working with profile properties.
If you want to convert the value, see the instructions in "Converting values" below for complete information on configuring value conversion.
Repeat the steps above for each listen rule of this type you want to create.
Click Save.
Writing data to a profile property when a form field value changes
Click Add rule.
Select whether this rule is an add or set operation. An add operation keeps the existing data in the profile property and adds the new data to it. A set operation substitutes the existing data with the newly submitted data, unless the "only if empty" option is checked.
Select whether this rule deals with text or a value.
Click the "define form field" link. This is the form field from which you want to take the data that is written to the profile property.
For this form field complete these steps:
Enter a name for the form field in the "Name" text box. This is an internal name for the form field that you choose to use identify it — it is not the name of the form field in the source code.
Enter a valid jQuery Selector to define the form field. For complete information on jQuery Selectors, follow this link: https://api.jquery.com/category/selectors/
To define the form field using the Visual Picker, click Visual Picker.
Click OK.
Click the "define profile property" link. You can use an existing profile property or enter a new profile property name to create a new one here. See Profile properties for complete information on working with profile properties.
Select the option "form field value changes" to store the form data when it changes.
If you want to convert the value, see the instructions in "Converting values" below for complete information on configuring value conversion.
Repeat the steps above for each listen rule of this type you want to create.
Click Save.
Writing data to a profile property when a custom form is submitted
This listen rule is triggered when a specified form is submitted. Typically this option is used when you want to write data from a form field to a profile property when a specific form is submitted, not necessarily the one containing the form field in question.
Click Add Rule.
Select whether this rule is an add or set operation. An add operation keeps the existing data in the profile property and adds the new data to it. A set operation substitutes the existing data with the newly submitted data, unless the "only if empty" option is checked.
Select whether this rule deals with text or a value.
Click the "define form field" link. This is the form field from which you want to take the data that is written to the profile property.
For this form field, complete these steps:
Enter a name for the form field in the "Name" text box. This is an internal name for the form field that you choose to use identify it — it is not the name of the form field in the source code.
Enter a valid jQuery Selector to define the form field. For complete information on jQuery Selectors, follow this link: https://api.jquery.com/category/selectors/
To define the form field using the Visual Picker, click Visual Picker.
Click OK.
Click the "define profile property" link. You can use an existing profile property or enter a new profile property name to create a new one here. See Profile properties for complete information on working with profile properties.
Click the "the surrounding form is submitted" link.
Select "Custom defined form is submitted".
Enter a name for the custom defined form in the "Name" text box.
Enter a valid jQuery Selector to define the custom defined form in the "Selector" text field. For complete information on jQuery Selectors, follow this link: https://api.jquery.com/category/selectors/
To define the form using the Visual Picker, click Visual Picker.
Click OK.
If you want to convert the value, see the instructions in "Converting values" below for complete information on configuring value conversion.
Repeat the steps above for each listen rule of this type you want to create.
Click Save.
Writing data to a profile property when a custom position is clicked
This listen rule is triggered when a custom position is clicked in by the website visitor. The data from the form field you specify is written to the profile property you specify.
Click Add Rule.
Select whether this rule is an add or set operation. An add operation keeps the existing data in the profile property and adds the new data to it. A set operation substitutes the existing data with the newly submitted data, unless the "only if empty" option is checked.
Select whether this rule deals with text or a value.
Click the "define form field" link. This is the form field from which you want to take the data that is written to the profile property.
For this form field, complete these steps:
Enter a name for the form field in the "Name" text box. This is an internal name for the form field that you choose to use identify it — it is not the name of the form field in the source code.
Enter a valid jQuery Selector to define the form field. For complete information on jQuery Selectors, follow this link: https://api.jquery.com/category/selectors/
To define the form field using the Visual Picker, click Visual Picker.
Click OK.
Click the "define profile property" link. You can use an existing profile property or enter a new profile property name to create a new one here. See Profile properties for complete information on working with profile properties.
Click the "the surrounding form is submitted" link.
Select "Custom position is clicked".
Enter a name for the custom position in the "Name" text box.
Enter a valid jQuery Selector to define the custom position in the "Selector" text field. For complete information on jQuery Selectors, follow this link: https://api.jquery.com/category/selectors/
To define the position using the Visual Picker, click Visual Picker.
Click OK.
If you want to convert the value, see the instructions in "Converting values" below for complete information on configuring value conversion.
Repeat the steps above for each listen rule of this type you want to create.
Click Save.
Writing data to a profile property when a location hash changes
Click Add rule.
Select whether this rule is an add or set operation. An add operation keeps the existing data in the profile property and adds the new data to it. A set operation substitutes the existing data with the newly submitted data, unless the "only if empty" option is checked.
Select whether this rule deals with text or a value.
Click the "define form field" link. This is the form field from which you want to take the data that is written to the profile property.
For this form field, complete these steps:
Enter a name for the form field in the "Name" text box. This is an internal name for the form field that you choose to use identify it — it is not the name of the form field in the source code.
Enter a valid jQuery Selector to define the form field. For complete information on jQuery Selectors, follow this link: https://api.jquery.com/category/selectors/
To define the form field using the Visual Picker, click Visual Picker.
Click OK.
Click the "define profile property" link. You can use an existing profile property or enter a new profile property name to create a new one here. See Profile properties for complete information on working with profile properties.
Select the option "Location hash name" to execute the listener rule whenever the hash part of the location or URL changes to a value you specify in the Location hash name field.
Click OK.
Choose whether to convert the value. If you want to convert the value, see the instructions in "Converting values" below for complete information on configuring value conversion.
Repeat the steps above for each listen rule of this type you want to create.
Click Save.
Converting values
Before committing text or a value to a profile property, you can convert it based on a defined mapping. You might want to do this in cases where you want to write a different value to a profile property than what was taken from the form field. For example, if a drop-down list in a form has two choices, "Male" and "Female", but you want to write "M" or "F" to the profile property, you can create a value conversion mapping to do this.
To convert text or a value based on a mapping, follow these steps:
Click the "do not convert the value" link.
Select "Convert based on mapping".
In the "Original value" text field, enter the text or value from the form field you want to convert.
In the "Converted value" text field, enter the text or value you want to convert the original text or value to.
Click Save mapping.
Repeat the steps above for each mapping that you want to define.
Click OK.
To delete a mapping, click the delete icon to the right of the mapping.
FAQ
Why isn't my form listener picking up data after a form is submitted?
This is a common issue related to how BlueConic listeners and form submissions interact on a webpage. Typically, a Listener executes once upon the initial page load. If your form updates the data layer after the page has already loaded, the listener won't automatically re-check it. To fix this, you need to manually trigger a new pageview event using BlueConic's front-end JavaScript API. You can do this by adding the following line of code to the process that updates your data layer on form submission: blueConicClient.handlePageView();
Why isn’t my form submission data being added to BlueConic profiles?
If data from a form submission is not being merged into profiles, it may be because the listener that captures identifiers only runs on page load. When a visitor submits a form and then immediately leaves the page, the listener does not have a chance to update the profile with the identifier. To resolve this, configure the form to redirect users to a confirmation or success page after submission. This ensures a page load occurs, triggering the listener and allowing BlueConic to capture the identifier and merge the profile correctly.
Privacy management
Listeners can be added to Objectives, allowing for privacy management of the information that is being picked up. The listener will only update a profile if the visitor consented to at least one of the objectives that it is linked to.