CharityEngine Donation form Event Listener

The CharityEngine event listener can be used with Google Tag Managers or other TMS to track completed donations using the CharityEngine form, allowing you to measure these critical conversions in your analytics tools like Google Analytics (GA4), Piwik Pro, Matomo, etc. and advertising platforms such as Google Ads, Meta ads conversion tracking, etc.

How to track CharityEngine embedded donation form conversions with google tag manager

You can track CharityEngine (CE) donation form interactions such as when a form is opened, successfully completed, or fails using Google Tag Manager (GTM).

By listening for specific CharityEngine events emitted by the CharityEngine event listener, you can capture key donor actions and send them to your analytics and advertising platforms, such as Google Analytics (GA4), Facebook Pixel, and Google Ads. This allows you to measure the success of your donation forms and optimize your campaigns accordingly.

Before proceeding, note that this method relies on the CharityEngine API (CE_API), which is used to trigger events during donation form interactions. The integration works seamlessly with CharityEngine’s Quick Action Donation Forms.

Setup Process:

Creating a Custom HTML Tag in GTM:
- The process begins by creating a Custom HTML tag in Google Tag Manager. You’ll add the CharityEngine event listener code to this tag.
- Ensure this tag is triggered when the page is fully loaded, ideally using a DOM-Ready trigger or a similar event that ensures the form has loaded.
Listening for CharityEngine Events:
- Event Names to Track: The key events to track include:
  - DonationFormOpened: Tracks when the donation form is opened.
  - DonationFormClosed: Tracks when the donation form is closed.
  - DonationSucceeded: Tracks when a donation is successfully processed.
  - DonationFailed: Tracks when a donation attempt fails.

These events are triggered by the CharityEngine platform when users interact with the donation form. The CE_API listens for these events and triggers a push to the dataLayer whenever one of them occurs.

Mapping Events to Human-Readable Descriptions:
- To make the data meaningful, human-readable descriptions are assigned to each event:
  - DonationFormOpened becomes open quick action donation form.
  - DonationSucceeded becomes quick action donation successful.
  - DonationFailed becomes quick action donation failed.
  - DonationFormClosed is mapped as close quick action donation form.

This makes it easier to interpret the events in your analytics platforms.

Creating Custom Triggers and Tags in GTM:
- Set up Custom Event Triggers in GTM for each of the CE events:
  - For example, create a trigger that listens for the ce_quick_action_form_event event and when the “ce_event_name” dataLayer attribute key DonationSucceeded event occurs.

By setting up these tags and triggers, you can track successful donations, donation attempts, form opens and closes, and much more.

Testing Your Implementation:
- Before publishing your GTM container, thoroughly test your setup using GTM’s Preview Mode. This ensures that events are being captured correctly and that your tags are firing as expected.

<script>
window.dataLayer = window.dataLayer || [];
// Define human-readable descriptions for each CE event
var ceEventActionMap = {
  'DonationFormOpened': 'open quick action donation form',
  'DonationFormClosed': 'close quick action donation form',
  'DonationSucceeded': 'quick action donation successful',
  'DonationFailed': 'quick action donation failed'
};
// Define relevant event names
var ceEventNames = [
  'DonationFormOpened',
  'DonationFormClosed',
  'DonationSucceeded',
  'DonationFailed'
];
// Register a listener for each CE event
ceEventNames.forEach(function(eventName) {
  if (typeof CE_API !== 'undefined' && typeof CE_API.AddListener === 'function') {
    CE_API.AddListener(eventName, function(result) {
      // Push structured event to dataLayer
      window.dataLayer.push({
        event: 'ce_quick_action_form_event',
        ce_event_name: eventName,
        ce_event_action: ceEventActionMap[eventName] || '',
        ce_event_data: result || null // Optional payload from CE (e.g., Transaction_Id)
      });
    });
  } else {
    console.warn('CE_API not available or CE_API.AddListener is undefined');
  }
});
</script>

Video of how to use the listener

Related Event Listener

Forminator

Use this Forminator event listener to track both successful Forminator form submissions and failures.

Omnisend

Capture the Omnisend form interactions and successful submissions and execute your marketing pixels.

Typeform

Ensure you always complete all Type form conversions by monitoring successful Type form submissions made by users.

download the google tag manager recipe for tracking CharityEngine embedded donation form conversions

we make you smarter with data

made with ❤️

The DumbData Team