Implement Ninja Forms integration

[hussain-t]

Feature Description

Implement Enhanced Conversions support by hooking into the ninja_forms_after_submission event. This enables Site Kit to capture and send user data submitted via Ninja Forms for improved conversion attribution.

Refer to the Plugin Event Integration for more details.

---

Do not alter or remove anything below. The following sections will be managed by moderators only.

Acceptance criteria

• When a supported conversion event (e.g., form submission) occurs via Ninja Forms, Site Kit should track the event and include any available user data (e.g., email, name, phone) in the event payload.
• The event should be sent using Site Kit’s internal gtagEvent mechanism.
• The user data should be normalized but not hashed, following the official Google guidelines for normalization.
• User data should only be included if it can be reliably extracted.
• User data should be sent if it has at least one supported field.
• User data shouldn't be sent if it has no supported fields.
• This behavior should only occur when the gtagUserData feature flag is enabled.
• Refer to Enhanced Conversions Fields Reference for the full list of supported fields.

Implementation Brief

In assets/js/event-providers/ninja-forms.js:

• Leverage the existing submit:response event listener already present in the file.
• If the gtagUserData feature flag is enabled using the isFeatureEnabled utility, add logic inside the event handler to:
  • Locate the actionSubmit handler and receive the data object from the event.
  • Read the submitted form from data.fields (a custom object that contains the form fields).
  • Iterate the fields object to extract user data.
  • For each field, use the classifyPII utility function (implemented in Implement unified PII classifier for plugin form event data for ECEE #11252) to determine if it contains PII.
  • The classifyPII function returns either null or { type: 'email' | 'phone' | 'name' | 'text', value: <normalized> }.
  • If the value wasn't normalized, normalize it using the normalizeValue / normalizeEmail / normalizePhone utility functions (implemented in Implement unified PII classifier for plugin form event data for ECEE #11252).
  • Only include names when the field metadata clearly indicates first name or last name (e.g., tokens like first-name, fname, last-name, name, lname). This will be classified as name by the classifyPII function.
  • If there are more than one name fields, treat the first one as the first name and the second/last one as the last name.
  • If there is only one name field, treat it as the full name and attempt to split into first_name and last_name using a space delimiter.
  • If the name field is not normalized, normalize it using the normalizeValue utility function.
  • Structure the user_data object using the following supported fields in Enhanced Conversions (if available):
    • email
    • phone_number
    • address.first_name
    • address.last_name
  • Inject the collected user data into the gtagEvent call with the key user_data, like so:

    global._googlesitekit?.gtagEvent?.( 'submit_lead_form', {
        user_data: { ...normalizedUserData }, // Injected user data for Enhanced Conversions
    } );

  • Do not pass the user_data property if no valid user data is available.
  • Pass the user_data even if it contains only one supported field.

Test Coverage

• No new tests are needed.

QA Brief

• Set up Site Kit with Analytics/Ads and enable conversion tracking.
• Enable the gtagUserData feature flag.
• Install Ninja Forms and set up a few forms:
  • A form without any PII fields (no names, email, or phone).
  • A form with all PII fields (First name, Last name, Email, Phone number).
  • Some forms with incomplete PII (e.g., first name only, first name + email only, email only, etc.).
• Using Tag Assistant, verify the data_layer of the submit_lead_form event:
  • A form with all PII fields should add a user_data object to the Data Layer with the following format:

    {
      "address": {
        "first_name": "...",
        "last_name": "..."
      },
      "email": "...",
      "phone_number": "..."
    }

  • A form without any PII fields should not add the user_data object.
  • A form with only a subset of fields should add the user_data object, but without any of the missing PII fields.
    • In other words, the properties of user_data should never contain undefined or an empty string ("") as a value.

Changelog entry

• Add Enhanced Conversions support for Ninja Forms by capturing and sending user data.

[techanvil]

AC ✅

[nfmohit]

Thank you for drafting the IB, @hussain-t!

• Extract the submitted form data from data.fields_by_key object.

• Attempt to retrieve user data (e.g., email, name, phone, address) by:

  • Preferably reading from the data.fields_by_key payload, if available.

Let's expand on this a little bit. In this object, the field keys may be ambiguous or not exact, for example:

In this case, we may use the type property of the field to determine what type of field it is for classification.

Falling back to querying known input field selectors in the form DOM.

Let's not rely on this here as the data is available through the event. WDYT?

Let me know what you think, thanks!