In this article:

1. Types of embeds
2. Creating an embeddable form or button
3. Customizing embeddable forms and buttons
4. Embedding forms and buttons in your website’s code
5. Using the WordPress plugin for embeddable forms and buttons
6. Backup form settings
7. Evaluating embeds
8. Embedding a goal tracker
9. 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:

1. data-ab-refcode
2. abConfigure({refcodes: {refcode: ‘refcode’}});
3. URL params:
   1. ab_refcode
   2. refcode
   3. ref

Refcode2 inheritance:

1. data-ab-refcode2
2. abConfigure({refcodes: {refcode: ‘refcode’}});
3. URL params:
   1. ab_refcode2
   2. 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: 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:

1. data-ab attributes
2. abConfigure() page configuration
3. url params (only refcodes can be configured with url params)
4. ActBlue form configuration

If you have any questions, please contact our support team using the email address you use to access your ActBlue account.