ActBlue user roles and permissions dictate what users can do on our platform. If the tools or features in this article are unavailable to you, speak to your entity Admin first about updating your permissions.
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 that embeddable forms and buttons are only available for 501(c)(3) and 501(c)(4) nonprofit organizations and federal campaigns.
Embeddable forms and buttons are donation features you can add directly to your webpage, so supporters don't need to leave your site to donate. Embeddable forms allow ActBlue Express users with saved information to donate via a prefilled embed on your site in seconds.
All three steps of the donation flow — contribution amount, payment information, and donor details — occur within your embeddable form or buttons. Donors can also give via PayPal™ in an embed, just like regular contribution forms, but embeds cannot currently accept Apple Pay.
Because embeddable forms and buttons live on your website, some customization options aren't available, including titles, donation asks, goal thermometers, or brandings. Donation amounts, Spanish language forms, and most other customization options within the form editor are available for embeds.
To use embeddable forms and buttons, you just need a way to edit your webpage's source code. If your website is on WordPress, use our plugin to make it even easier.
Types of embeds
Embeddable forms
Embeddable forms are contribution forms that are inserted directly into your webpage. The entire donation process, whether multistep for new donors or single-click for ActBlue Express donors, takes place within the form on your site. The image below depicts an embeddable form on a website from the viewpoint of an ActBlue Express donor.
Embeddable buttons
Embeddable buttons are donate buttons you can insert into your webpage that launch a pop-up modal where a donor finishes the donation process. They are a great option when your webpage has limited space, like in a navigation bar, menu, or hero area.
The pop-up looks like this:
If a donor has an ActBlue Express account, the pop-up will already have their payment information in the fields.
Creating an embeddable form or button
Click "Create form" in your Dashboard and select "Embed form." Fill in the basic information for your form.
Click “Next step” to enter more details for this form, or click “Publish now” to enter the form editor. From there, navigate to the “Embed Generator” tab to create your form or buttons and copy the code for your website.
Enter any URLs where you want to embed a form or buttons in the “Allowed URLs” field, separating each URL with a comma. You can only host embeds in the URLs listed here, and the URLs must be secure (start with https).
After entering your URLs, click “Publish” to save your work and continue creating your embeddable form or button.
After publishing, more options will appear under “Step 2:”. Under “Type of Embed,” select either form or button.
A preview of your form or buttons will always be visible on the right side of your screen. Click "Publish" to preview the most up-to-date version of your form or buttons.
Customizing embeddable forms and buttons
Embeddable forms
If you choose “Form,” you will see an unchecked “fixed height” box. By default, the embeddable form height is dynamic, so donors can see the entire form on your website (the form will not have an internal scroll). 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, allowing you to collect data about where your donations come from. Once you enter your custom refcode, we will include it in the code used to embed the form on your webpage.
To select the donation amounts on your form, return to the main menu of the form editor and select the “Preset donation amounts” tab. There is always an “Other amount” option.
Publish your changes to save them.
Embeddable buttons
If you choose “Button,” you can customize your buttons in the “Embed Generator” tab.
To ask supporters for recurring donations, choose a recurring ask in the “Recurring” dropdown menu. The default recurring setting for embeddable buttons is “Donor Decides,” which gives donors the option between a one-time or recurring contribution:
If you select “Recurring,” embeddable buttons will only accept recurring donations, and no one-time donation options appear in the pop-up. The donor will have already chosen to give a recurring contribution by clicking the button, so there is no recurring upsell after they donate. Embeddable buttons make it clear to the donor that they're making a recurring donation:
If you select “One-Time” from the “Recurring” dropdown menu, your embeddable buttons will only accept one-time contributions. Donors won't see a recurring option in the pop-up. They also won't see an additional recurring upsell after donating, even if you enable the upsell in the “Recurring settings” tab of the form editor.
Set specific amounts for your embeddable buttons in the “Preset amounts” field, separating each amount with a comma. To include an “Other amount” option, check the box below the “Preset amounts” field.
You can leave the buttons with just the amounts or add a verb like “donate" by entering it in the “Button verb” field.
Click the "Color" and "Font Color" dropdown menus to customize these elements of your buttons.
You can paste the hex code for your brand's colors or use the color picker to select a color.
You can also change your font size and weight.
Edit the “Border Radius” field to adjust how round your buttons are.
By clicking “Advanced,” you can use custom CSS to change how your buttons look.
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 code to integrate with other popular platforms. For example, you can add "Facebook Conversion Tracking" if you have a Facebook pixel on the page with your embed.
Use "Google Conversion Tracking" if you track Google Ads conversions to the page with your embed.
Other embed settings
Once you’re happy with how your buttons or form look, you have a few other options that you can apply to your embed. Exit the “Embed Generator” tab to return to your form editor.
In the “Form customization” tab, you can change the provided text on your form or your button’s pop-up modal to Spanish. Doing so translates most form elements:
- Form buttons
- Donation block helper text
- Donor information fields
- Recurring options
- Recurring or Smart Boost upsell text
- Standard contribution rules
- ActBlue or AB Charities disclaimers
However, translation doesn't apply to any verbs you add to embeddable buttons because they are user-generated text.
Add a custom input — a field you can customize to collect additional information from your supporters. You can apply this to your embeddable form or embeddable button's pop-up modal.
You can customize your recurring settings in the “Recurring settings” tab.
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.
If you select “One-Time” or “Recurring” in the menu in the "Embed Generator" tab, upsell customizations made in the "Recurring settings" will not apply.
In the “Recurring settings” tab’s “Monthly recurring donations” dropdown menu, you can change your recurring ask and recurring upsell:
- Disabled: no recurring option in the embeddable object or recurring upsell
- Specified duration: donors will see a recurring option on your embeddable object. If they make a one-time contribution, they will see a recurring upsell after donating. Your form will prompt them to customize how long their contribution will recur.
- Unlimited: 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 donating. There is no duration option, so their contribution will recur until they cancel it or change the schedule in their ActBlue Express account.
- Unlimited + Smart Options: your donors will see a recurring option in the embeddable object. If they make a one-time contribution, they will see a recurring upsell after donating, suggesting multiple smaller recurring amounts. They will also have the option to set their own amount. Read more about Smart Recurring.
If you select “Smart Boost” in the “Post-donation upsells” tab, donors won't see a recurring upsell, even if you enable one of the options above.
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. 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 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.
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.
In the “Thanks and receipt” tab, you can write the text for the top of donors’ email receipts.
In the “Post-donation upsells” tab, you can select the upsell you want donors to see after they give an initial contribution. If you select “Recurring,” customize these settings in the “Recurring settings” tab (if you’re creating embeddable buttons, in the “Embed Generator” tab).
If you select “Smart Boost,” an upsell will give donors multiple options to increase their initial donation. You can customize the Smart Boost upsell title and ask in the “Post-donation upsells” tab.
Donors will still see the Smart Boost upsell if they make a recurring donation through your embeddable form or buttons. However, Smart Boost will not add 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 $6. But their future recurrences will be $5.
Publish any 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 to embed a form or buttons in your webpage.
At the bottom of the tab, click “Generate Embed.”
The pop-up will have the code you need to paste into your webpage's source code (HTML) – insert it wherever you want your embeddable buttons or form to appear. Our engineers also included information in this pop-up if you’re new to editing HTML.
You can include multiple embeddable buttons and forms in a single webpage.
You only need to include the <script>
tab in the <head>
once per page and then copy and paste the different <div>
tags where you want your embeds to display.
Using the WordPress plugin for embeddable forms and buttons
If your website is on WordPress, you can embed your contribution form or buttons in a few 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. Read further instructions here.
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 buttons. These settings apply to your backup form, a regular contribution form that your donors will land on if something prevents your embed from working.
There are limited customizations available for backup forms. Customizing the title and donation ask on your backup form is essential so donors know they are still giving to you even if the embed does not work and they leave your site. Write these in the “Title, ask, and URL” tab.
Read more about 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. You can filter the list by “Embed” to find your form more quickly:
Select the Contributions or Amount total for your backup form to view its Statistics page, or go straight there by selecting the “Stats” button in the form navigation bar:
You can also set up email alerts for contributions or refunds for embeddable forms and buttons in the “More” dropdown of the navigation bar. Data will also appear in the rest of your Dashboard data.
More questions? Schedule a call with one of our nonprofit experts.
Embedding a goal tracker
Click here to read more about embedding a goal tracker on your website or email.
Advanced
Tracking embeds
Find Embed statistics like visits and contributions on the Statistics page for that contribution form.
Visit tracking works differently from standard ActBlue contribution form reporting. ActBlue only tracks a visit to an embeddable form if a potential donor interacts with an embedded element. This interaction can occur by clicking an embeddable button or anywhere on an embed form iframe.
Pair this information with your website traffic data for a broader picture of your end-to-end conversion.
You can pass a refcode into the embed through an attribute on the embed div or a URL parameter.
Refcode inheritance:
data-ab-refcode
abConfigure({refcodes: {refcode: ‘refcode’}});
- URL params:
ab_refcode
refcode
ref
Refcode2 inheritance:
data-ab-refcode2
abConfigure({refcodes: {refcode: ‘refcode’}});
- URL params:
ab_refcode2
refcode2
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: stri
ng, 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
If you have any questions, please contact our support team using the email address you use to access your ActBlue account.
The amount of support that the ActBlue Customer Service Team can provide is dependent on the permissions that you have. Check with your entity Admin about your assigned role.
Comments
0 comments
Article is closed for comments.