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 is my Form Listener not picking up values?
First, make sure that the form is actually part of the webpage and not hosted in an iframe. If the form is hosted in an iframe, then the only way to enrich the profile based on the visitor's input is to have the BlueConic script placed in the iframe as well.
Another important aspect to consider is how the form is handled by the site. Traditionally, forms are submitted using the HTML DOM form submit, which for example is triggered by clicking a 'submit button'. A lot of websites choose to prevent the default submit event and handle the form programmatically -- for example, by triggering an AJAX request to send the input data to the server and not have the page reloaded completely. The rules of the Form Listener need to be configured to fit the way the form is handled by the site.
Finally, there is the way the form is initially loaded into the page. Traditionally, the form is just part of the HTML body of the page. Some sites, however, especially sites that embrace the Single Page Interface model, choose to load the form dynamically, after the HTML body has loaded.
If you are not sure how the site is handling or loading the form, try the different rule variations to find the variation the works for you.
The different listen rule variations are:
Write data to a profile property when the surrounding form is submitted
This corresponds to the traditional way of submitting and loading forms.Write data to a profile property when a custom form is submitted
This also corresponds to the traditional way of submitting forms but lets you manually choose the form. Whenever the form is dynamically inserted into the page this should be the first variation to try.Write data to a profile property when a custom defined form is submitted
This variation should be used when the fields are not located inside the form that is programmatically submitted by the site. Either manually choose the position on the website or use the visual picker to select the form.Write data to a profile property when a custom position is clicked
This variation should be used when the form submit is handled programmatically by the site. You manually choose the position on the website, which after it is clicked should trigger a profile update.Write data to a profile property when the location hash changes
This variation should be used when the form submit is handled programmatically by the site and the URL in the browser is appended with a specific hash (e.g. "#success") as a result. Enter the hash name without the "#" so BlueConic can determine a successful submit has taken place.
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.