Manual Form Tracking in Ruler Analytics

Overview

Ruler's manual form tracking allows you to control when a form submission is sent to Ruler and exactly what information is included.

Manual tracking works by creating a JavaScript object called RAConv containing your form data and passing it to the Ruler tracking function:

RulerAnalytics.trackConversionAsync(RAConv, "", "", 500);

The RAConv payload is fully customisable, allowing you to send relevant information captured from your website, backend, or URL.

Basic Example

The following example shows a basic form submission payload:

var RAConv = { first_name: "John", last_name: "Doe", email: "[email protected]", phone: "07123456789", company: "Example Ltd", form_type: "contact_form"};RulerAnalytics.trackConversionAsync(RAConv, "", "", 500);

You can include additional fields that are relevant to your business and reporting requirements.

Recommended Identifiers

We recommend including at least one unique identifier in your payload.

The preferred identifiers are:

• Email – Recommended where available.
• Phone – Useful where a phone number is collected.
• Order ID – Useful for ecommerce or transactional forms.
• Unique ID – Such as a Customer ID, Lead ID, or another identifier used within your internal systems.

Ruler can use these identifiers to help match form submissions back to visitors and their marketing sessions.

They can also help connect your website activity with offline data captured in your CRM or other internal systems.

Important: Form events can be sent without an identifier, but this can limit Ruler's ability to match the event to an existing visitor or connect it with subsequent offline CRM data.

Customising the Payload

The Ruler payload is customisable. You can pass any relevant value that is available to your implementation, including data from:

• The website DOM
• Form fields
• Your backend
• URL parameters
• Other data available to your website

For example, you could include information such as:

var RAConv = { email: "[email protected]", phone: "07123456789", company: "Example Ltd", form_type: "contact_form", lead_type: "sales_enquiry", product_interest: "Enterprise"};

Only include information that is relevant to your reporting and data requirements.

Field Naming Recommendations

We recommend following a consistent naming convention when creating payload fields.

Use snake_case

For example:

first_nameform_typecustomer_idproduct_interest

Avoid Spaces and Special Characters

Use simple, descriptive field names rather than names containing spaces or special characters.

Keep Field Names Consistent

Use the same field name across different forms whenever the field represents the same piece of information.

For example, if you use:

customer_id

for one form, avoid using:

customerID

or:

customer_number

for the same type of data on another form.

Field names are treated as unique fields in Ruler. Changing a field name can therefore result in a new field appearing in your reporting rather than continuing to populate the existing field.

Accepted Data Types

Ruler supports common simple data types, including:

• Strings
• Numbers
• Email addresses

Email addresses should be provided as standard string values.

For example:

email: "[email protected]"

Validation

Ruler does not enforce a strict schema on manual form-tracking payloads. Payloads are generally accepted as provided by your implementation.

This means that incorrectly formatted values may still be accepted.

For example, an invalid email value may be recorded if your implementation sends it to Ruler.

Payload Structure

Ruler supports a flat payload structure.

Each field should be provided as a simple key-value pair.

For example:

var RAConv = { first_name: "John", email: "[email protected]", customer_id: "12345"};

Nested objects and arrays are not supported.

Avoid structures such as:

var RAConv = { customer: { first_name: "John", email: "[email protected]" }};

Instead, use individual fields:

var RAConv = { customer_first_name: "John", customer_email: "[email protected]"};

Recommended Limits

There are no strict limits that are typically enforced on the number or size of payload fields. However, for best performance and maintainability, we recommend:

• Keeping payloads to around 50 fields or fewer.
• Keeping field names to around 50 characters or fewer.
• Avoiding excessively large string values, particularly values greater than 1–2 KB per field.
• Only sending data that is relevant to your reporting or matching requirements.

Keeping your payload concise makes your implementation easier to maintain and your Ruler reporting easier to manage.

Getting Started

Review the below guides on implementing Manual form tracking based on your setup.

• Thank you Page tracking
• Form tracking via GTM
• On Submit Button tracking

Need Help?

If you have questions about manual form tracking, payload structure, or which fields you should send to Ruler, please contact a member of the Ruler team.