Events

Overview

Event listeners in the Givebutter platform enable you to respond to various actions and states within the widget lifecycle - from the moment a widget is loaded to when a user completes a donation. To interact with these events, you'll use the window.Givebutter object.

Event Details

When handling events with Givebutter, each event provides a details argument containing specific information relevant to that event. Here's a detailed look at the kind of information you can expect.

CommonEventDetail

All events include common information that helps identify the context of the event.

{
  // Details about the associated campaign
  campaign: {
    code,
    name,
  },
  // UTM parameters for tracking marketing effectiveness.
  utm: {
    source,
    campaign,
    medium,
    content,
    term,
  }
  // Information about the widget triggering the event.
  widget: {
    id,
    type
  }
}

CheckoutDetail

For events related to the checkout process, such as starting or completing a donation, the details argument will include additional info.

{
  // Information about the individual making the donation.
  supporter: {
    id,
    email,
    firstName,
    lastName,
    mailingListSubscribed,
  },
  // Details about the donation
  donation: {
    source,
    campaign,
    medium,
    content,
    term,
  }
}

Library Events

Library events are global events and can be listened to at any point in your application. These events provide hooks into key lifecycle moments and user actions across all widgets.

WidgetLoaded

Fires when any Givebutter widget has finished loading.

Name: widgetLoaded
Constant: GlobalEvents.WidgetLoaded
Parameters: details (CommonEventDetail)

window.Givebutter.on('widgetLoaded', function(details) {
    // Handle the event, e.g., analytics tracking
});

CheckoutStarted

Fires when a checkout process starts in any widget.

Name: checkoutStarted
Constant: GlobalEvents.CheckoutStarted
Parameters: details (CheckoutDetail)

window.Givebutter.on('checkoutStarted', function(details) {
    // Execute actions when checkout starts
});
);

CheckoutCompleted

Fires when a checkout process is completed successfully.

Name: checkoutCompleted
Constant: GlobalEvents.CheckoutCompleted
Parameters: details (CheckoutDetail)

window.Givebutter.on('checkoutCompleted', function(details) {
    // Actions after a successful donation
});

Widget Events

Widget events are specific to individual widgets. This allows for granular control and response to user interactions within a particular widget instance.

All Widgets

Loaded

Fires when any widget instance has completed its initial loading and setup.

Name: loaded
Constant: WidgetEvents.Loaded
Parameters: details (CommonEventDetail)

const myWidget = Givebutter.widgets.get({id: 'yourWidgetId'});
myWidget.on('loaded', function(details) {
    // Actions to take once the widget is fully loaded
});

Button

Clicked

Fires when the button is clicked.

Name: clicked
Constant: ButtonEvents.Clicked
Parameters: details (CommonEventDetail)

const myButton = Givebutter.widgets.get({id: 'yourButtonId'});
myButton.on('clicked', function(details) {
    // Respond to the button click
});

Opened

Fires when the button opens the Giving Form.

Name: opened
Constant: ButtonEvents.Opened
Parameters: details (CommonEventDetail)

const myButton = Givebutter.widgets.get({id: 'yourButtonId'});
myButton.on('opened', function(details) {
    // Execute actions when the modal opens
});

Closed

Fires when the button is used to close the Giving Form.

Name: closed
Constant: ButtonEvents.Closed
Parameters: details (CommonEventDetail)

const myButton = Givebutter.widgets.get({id: 'yourButtonId'});
myButton.on('closed', function(details) {
    // Handle the modal close
});

Giving Form

CheckoutStarted

Fires when a user starts the checkout process in the Giving Form.

Name: checkoutStarted
Constant: GivingFormEvents.CheckoutStarted
Parameters: details (CheckoutDetail)

const myForm = Givebutter.widgets.get({id: 'yourFormId'});
myForm.on('checkoutStarted', function(details) {
    // Actions when checkout starts in the form
});

checkoutCompleted

Fires when a user finishes the checkout process in the Giving Form.

Name: checkoutCompleted
Constant: GivingFormEvents.CheckoutCompleted
Parameters: details (CheckoutDetail)

const myForm = Givebutter.widgets.get({id: 'yourFormId'});
myForm.on('checkoutCompleted', function(details) {
    // Respond to successful donation via the form
});

Goal Bar

updated

Fires when the Goal Bar is updated with changes in the amount raised or progress towards the goal.

Name: updated
Constant: GoalBarEvents.Updated
Parameters: details (CommonEventDetail)

const myGoalBar = Givebutter.widgets.get({id: 'yourGoalBarId'});
myGoalBar.on('updated', function(details) {
    // Execute actions when the goal bar updates
});