Using the JavaScript API

This document describes how to work with Fundraise Up's Javascript API. Our API allows for the detection of processing events related to the Fundraise Up Checkout.


Main Script

The principal integration code snippet must be installed on every page of your website. This loads the main Fundraise Up script and is required for working with Fundraise Up Elements and launching the Checkout experience. The Account ID (in bold below) would be replaced with your Account ID. If you're already accepting donations via FRU, then this script is already installed.

<!-- Fundraise Up -->
<script>(function(w,d,s,n,a){if(!w[n]){var l='call,catch,on,once,set,then,track'
.split(','),i,o=function(n){return'function'==typeof n?o.l.push([arguments])&&o
:function(){return o.l.push([n,arguments])&&o}},t=d.getElementsByTagName(s)[0],
j=d.createElement(s);j.async=!0;j.src='https://cdn.fundraiseup.com/widget/'+a;
t.parentNode.insertBefore(j,t);o.s=Date.now();o.v=4;o.h=w.location.href;o.l=[];
for(i=0;i<7;i++)o[l[i]]=o(l[i]);w[n]=o}
})(window,document,'script','FundraiseUp','AXXXXXXX');</script>
<!-- End Fundraise Up -->

The best approach is to install this line right after opening <head> section of the webpage.

 


API Syntax

Events

You can subscribe to Fundraise Up events using following syntax:

<script>
FundraiseUp.on('checkoutOpen', function(details) {
console.log(details.campaign);
});
</script>

Currently our API supports these select event types:


checkoutOpen

This is fired every time user opens Checkout clicking on Element or using direct link.

Typical details content.

{
"campaign": {
"id": "FUNXXXXXXXX",
"code": "MYCODE",
"name": "My campaign name"
},
"customFields": {
"source": "Twitter"
},
"utm": {
"source": "Twitter",
"campaign": "",
"medium": "",
"term": "",
"content": ""
},
"livemode": true,
"element": {
"id": "XXXXXXX1",
"type": "Donate Button",
"name": "Donate Button - Main Header"
}
}


checkoutClose

This is fired the moment a user closes Checkout, regardless of whether a donation has been made or not.

Typical details content:

/**
* Successful donation
*/
{
"campaign": {
"id": "FUNXXXXXXXX",
"code": "MYCODE",
"name": "My campaign name"
},
"donation": {
"id": "DXXXXXX1",
"amount": 105.4,
"feesCovered": 5.4,
"currency": "USD",
"recurring": true,
"paymentMethod": "Apple Pay"
},
"designation": {
"id": "EXXXXXX1",
"code": "GN1",
"name": "General"
},
"tribute": {
"type": "In Honor"
},
"supporter": {
"id": "SXXXXXX1",
"firstName": "Max",
"lastName": "Stein",
"email": "maxstein@example.com",
"mailingListSubscribed": true,
"anonymous": true,
"employer": "ACME Corp",
"onBehalfOf": "Microsoft"
},
"customFields": {
"source": "Twitter"
},
"utm": {
"source": "Twitter",
"campaign": "",
"medium": "",
"term": "",
"content": ""
},
"livemode": true,
"element": {
"id": "XXXXXXX1",
"type": "Donate Button",
"name": "Donate Button - Main Header"
}
}

/**
* Donation incomplete
*/
{
"campaign": {
"id": "FUNXXXXXXXX",
"code": "MYCODE",
"name": "My campaign name"
},
"donation": null,
"designation": null,
"tribute": null,
"supporter": null,
"customFields": {
"source": "Twitter"
},
"utm": {
"source": "Twitter",
"campaign": "",
"medium": "",
"term": "",
"content": ""
},
"livemode": true,
"element": {
"id": "XXXXXXX1",
"type": "Donate Button",
"name": "Donate Button - Main Header"
}
}


donationComplete

This is fired the moment a success donation is completed. This usually happens immediately after a credit card or payment method is entered/confirmed, or after entering an address on the Address screen (dependent on the configuration of checkout).

Typical details content:

{
"campaign": {
"id": "FUNXXXXXXXX",
"code": "MYCODE",
"name": "My campaign name"
},
"donation": {
"id": "DXXXXXX1",
"amount": 105.4,
"feesCovered": 5.4,
"currency": "USD",
"recurring": true,
"paymentMethod": "Apple Pay"
},
"designation": {
"id": "EXXXXXX1",
"code": "GN1",
"name": "General"
},
"tribute": {
"type": "In Honor"
},
"supporter": {
"id": "SXXXXXX1",
"firstName": "Max",
"lastName": "Stein",
"email": "maxstein@example.com",
"mailingListSubscribed": true,
"anonymous": true,
"employer": "ACME Corp",
"onBehalfOf": "Microsoft"
},
"customFields": {
"source": "Twitter"
},
"utm": {
"source": "Twitter",
"campaign": "",
"medium": "",
"term": "",
"content": ""
},
"livemode": true,
"element": {
"id": "XXXXXXX1",
"type": "Donate Button",
"name": "Donate Button - Main Header"
}
}

 


Custom Fields

Assuming you have configured custom fields for your campaigns, you can access all these data points with JS API through customFields function. 

For example, let's say your campaign uses the custom fields fund, appeal, and source. The events below get the values of those fields.

FundraiseUp.on('checkoutOpen', function(details) {
var fund = details.customFields.fund || '';
var appeal = details.customFields.appeal || '';
var source = details.customFields.source || '';
});

FundraiseUp.on('checkoutClose', function(details) {
var fund = details.customFields.fund || '';
var appeal = details.customFields.appeal || '';
var source = details.customFields.source || '';
});

FundraiseUp.on('donationComplete', function(details) {
var fund = details.customFields.fund || '';
var appeal = details.customFields.appeal || '';
var source = details.customFields.source || '';
});


Some custom field names are reserved for large enterprise clients and enabled on case by case basis.  Bellow are reserved names and possible values:

{
"customFields": {
"initialStateFeesCovered": "always|never|defaultYes|defaultNo",
"initialStateFrequency": "onetimeOnly|monthlyOnly|defaultOnetime|defaultMonthly",
}
}

 


Example

Optimizely. If you'd like to track successful donations into an Optimizely setup, we would use the following code:

<html>
<head>

<!-- Fundraise Up -->
<script>(function(w,d,s,n,a){if(!w[n]){var l='call,catch,on,once,set,then,track'
.split(','),i,o=function(n){return'function'==typeof n?o.l.push([arguments])&&o
:function(){return o.l.push([n,arguments])&&o}},t=d.getElementsByTagName(s)[0],
j=d.createElement(s);j.async=!0;j.src='https://cdn.fundraiseup.com/widget/'+a;
t.parentNode.insertBefore(j,t);o.s=Date.now();o.v=4;o.h=w.location.href;o.l=[];
for(i=0;i<7;i++)o[l[i]]=o(l[i]);w[n]=o}
})(window,document,'script','FundraiseUp','AXXXXXXX');</script>
<!-- End Fundraise Up -->

<!-- Some other scripts and styles are defined here -->

</head>
<body>

...

<!-- Here is my main donate button -->
<a href="#XXXXXXX1" style="display: none;"></a>

...

<script>

// Here is how we track donations
FundraiseUp.on('donationComplete', function(details) {

// This function will be fired right after successful donation

window['optimizely'].push({type: "event", eventName: "donation_completed"});
});

</script>

</body>
</html>