Qgiv’s Analytics API allows for seamless integration of Qgiv forms with various external applications and tracking tools, such as Google Tag Manager, Google Analytics 4, Meta Pixel, and others. This allows you to monitor and analyze Qgiv conversion events, optimizing your fundraising efforts through effective data collection and analysis.

The API uses the dataLayer, a JavaScript object that captures and transmits information on your Qgiv forms. When a Qgiv event is triggered, the relevant data is automatically pushed to the dataLayer, making it accessible for tracking and deeper insights.

This article explains the different events and parameters that you can track using the Qgiv data layer. 

Pro tip: Throughout this article, “events” refers to actions that can occur on a webpage, which you can track.

Check out this article to learn how to connect an analytics service to Qgiv via the Service Integrations landing page.

Contents: 

• JavaScript Events
• Parameters Reference
• Payload Structure
• JavaScript Event System
  • Custom Fields
  • Testing Custom Events

JavaScript Events

Qgiv creates JavaScript “events” based on the state of the Qgiv form. Our Qgiv events include the following:

• Page view  QGIV.pageView - Triggered when a form is loaded, when a user navigates between steps, and upon completion of a donation.
• Donation started QGIV.donationStart - Triggered when a donation form is loaded.
• Donation step change QGIV.donationStepChange - Triggered when a user navigates between steps in a donation form.
• Donation completed QGIV.donationComplete - Triggered each time a donation is successfully completed.
• Donation abandoned QGIV.donationClose - Triggered when a user exits a donation form without completing the donation process.
• Registration started  QGIV.registrationStart - Triggered when a registration form is loaded.
• Registration step change QGIV.registrationStepChange - Triggered when a user navigates between steps in a registration form.
• Registration completed QGIV.registrationComplete - Triggered each time a registration is successfully completed.
• Registration abandoned QGIV.registrationClose - Triggered when a user exits a registration form without completing the registration process.
• Transaction completed QGIV.ga4Purchase - Triggered when a user completes a transaction, formatted to be compatible with Google Analytics 4’s purchase event.

Events push payloads to the dataLayer on the webpage where the donation form is embedded. If the form is deployed on a Qgiv Landing Page, the payloads are added to that page's dataLayer. If the form is a widget on an external domain, the payloads are added to the external webpage’s dataLayer, allowing for data collection across most analytics tools added to the website.

Custom Qgiv Events include a payload with a structure designed by Qgiv, while the QGIV.ga4Purchase event adheres to the Google Analytics 4 purchase event format.

Parameters Reference

Here are the various data points that may be present when users interact with your forms. Which parameters you see will depend on the products you’re using and tracking:

Payload Structure

The payload for each Qgiv event follows this standardized structure:

{
    QGIV: {
      form: {...},
      contact: {} || {...},
      customFields: {} || {...},
      dedication: {} || {...},
      restrictions: {} || {...},
      transaction: {} || {...},
      utm: {},
    }
}

Here’s a breakdown of each key and whether or not you should expect an empty object {} or an object with data inside of it {...}:

• form: This object always contains keys for all of the events.
• contact: This object always contains keys for all of the events.
• customFields: This object only contains keys when a custom field has been filled out.
• dedication: This object only contains keys when a donor has selected a dedication.
• restrictions: This object only contains keys when a donor has selected a restriction.
• transaction: This object only contains keys when a transaction has been completed.
• utm: This object is always empty as it is just a placeholder object that will at some point in the future be used to collect data related to UTM tracking.

JavaScript Event System

In addition to pushing data to the dataLayer, the JavaScript event system allows you to run custom code when specific events are triggered during the donation or registration process. This system enables developers to create more dynamic integrations by responding directly to key form actions through JavaScript.

Custom Fields

You can extend Qgiv's event system to include custom fields, ensuring they are pushed to the dataLayer when events like donationComplete or donationStart are fired.

Here’s an example of how you might set up some custom code for events on your forms:

QGIV.on('donationComplete', function(details) {
  var transid = QGIV.transaction.id;
  var amount = QGIV.transaction.total;
  var frequency = QGIV.transaction.frequency;
  // Push custom fields to data layer
  dataLayer.push({
    'event': 'donationComplete',
    'transid': transactionid,
    'amount': amount,
    'frequency': frequency
  });
});

Testing Custom Events

Use your browser’s console to test and ensure that the custom fields are being tracked and pushed to the dataLayer correctly. This is helpful for troubleshooting.

Here’s an example of how you might set up some custom code for events: 

QGIV.on('donationComplete', function(details) {
  console.log('Donation Complete!');
  console.log('Donation Details:', details);
  // Add your custom code here
});