◼️Forms

Form is an interactive data-collection tool used to gather information directly from end users for profile updates, surveys, accepting T&C’s and many more. You can build custom forms that automatically map answers to user profiles or store them as custom attributes, all in real-time using dedicated campaigns and powered by our segmentation engine.

Creating & Managing Form Assets

Before displaying any form to end users via a campaign or deep link, you must first create and configure a Form Asset.

📌 Where to Create Assets?

1. Navigate to the Marketing tab in the BO (Back Office).

2. Under the Assets subsection, select Forms and click Create to start setting up a new form template.

📌 Key Asset Configurations:

• Internal name - Used to identify and select the asset in campaigns.

• Status - Can be Active, Draft, or Archived.

• Allow direct form access - If enabled, it allows opening this form via deep link or JavaScript API without an active campaign. It’s recommended that you keep it disabled to prevent unauthorized manual triggers. Here is how to trigger:

  • Deeplink: dp:form&id=123

  • JS call: _smartico.showForm({ id: 123 })

• Target Segment - select a segment of users who will be allowed to trigger the form

Form Field configurations

You can add any number of fields which are presented as collapsible cards for easier navigation as well as options for quick reorder, clone, and delete. The setup will allow you to structure and validate the data collected from your users.

1. Data Mapping

Determines how submitted user responses are stored or applied in the system:

• Source:

  • Property: Connects the input directly to an existing user property (e.g., First Name, Birthdate, Language etc..).

  • Custom: Collects data independently without updating core profile fields. The custom property and the user-submitted value are passed in the payload of the form event.

• Property name: (When Source = Property) Select the existing user property this form field updates upon submission.

  • Let's take, for example, that you added a field connected to the user property for “first name”. When the user submits the form, the property will be overwritten with the value submitted by the user and will be automatically updated on his profile page:

• Custom key: (When Source = Custom) Write a custom property that is going to be exposed in the form event payload so that you can use it for mapping on your end:

  • Lets take for example that you added a field with a custom key set as favorite_game_type. When the user submits the form the value populated for that field will be exposed in the payload:

Note: Beware that using existing user state properties will change their value immediately on successful submission. We are not making validation of the submitted data. You can use Campaigns that trigger based on form events to insert additional steps or validation checks.

2. Field Content

Defines what the user sees in the form interface and handles localization:

• Field Title: The headline label displayed directly above the input field on the form UI.

• Field Type: Select the structural input format used to capture user entries:

  • Text: Free text input field.

  • Number: Numeric input field.

  • Select: Dropdown selection menu.

  • Checkbox: Binary agreement (e.g. yes/no)

  • Date: Calendar date selector.

Note: Selecting an existing Smartico property automatically populates the Field Type to match that property's data type.

3. Input Validation Constraints

To ensure high data quality and prevent invalid submissions, you can set specific validation constraints based on the chosen Field Type:

Text Validation (Character Limits)

• min length: The minimum number of characters required.

• max length: The maximum character boundary allowed.

• pattern (regex): Enforces specific text formatting (e.g., requiring letters only or specific alphanumeric patterns).

Number Validation (Value Range)

• min value: The lowest acceptable numeric value.

• max value: The highest acceptable numeric value.

• pattern (regex): Enforces specific number formatting rules (e.g, phone number, country code pattern)

What is Pattern Validation (Regex)?

While character limits control how much text someone can type and value ranges control how high or low a number can be, a Pattern (Regex) controls the exact structure of the data being entered.

Think of it as a smart blueprint or template. Instead of checking for an exact word, it checks whether the user's input matches a specific format, like checking if an email has an @ symbol or if a phone number has the right country code.

How to Define a Regex Rule

Regex uses special symbols as building blocks to create validation rules. You don't need to be a programmer to understand the basic pieces:

• ^ (Start): Forces the pattern to match from the beginning of the text.

• $ (End): Forces the pattern to match all the way to the end of the text.

• [a-z] / [A-Z]: Allows lowercase or uppercase letters.

• [0-9] or \d: Allows digits (numbers 0 through 9).

• +: Requires one or more of the preceding character type.

• {3} or {3,10}: Sets an exact length (e.g., exactly 3 digits, or between 3 and 10 characters).

Common Regex Patterns Cheat Sheet

Here are the most frequently used validation patterns you can apply to text and number fields:

1. Text & Character Formats

Goal / Requirement	Regex Pattern	Example Valid Inputs	Description
Letters Only (No spaces/numbers)	^[a-zA-Z]+$	John, Smith	Accepts uppercase and lowercase letters only.
Letters & Spaces (Full Names)	^[a-zA-Z\s]+$	Mary Jane, De La Cruz	Accepts letters and spaces, excluding special characters.
Alphanumeric Only (No special chars)	^[a-zA-Z0-9]+$	User123, A1B2C3	Allows letters and numbers only. Great for IDs or usernames.
Alphanumeric with Spaces	^[a-zA-Z0-9\s]+$	Building 4A, Suite 100	Useful for street addresses or internal codes.

2. Contact & Identity Information

Goal / Requirement	Regex Pattern	Example Valid Inputs	Description
Email Address	^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$	[e-mail], [e-mail]	Validates standard email formatting rules.
US Phone Number	^\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}$	[phone], 555-123-4567, 5551234567	Accepts 10-digit formats with flexible dashes/parentheses.
International Phone (E.164)	^\+[1-9]\d{1,14}$	[phone], [phone]	Requires a + symbol followed by country code and digits.
US ZIP Code	^\d{5}(-\d{4})?$	90210, 90210-1234	Accepts standard 5-digit ZIPs or 9-digit ZIP+4 formats.

Select Menu Items (Dropdown Options)

When configuring a Select field type, you must add and define the dropdown choices you want to have available to the user:

• Value: The raw (technical) value passed in the payload upon submission.

• Label: The presented text label displayed to the user in the UI dropdown.

Required field

Located at the bottom of each field configuration setup:

• Off: The field is optional; users can submit the form without completing it.

• On: Forces the user to complete or check the field before submitting the form. If left blank, a visual error warning will prevent form submission.

Form Content

The Form Content section gives you control over the visual presentation, structural markup, styling, and multi-language localization of the form. It features a side-by-side code editor and live visual preview, allowing you to tailor form designs to match your brand identity or gamification skin.

Note: The “Form Content” becomes available only once you save your newly created Form template.

What can you customize?

• Brand Styling: Modify CSS colors, fonts, paddings, border radii, and button states to match your brand skin.

• Localization: Define translations for headers, labels, placeholders, and action buttons across all supported brand languages.

  • Example:

const translations = {
"title_label": { 
        en: "We'd love to know you better", 
        pt: "", br: "", ro: "", ja: "", de: "", uk: "", fr: "", 
        fi: "", hy: "", au: "", el: "", ar: "", pe: "", cl: "", za: "" 
    }
}

• HTML Layout: Add helper text, tooltips, brand logos, or re-order visual elements.

• Live Preview: Test visual changes instantly in the right-hand preview panel before saving.

The "Regenerate" Button

If you’ve been making a lot of changes to your Form, tweaking HTML, adjusting CSS, or shifting layouts around, and realize things have gotten a bit messy, you can use the Regenerate button to start fresh. This will instantly reset the form back to its standard default view. However, please keep in mind that clicking Regenerate will completely overwrite all of your customized HTML and CSS (including localization), restoring everything back to the original template layout. This action is permanent and cannot be undone.

Edit with Vibe studio

Use Vibe Studio to completely customize your forms using simple, conversational prompts. Instead of manually tweaking code or navigating complex design settings, simply describe what you want in the chat, and the AI will generate and apply updates to your live preview in real time.

You can easily update visual themes and colors, automatically generate and embed custom graphics, upgrade inputs add multi-language support and so much more in seconds.

Submissions tab

The Submissions tab allows you to view, search, and audit all individual responses gathered from end-users.

• Overview: View the user's details, exact submission timestamp, and total count of completed fields.

• Expanded Details: Click any submission row to expand it and reveal every individual field filled out during that session alongside its submitted value (e.g., phone numbers, T&C acceptance flags, or dropdown choices).

Click the export icon in the upper-right corner of the table to export your filtered submission records for offline auditing or custom reporting.

Forms in Campaign

Once a form asset is created it can be triggered within your campaigns by attaching the Form activity directly to your gamification, communications or other flow activities.

Forms in Data Warehouse

Comprehensive form data is now available in the DWH. You can access structure, interaction, and submission data using the following views:

• Form Definitions: Contains the setup and structural details of your forms.

• Form Views: Tracks user interactions and when forms are viewed.

• Submitted Data: Contains the actual data and responses submitted by users.

Working with forms from JavaScript

Front-End Callbacks (_smartico.on)

When a form is displayed (via a campaign trigger or _smartico.showForm(...), the Smartico library emits browser-side events. Subscribe to these events using _smartico.on(...) to react to form interactions or render submitted data in your UI.

Subscribing to Events

// Fires when a form is displayed to the user
_smartico.on('form_viewed', function (data) {
  // data = { id: <form_id> }
  console.log('Form shown:', data.id);
});

// Fires when the user successfully submits a form
_smartico.on('form_submitted', function (data) {
  // data = { id: <form_id>, fields: { <field_key>: <value>, ... } }
  console.log('Form', data.id, 'submitted:', data.fields);
  // e.g. render data.fields in your own UI
});

Event Payloads

• Form Viewed

  • Key: form_viewed

  • Fires: When the form is rendered.

  • Payload: { id } - id is the Form ID from the Back Office.

• Form Submitted

  • Key: form_submitted

  • Fires: After a successful submit.

  • Payload: { id, fields } - fields is a map of field_key: value pairs as configured in the Back Office.

Targeting a Specific Form

There is a single handler per event type. If you show multiple forms, filter by data.id:

_smartico.on('form_submitted', function (data) {
  if (data.id === 123) { 
    /* Handle form 123 submit */ 
  }
});

Unsubscribing

Remove event listeners using _smartico.off(...):

function onSubmit(data) {
  /* ... */
}

// Subscribe
_smartico.on('form_submitted', onSubmit);

// Unsubscribe
_smartico.off('form_submitted', onSubmit);