Embeddable Objects Guide

Please Note: These tools are in beta and have only been rolled out to a small group of users. If you have questions about these tools, reach out to your ActBlue contact or support@actblue.com!

ActBlue embeddable objects are donation features you can add directly to your webpage so donors never have to leave your site. Our embeddable objects (A.K.A. embeds) take advantage of our full ActBlue Express ecosystem, meaning that if a user is recognized as a previous ActBlue donor, their information will be prefilled directly in the embed on your webpage, resulting in higher conversion rates.

Though we designed these embeddable objects to be as simple to use as possible, you will need some technical knowledge to be able to successfully include them on your webpages. You’ll have to know how to edit your webpage’s source code, know a bit about HTML, and if you know CSS, you’ll be able to customize the look and feel of your embeddable objects.

Types of Embeds

There are currently two different types of embeddable objects you can include on your webpages. They are Embeddable Forms and Embeddable Buttons.

Embeddable Forms

Embeddable Forms are contribution forms that are inserted directly onto your webpage. The entire donation process, whether it be multistep for new donors, or single-click for ActBlue Express donors, takes place within the Embeddable Form. 

Live Embeddable Form Demo: https://report.actblue.com/donate/

Embeddable Buttons

Embeddable Buttons are donate buttons you can insert onto your webpage that launch a modal where the remainder of the contribution takes place. Embeddable Buttons are a great option when you’re working with limited space, like in a navigation bar, hero area, etc. 

Live Embeddable Button Demo: https://report.actblue.com/

Enabling Embeds 

All Embeddable Forms and Buttons have to be tied to an ActBlue contribution form. These forms will still function as regular contribution forms. We recommend creating a new contribution form solely to use with your embed integration in order to more easily track the source of donation activity. We do not currently distinguish between donations made directly through a form versus an embeddable object associated with a form. 

Getting Started with Embeds:

Step 1: Create Form

Create a contribution form on ActBlue associated with your campaign. To do this, select “Embed form” from the “Create form” dropdown. The form you create will have the code you need for both an Embeddable Form and Embeddable Buttons. This contribution form should be one that isn't used for any other donor traffic. This allows you to more easily track your donations.

Step 2: In the form editor, select “Embed Code”

Step 3: Enter URLs

Now you can specify the webpage where you’d like to host your embeds. In the “URLs” field, enter any URLs where you’ll include Embeddable Forms or Buttons. For security purposes, embeds will only appear on URLs listed here. Each URL must begin with “https” in order to proceed. If you’d like to include the embeds on multiple pages you’ll need to include each of the URLs separated with a comma.

Any valid domain name you include will be allowed to host the embeds. If you add "https://www.example.com" you’d be able to include an embeddable object anywhere on example.com.

The “Embed button,” “Embed form,” and “Token” fields will not generate until you hit the “Publish” button (covered in the next step).

Step 4: Publish Form

Once you’ve entered at least one valid https URL, hit the “Publish” button in the top right corner of the form editor. Note: This will not publish the form or buttons to the public on your webpage — you will need to embed the object yourself in the code for the URL(s) you provided.

Step 5: Generate Code

After hitting “Publish,” the “Embed button,” “Embed form,” and “Token” fields will automatically generate.

Including Embeddable Forms & Buttons on Your Webpage

Once you’ve successfully enabled the embed option for a contribution form by following the steps above, you’ll be able to include an embeddable object on your “authorized” webpages.

  1. From the “Embed Code” tab of the form editor, copy the <script> tag provided.
  2. Paste the <script> tag into your webpage’s source code, preferably in the <head> tag.
  3. Next, decide whether you’d like to include “Embed buttons” or an “Embed form.” Copy the corresponding code.
  4. Paste that code in your page’s source code wherever you would like the embeddable object to appear. 

Note: You can repeat steps 3–4 as many times as you’d like on a single webpage. You can even include multiple embeddable objects from different contribution forms on a single webpage. The <script> tag only has to be included in the <head> once per page, even if you have embeds from different forms.

Customizing Embeddable Forms & Buttons

There are a number of ways to customize the embeds. Some customization options may only apply to the Embeddable Form, or only to Embeddable Buttons, or both. All customizations are optional.

All customization options will be applied as properties to the containing <div>. When adding or editing customization properties, be sure not to delete the data-ab-button/form or data-ab-token properties.

Amounts — Embeddable Forms and Buttons

Customize the number of dollar amount buttons and their values. Using the letter “n” signifies the “other amount” option.

Examples:

data-ab-amount=”5”

data-ab-amount=”5,10,25,50”

data-ab-amount=”5,10,25,50,100,n”

Verb — Embeddable Buttons only

By default, Embeddable Buttons will simply show a dollar amount. You can customize what Embeddable Buttons say by setting a “verb.” This will change what Embeddable Buttons display from simply “$25” to “Donate $25,” “Give $25,” or whatever other one-word verb you set. 

Examples:

data-ab-verb=”Donate”

data-ab-verb=”Give”

data-ab-verb=”Contribute”

Styling Embeddable Buttons

Custom styles can be applied to Embeddable Buttons using inline CSS via the data-ab-style property. Add this to the containing <div> just as you would other customization properties.

Styling Forms

These instructions apply not only to the Embeddable Form, but also to the form that displays in the modal when an Embeddable Button is clicked. Since there are many more elements to style within the forms vs. a single <button> element, inline CSS is no longer practical. Instead, users who wish to style forms can link to a hosted custom stylesheet.

To style a form, follow these instructions: 

  1. Create your custom stylesheet and host it somewhere. We recommend uploading the stylesheet wherever the rest of your site is hosted. Alternatively, you can use a file hosting service. 
  2. On the same webpage where the embeds you wish to style are, find where you added the <script> tag to the source code (from the “Including Embeddable Forms & Buttons on Your Webpage” instructions). It is most likely in the <head> tag if you followed those instructions.
  3. Add the following <script> tag directly before the existing script tag: <script>window.actBlueConfig = {styleSheetHref: "https://[YOUR-URL-HERE].css"};</script>
  4. Be sure to replace the URL in the above script with the URL of your hosted stylesheet. 

Note: You can only add one custom stylesheet to each webpage. This means that if you have multiple embeds on a single webpage — whether they’re Forms, Buttons, or some combination — all of the forms will take the same custom styles.

Styling Shortcuts

All styles for the forms have been written in a way that is meant to be as easy to overwrite as possible. Class names are clear to read (inspired by BEM naming conventions), and there is little nesting, which means you won’t have to fight with specificity.

The stylesheet utilizes CSS Custom Properties (often called CSS variables), which provide a handy shortcut for customization. What makes CSS Custom Properties so handy is that they are dynamic: Their values can be changed later (for example, via a hosted custom CSS file), and this change will apply to all instances of the variable — even before the change was declared. 

This means that if in the default stylesheet it is declared that all buttons have a background color of var(--button-color), and the default value of var(--button-color) is cerulean blue, you can link to a custom stylesheet that declares var(--button-color) should be green, and all buttons that use that variable will now be green instead of cerulean blue.

CSS Custom Properties were used wherever we thought customization would be most desired. A list of all Custom Properties and their default values is shown below. To quickly customize forms, simply copy and paste the properties below into your custom hosted CSS file. (Be sure to wrap them in a :root { } selector.) Change the values as you desire to match your branding.

If the Custom Properties don’t quite get the job done, you can include additional CSS in the same file, targeting class names as you normally would. (These additional styles should be outside the :root { } selector.)

/* Colors */

--color-primary-brand: #00A8DF;

--color-text: #1F2A44;

--color-secondaryText: #657287;

--color-error: #DB0A5B;

--color-background: #FFF;

--color-subtle-background: #F7F8FA;

--color-success: #00AB4C;

--color-link: #0078AB;

/* Form options */

--form-padding: 1.5rem;

--border-radius: 4px;

/* Border around entire form */

--form-border: 1px solid #E6E9ED;

/* Form header and footer areas */

--form-header-footer-background: #FFF;

--form-header-footer-border-color: #E6E9ED;

/* Advance button: continue, donate, etc. */

--advance-button-background-color: var(--color-primary-brand);

--advance-button-color: #FFF;

--advance-button-border: 0;

--advance-button-font-weight: bold;

--advance-button-text-transform: none;

--advance-button-font-size: 1rem;

/* Selectable buttons: amounts, recurring, etc. */

--select-button-color-text: #4D5666;

--select-button-color-background: #CCD3DE;

--select-button-border: 0;

--select-button-font-weight: bold;

--select-button-text-transform: none;

--select-button-font-size: 1rem;

--select-button-selected-color-text: #FFF;

--select-button-selected-color-background: var(--color-primary-brand);

--select-button-selected-border: 0;

/* Input fields */

--input-background-color: #FFF;

--input-border-size: 1px;

--input-border-color: #CCD3DE;

--input-border-focus-color: var(--color-primary-brand);

--input-color: var(--color-text);

--input-label-color: var(--color-primary-brand);

--input-color-placeholders: #657287;

Note: CSS Custom Properties are supported in all modern browsers except for IE11. This means that if you choose to style your forms with Custom Properties, your custom styles will be visible in all modern browsers except IE11. IE11 forms will still be fully functional, they will simply use the default styles.

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:

  1. data-ab-refcode
  2. URL params:
    1. ab_refcode
    2. refcode
    3. ref

Refcode2 inheritance:

  1. data-ab-refcode2
  2. URL params:
    1. ab_refcode2
    2. refcode2

Events

In order to track events, just add a function to your actBlueConfig object:

<script>
window.actBlueConfig = {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: new JavaScript function that accepts an object with amount 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.

actblueConfig:

Now accepts token as a way to set a default token for both the new API and for Embeddable Forms/Buttons.

Paid for by ActBlue (actblue.com) and not authorized by any candidate or candidate's committee.
Contributions or gifts to ActBlue are not deductible as charitable contributions for Federal income tax purposes.