Embeddable Forms & Buttons for Nonprofits
In this article:
- Types of Embeds
- Creating an Embeddable Form or Button
- Customizing Embeddable Forms and Buttons
- Embedding Forms and Buttons in Your Website’s Code
- Using the WordPress Plugin for Embeddable Forms and Buttons
- Backup Form Settings
- Evaluating Embeds
- Embedding a Goal Tracker
- Advanced
Please Note: These tools are only available for admins of 501(c)(3) and 501(c)(4) nonprofit organizations. If you are an admin for a 501(c)(3) or (c)(4) and also a political campaign, you will only see the embed option on your 501(c)(3)’s or (c)(4)’s Dashboard.
Embeddable forms and buttons are donation features you can add directly to your webpage so donors never have to leave your site. Our embeddable forms and buttons take advantage of our ActBlue Express universe of donors, meaning that if a supporter has previously donated on our platform and saved their contact and payment information with us, their information will be prefilled in the embed in your webpage!
All three steps of the donation flow — contribution amount, payment information, and donor details — will occur within your embeddable form or buttons! Donors will also be able to give with PayPal™ in an embed, just like with regular contribution forms, but at this point in time, embeds cannot accept Apple Pay.
Because embeddable forms and buttons live in your website, some of the customization options for a regular contribution form do not apply, including titles and donation asks, goal thermometers, or brandings. You can preset your donation amounts, change the AB Charities-provided text to Spanish, add a custom field or radio button, ask for recurring contributions, customize the recurring upsell or the Smart Boost upsell, or write a custom recurring pitch for your embeddable forms and buttons!
We designed our embeddable forms and buttons to be as easy to use as possible – the only technical knowledge you need to use them is a way to edit your webpage’s source code! And if your website is on WordPress, we have a plugin that enables you to embed a form or button on your site in only a few clicks. Read on to learn more.
Types of Embeds
Embeddable forms:
Embeddable forms are contribution forms that are inserted directly into your webpage. The entire donation process, whether it be multistep for new donors or single-click for donors with saved payment accounts, takes place within the embeddable form in your site. This is what an embeddable form would look like in your webpage to an ActBlue Express donor:
Embeddable buttons:
Embeddable buttons are donate buttons you can insert into your webpage that launch a pop-up modal where the remainder of the contribution takes place. Embeddable buttons are a great option when your webpage has limited space, like in a navigation bar, menu, or hero area. This is what embeddable buttons would look like in your webpage:
And this is what the pop-up will look like when a donor clicks on a button. If a donor has an ActBlue Express account, their payment and contact information will already be filled in!
Creating an Embeddable Form or Button
Clicking on “Create form” in your Dashboard will lead you to the “Choose a form type” page, where you can select which form you would like to make as well as customize it.
Click “Embed Form” and begin filling in the basic information about your form.
Once you’re done filling out these fields, click “Next step” to fill out more details for this form, or click “Publish now” to go directly to the form editor. From there, you can navigate to the “Embed Generator” tab, where you can create your embeddable form or buttons and copy the code you will need to put on your website.
Once you’ve clicked on the “Embed Generator” tab, enter any URLs where you want to embed a form or buttons in the “Allowed URLs” field, with each URL separated with a comma. You will only be able to host embeds in the URLs listed here, and the URLs must be secure (start with https)!
Any valid domain name you include will be allowed to host your embeddable forms and buttons. If you add “https://www.example.com,” you’ll be able to include an embeddable form or button anywhere on example.com.
Once all of your URLs are entered, click “Publish” to save your work and continue creating your embeddable form or button!
Once you click “Publish,” the rest of your options will appear under “Step 2:”. Under “Type of Embed”, you can select either form or button!
At any point, you will be able to see a preview of your embeddable form or buttons on the right side of your screen. Make sure to click “Publish” to preview the most up-to-date version of your form or buttons!
Customizing Embeddable Forms and Buttons
When you select the type of embeddable object you would like to include in your site, you will have different options for customization!
Embeddable forms:
If you choose “Form,” you will see a “fixed height” box that is unchecked. By default, the embeddable form height is dynamic, which means donors will see the entire form on your website (the form will not have an internal scroll). If you prefer to set your own form height (which may create internal scrolling), check the “Fixed height” box and change the number in the “Height” field.”
You can also create refcodes for your embeddable form, which we recommend to help you collect useful data about where your donations are coming from! Once you enter your custom refcode, we will include it in the code which you will use to embed the form in your webpage.
To pick the donation amounts on your embeddable form, go back to the main menu of the form editor and select the “Preset donation amounts” tab.
Embeddable forms will always include an “Other amount” option. Publish your changes when you’re done setting your amounts to save them!
Embeddable buttons:
If you choose “Button,” you can change the amounts and look of your embeddable buttons in the “Embed Generator” tab!
First, if you would like to ask your supporters for recurring donations, choose the type of recurring ask you would like to present to your donors in the “Recurring” dropdown menu. The default recurring setting for embeddable buttons is “Donor Decides,” which gives donors the option to make their contribution one-time or recurring:
If you select “Recurring,” your embeddable buttons will only accept recurring donations, so there will be no one-time donation option in the pop-up modal. Since the donor will have already chosen to give a recurring contribution by clicking on one of your embeddable buttons, there will also be no recurring upsell after the donation. Your embeddable buttons will look something like this, so it is clear to your donors that they will be making a recurring contribution:
If you select “One-Time” from the “Recurring” dropdown menu, your embeddable buttons will only accept one-time contributions. Your donors will not see a recurring donation option in the pop-up modal, and they will not see an additional recurring upsell after they donate, even if you enable the upsell in the “Recurring settings” tab of the form editor.
Then, set specific amounts for your embeddable buttons in the “Preset amounts” field by separating each amount with a comma. If you’d like to include an “Other amount” option, check the box below the “Preset amounts” field!
You can either leave the buttons with just the amounts, or you can add a verb like “donate” to your embeddable buttons! If you’d like to include a verb, enter it in the “Button verb” field.
You can customize the color of your buttons and font by clicking the dropdown menus under “Color” and “Font Color.”
A hex color code is a series of numbers and letters (#XXXXXX) that specifies an exact color. We recommend using your brand’s specific hex colors for your button colors. This will make sure your embeddable buttons match the rest of your online presence and look professional! If you don’t know your hex color codes, you can use the color picker available in both dropdowns to select a shade that looks like one of your commonly used colors.
You can also change your font size and font weight – click on the dropdown beneath “Font Weight” to select between “Bold” and “Normal”!
You also have the option to change the border radius of your embeddable buttons in the “Border Radius” field. The border radius is the amount of rounding applied to the corners of the button. A border radius of 0 will result in sharp, 90 degree corners.
By clicking “Advanced,” you can use custom CSS to change how your buttons look. You can find more about this option in the “Advanced” section at the end of this article!
Finally, you can create custom refcodes for your embeddable buttons just like you can for embeddable forms!
Code Add-ons:
The Embed Generator can also include optional code to integrate with other popular platforms. For example, if you have a Facebook pixel on the page you are including an embeddable form on, you can choose to include the ‘Facebook Conversion Tracking’ add-on:
And if you are tracking Google Ads conversions to the page you are including an embeddable form on, you can pick the ‘Google Conversion Tracking’ add-on:
Other embed settings:
Once you’re happy with how your embeddable buttons or embeddable form look, you have a few other options that will apply to your embed. Exit the “Embed Generator” tab to go back to your embed’s form editor.
In the “Form customization” tab, you can change all of the standard ActBlue- or AB Charities-provided text on your embeddable form or your embeddable button’s pop-up modal to Spanish! This includes an embeddable form’s buttons, donation block helper text, donor information fields, the recurring option on your embeddable form or button pop-up modal, all ActBlue- or AB Charities-provided text in the recurring or Smart Boost upsell, standard contribution rules, and the ActBlue or AB Charities disclaimer. If you add verbs to your embeddable buttons , these will not be translated, because they are user-generated text.
In the “Form customization” tab, you can also add a custom input —a text field for donors to fill out, or radio buttons for donors to select — so you can collect additional information from your supporters on either your embeddable form or your embeddable button’s pop-up modal. You can learn more about this tool
here. Please note: For the most part, organizations will not need to gather more information and add steps to the giving process.
In the “Recurring settings” tab, you can customize your recurring settings. Please note: Some recurring settings for embeddable buttons live in the “Embed Generator” tab. If you selected “One-Time” or “Recurring” in the menu in that tab, the following list of recurring customizations will not apply to your buttons, and your supporters will not see any recurring upsell after they donate.
If you are creating an embeddable form, or embeddable buttons with the “Donor Decides” option selected in the “Embed Generator” tab, read on to learn about your customization options in the “Recurring settings” tab of the editor.
In the “Recurring” tab’s “Monthly recurring donations” dropdown menu, you can change the type of recurring ask and recurring upsell your donors see:
- If you select “Disabled,” there will be no recurring option in the embeddable object or recurring upsell.
- If you select “Specified duration,” your donors will see a recurring option on your embeddable object, and if they choose to make a one-time contribution, they will see a recurring upsell after they donate. In both cases, they will be prompted to customize the number of months their contribution will recur for.
- If you select “Unlimited,” your donors will see a recurring option in the embeddable object, and if they choose to make a one-time contribution, they will see a recurring upsell after they donate. They will not be prompted to specify a number of months, and their contribution will recur until they cancel it or change the recurring schedule in their ActBlue Express account.
- If you select “Unlimited + Smart Options,” your donors will see a recurring option in the embeddable object, and if they choose to make a one-time contribution, they will see a recurring upsell after they donate suggesting multiple smaller recurring amounts. They will also have the option to set their own amount! To learn more about Smart Recurring and see examples, read this article. Please note: Smart Options is the only Smart Recurring option for embeddable forms and buttons.
Please note: If you select “Smart Boost” in the “Post-donation upsells” tab, your donors will not see any recurring upsell, even if you have one of the above options enabled.
In the “Pop-up recurring ask threshold” box in the “Recurring settings” tab, you can create a donation threshold for who should get a recurring upsell if you are using the “Specified duration” or “Unlimited” setting described above. Supporters who give a one-time donation smaller than the amount you enter in this field will see a recurring upsell asking them to make a monthly donation of the same amount that they just gave as a one-time donation. If you want any of your donors to see a recurring upsell, you must enter an amount in the “Pop-up recurring ask threshold” box.
Quick tip: click “Publish” to preview what the recurring ask will look like on your embeddable form or embeddable button’s pop-up modal!
You can also manage other recurring settings in this tab. If you select “Recurring pitch” in the “Promote recurring donations” dropdown menu, you can write a custom recurring pitch to highlight the recurring option on your embeddable forms and embeddable button pop-up modals.
In the “Thanks and receipt” tab, you can write the text that will appear at the top of donors’ email receipts.
In the “Post-donation upsells” tab, you can select the type of upsell you would like your donors to see after they give an initial contribution. If you select “Recurring,” customize these settings in the “Recurring settings” tab (and if you’re creating embeddable buttons, in the “Embed Generator” tab).
If you select “Smart Boost,” an upsell will present donors with multiple options to increase their initial donation, giving your supporters the choice to double their contribution or increase it by a smaller amount than the amount they just gave. You can customize the Smart Boost upsell title and ask to let donors know why you would like them to increase their impact in the “Post-donation upsells” tab.
Donors will still see the Smart Boost upsell if they make a recurring donation through one of your embeddable buttons or your embeddable form. However, Smart Boost will not add on to the recurring contribution amount, only the initial contribution. So if they donate a recurring amount of $5, and then choose to increase their donation by $1 in the Smart Boost upsell, their first charge will be for $6. But their future recurrences will be $5!
Remember to always publish changes you make in the form editor!
Embedding Forms and Buttons in Your Website’s Code
Return to the “Embed Generator” tab to generate the code you need to embed a form or buttons in your webpage!
At the bottom of the tab, click “Generate Embed.”
The resulting pop-up will have the code you need to paste into the source code (HTML) of your webpage – you can insert it wherever you would like your embeddable buttons or form to appear! Our engineers have included some helpful info in this pop-up if you’re new to editing HTML.
Note: You can include multiple embeddable buttons and forms in a single webpage. The<script> tag only has to be included in the <head> once per page, and then you can copy and paste the different <div> tags where you would like your embeddable buttons and forms to display in your webpage.
Using the WordPress Plugin for Embeddable Forms and Buttons
If your website is hosted on WordPress, you can embed your contribution form or donation buttons in a matter of clicks. Just download our “ActBlue Contributions” plugin in the WordPress plugin directory and search for the “ActBlue Embed” or “ActBlue Buttons” blocks in the WordPress editor. Full instructions can be found in this support article!
Backup Form Settings
The rest of the form editor, which you can find under “Backup Form Settings,” does not apply to your embeddable form or embeddable buttons. These settings will apply to your backup form, a regular contribution form which your donors will be sent to if something prevents your embed from working.
There are limited customizations available for backup forms. It is most important to customize the title and donation ask on your backup form so donors know they are still giving to you even if the embed does not work and they leave your site. You can write these in the “Title, ask, and URL” tab.
To learn more about the rest of the settings for your backup form, check out our article on the basics of customizing forms. Backup forms do not support multiple recipients (Tandem Fundraising), tracking, or Entry Mode.
Evaluating Embeds
To see how your embed is doing, go to the “Contribution Forms” tab of your Dashboard toolbar like normal. The backup form for your embeddable form or buttons will be here with the rest of your forms, and you can even filter the list by “Embed” to find your form more quickly:
Select the Contributions or Amount total for your backup form to be taken to its Statistics page. You can also quickly get to the Statistics page when you’re previewing your backup form by selecting the “Stats” button in the form navigation bar:
You can also set up email alerts for contributions or refunds for both embeddable forms & buttons like normal in the “More” dropdown of the navigation bar! Data from both embeddable buttons and forms will also show up in the rest of your Dashboard data, like normal (including your Overview and all of the tabs in the Tools and Insights sections of the Dashboard toolbar).
More questions? You can schedule a call with one of our nonprofit experts here.
Embedding a Goal Tracker
You can also embed a goal tracker on your website or email. For instructions on how to embed your goal tracker, click here!
Advanced
Tracking Embeds
Embed statistics can be found on the Statistics page for the associated contribution form. We can track visits and contributions.
Visits are tracked a little differently from standard ActBlue contribution form reporting. A visit to an embeddable form will be tracked by ActBlue if a potential donor interacts with an embeddable object. This interaction can either occur by clicking on an embeddable button and loading the modal or clicking anywhere on the embed form iframe. This data can be paired with your own website traffic data to get a full idea of your end-to-end conversion.
You can pass a refcode into the embed, either through an attribute on the embed div or through a URL param.
Refcode inheritance:
data-ab-refcodeabConfigure({refcodes: {refcode: ‘refcode’}});- URL params:
ab_refcoderefcoderef
Refcode2 inheritance:
data-ab-refcode2abConfigure({refcodes: {refcode: ‘refcode’}});- URL params:
ab_refcode2refcode2
In order to track events, just add a function to your actBlueConfig object:
<script>
abConfigure({onContribute: function(contribution) {
// tracking code goes here
}};
</script>
onContribute:
Called with contribution that includes:
- amount: the amount, in cents, that was donated
- email: the email of the donor
- name: the name of the form (the slug that appears in the URL)
- order_number: the ActBlue contribution order number
- recurring: whether the donor chose recurring
- refcode: the refcode of the contribution
actblue
actblue is a new global object on window that allows you to interact with ActBlue’s embeddable form functions from a host website. Provided by the actblue.js script tag.
actblue.requestContribution: function that accepts an object with amount in cents and token and will open a modal to ask the user for a contribution. It returns a promise that resolves with a contribution if the user completes the contribution. The promise will reject if the user closes the modal without making a contribution.
For example:
actblue.requestContribution({amount: 1000, token: ‘abc123’});
You can look up a token from the “Generate Embed” button in the “Embed Generator”:
abConfigure(configuration):
Configure all embeds on the page, with new refcodes, a different language, and more. See the reference for all options.
API Reference
<div data-ab-button /> parameters:
data-ab-token: the token for the embed, retrieved from the generate embed modal
data-ab-amounts/data-ab-amount: comma separated amounts in dollars for the button(s)
data-ab-id: unique string that can be used to uniquely identify origin embeds in events
data-ab-locale: current locale for the embed, overriding configured locale. `en` and `es` are supported.
data-ab-preview: true/false, preview mode for the embed, will disable contributions from going to ActBlue servers for development purposes
data-ab-recurring: true/false, will require contributions to be recurring or one-off, leave off to allow the donor to decide
data-ab-style: inline css string that will be applied to buttons
data-ab-stylesheet-href: url to stylesheet that will be injected into the iframe, all inline styles will be disabled
data-ab-verb: string to be included before the amount, such as ‘Donate’ or ‘Give’
data-ab-donor-email: prepopulate the donor’s email
data-ab-donor-firstname: prepopulate the donor’s firstname
data-ab-donor-lastname: prepopulate the donor’s lastname
data-ab-donor-phone: prepopulate the donor’s phone number
data-ab-donor-zip: prepopulate the donor’s zip code
<div data-ab-form /> parameters:
data-ab-token: the token for the embed, retrieved from the generate embed modal
data-ab-amount: pre-selected amount in cents for the embed, can be combined with data-ab-amounts and data-ab-other-amount=”false” to enforce an embed which only accepts a specific amount
data-ab-amounts: comma separated list of suggested amounts in cents
data-ab-other-amount: true/false, false will disable donors from entering a custom amount
data-ab-id: unique string that can be used to uniquely identify origin embeds in events
data-ab-locale: current locale for the embed, overriding configured locale. `en` and `es` are supported.
data-ab-preview: true/false, preview mode for the embed, will disable contributions from going to ActBlue servers for development purposes
data-ab-height: pixel amount (ex: “600px”) or “auto” to allow the embed to resize itself to it’s contents. Omitting will have the embed grow to the height of it’s containing div.
data-ab-stylesheet-href: url to stylesheet that will be injected in the frame
data-ab-donor-email: prepopulate the donor’s email
data-ab-donor-firstname: prepopulate the donor’s firstname
data-ab-donor-lastname: prepopulate the donor’s lastname
data-ab-donor-phone: prepopulate the donor’s phone number
data-ab-donor-zip: prepopulate the donor’s zip code
window.actblue:
actblue.requestContribution: ({
amount: number, // preselected amount in cents
amounts: number[], // array of amounts in cents to suggest to the donor
donor: { firstname: string, lastname: string, email: string, phone: string, zip: string }, // information about the donor to prepopulate
embedId: string, // unique string that can be used to uniquely identify origin embeds in events
locale: ‘en’ | ‘es’, //locale to present the embed form in
onClose: (contribution: Contribution) => {}, // function to be called when the modal from this contribution is closed
onComplete: (contribution: Contribution) => {}, // function to be called when the donor reaches the thanks screen, after all upsells
onContribute: (contribution: Contribution) => {}, // function to be called at the moment the donor submits a contribution (before upsells), useful for conversion tracking, etc
onError: (message: string) => {}, // function to be called on any fatal system errors, like the embed token not being found on ActBlue servers
onLanded: () => {}, // function to be called when the donor ‘lands’ on the form, i.e. the modal has opened and the form is loaded and ready for interaction.
preview: boolean, // preview mode for the embed, will disable contributions from going to ActBlue servers for development purposes
refcodes: {[refcode: string]: string}, // object containing a map of refcodes to their values, note that all refcodes must begin with the string ‘refcode’
styleSheetHref, // url to stylesheet that will be injected in the frame
token, // the token for the embed, retrieved from the generate embed modal
}) => Promise<Contribution> // promise is resolved once the user contributes, exact same time as ‘onContribute’. promise is rejected if the donor closes the modal without donating.
actblue.addEventHandler(‘close’ | ‘complete’ | ‘contribute’ | ‘error’ | ‘landed’, (contribution: Contribution) => {})
Add an event handler that will trigger on events from any ActBlue embed on the page:
‘close’: function to be called when the modal from this contribution is closed
‘complete’: to be called when the donor reaches the thanks screen, after all upsells
‘contribute’: to be called at the moment the donor submits a contribution (before upsells), useful for conversion tracking, etc
‘error’: to be called on any fatal system errors, like the embed token not being found on ActBlue servers
‘landed’: to be called when the donor ‘lands’ on the form, either when a modal is opened from an embeddable button or requestContribution when a user interacts
abConfigure(configuration)/actblue.configure(configuration):
actblue.configure({
amounts: number[]; // array of amounts in cents to suggest to the donor
donorData: {firstname: string, lastname: string, email: string, phone: string, zip: string}; // information about the donor to prepopulat
preview: boolean; // preview mode for the embed, will disable contributions from going to ActBlue servers for development purposes
refcodes: { [refcode: string]: string }; // object containing a map of refcodes to their values, note that all refcodes must begin with the string ‘refcode
locale: ‘en’ | ‘es’, //locale to present embeds in
styleSheetHref: ‘string’, // url to stylesheet that will be injected into an embeddable forms
onClose: (contribution: Contribution) => {}, // function to be called when an ActBlue modal is closed
onComplete: (contribution: Contribution) => {}, // function to be called when the donor reaches a thanks screen, after all upsells
onContribute: (contribution: Contribution) => {}, // function to be called at the moment the donor submits a contribution (before upsells), useful for conversion tracking, etc
onError: (message: string) => {}, // function to be called on any fatal system errors, like an embed token not being found on ActBlue servers
onLanded: () => {}, // function to be called when the donor ‘lands’ on the form, i.e. the modal has opened and the form is loaded and ready for interaction.
});
actblue.remove():
Will reset any embed divs back to the backup content, and remove all ActBlue logic from your page.
Contribution:
{
name: string, // form name
recurring: boolean, // if the contribution will recur
embedId: string, // unique string for the embed that generated this contribution
email: string, // donor’s email address
order_number: string, // ActBlue order number
amount: number, // amount in cents
preview: boolean, // if the contribution was made in preview mode, i.e. not actually sent to ActBlue’s servers
refcode: string, // the ‘refcode’ refcode
refcodes: {[refcode: string]: string}, // object containing all refcodes, note: all refcode strings will begin with the string ‘refcode’
]),
}
Note: configuration inheritance
As you can see, you can configure the same things in different places, where there are conflicts the specificity will work like:
- data-ab attributes
- abConfigure() page configuration
- url params (only refcodes can be configured with url params)
- ActBlue form configuration