ActionTag

ActionTag is an easy way to embed forms on any site. Much like Twitter Embedded Timelines, the idea is to use one line of JavaScript and one line of HTML to have a foolproof way to present a form that posts back to your NGP database. Please note that ActionTag does not work on IE9 or older browsers.

Usage

What is it?

ActionTag is our name for our embeddable forms functionality. Embeddable on any page on the web, it will:

Make an API call to retrieve that form’s definition (aka which fields should display)

How to Find the Embed Code

The easiest way to use ActionTag on your own website is to use the embed codes provided inside the form builder. In Online Actions there is a “Link & Embed” button at the top of every step of the form builder, which is enabled once you have published your form. In EveryAction 7, you can find the embed code on the last step of the Online Page Manager (the step labeled “Published Page Info”).

Getting Started with Manually Embedding a Form

All that’s necessary to use ActionTag is to drop a special <div> tag on any page along with our JavaScript file. For example:

We use the class ngp-form to indicate that this is the place where the form should render.

NOTE: any use of ActionTag for processing payment information must be embedded in a TLS-secured page.

To specify which form to render, add the only other required data attribute, the data-id attribute, e.g. data-id="-9061805400222859264". Each form published has a unique id which can be used in this tag. Please note: that some form IDs start with a minus sign (-), as shown in the example above. Do not delete this as it is a part of the form ID.

These are the simplest cases. Below are some more of the data attributes that can optionally be added to the tag to alter its behavior.

SmartLinks

For users who draft emails for use in Targeted Email, a special merge field is available which auto-fills user contact data merge fields in an ActionTag form. To use this merge field, append contactdata={{ContactData}} to any URL which hosts an ActionTag form, and embed the resulting URL in the body of a Targeted Email. Doing so will cause the following merge data to be automatically merged in to when email receipients click through the URL in the email, and view the form:

First Name

Middle Name

Last name

Subscriber Email

Street Address

City

State or Province

Zip or Postal

Home Phone

Cell Phone

Work Phone

Employer

Occupation

Prefix

Suffix

Example

You create a form in Online Actions, and use ActionTag to embed it at https://www.peopleforgood.com/donate.

You draft an email to your supporters.

In the body of the email, you include the following URL: https://www.peopleforgood.com/donate?contactdata={{ContactData}}

You paste the body of the email into Targeted Email, and send the email to your supporters.

When Targeted Email generates the email, it prepares a special encoded string, specific to each supporter. This encoded string is merged in to the personalized email which each supporter receives. For example, supporter Jane Casey might receive an email with the URL https://www.peopleforgood.com/donate?contactdata=1234ABC.

Jane Casey, one of your supporters, receives the email and clicks the link.

ActionTag displays the form from step 1.

ActionTag reads the contactdata string, and merges Jane Casey’s data into the form display.

It is also possible to add contactdata alongside other parameters. For example, if you wanted to use the Targeted Email merge field for a record’s highest previous contribution to set the contribution amount on a form, defaulting to $3 if the record is a nondonor, then the url would look like this: https://www.peopleforgood.com/donate?am={{HighestPreviousContribution or '3'}}&contactData={{ContactData}}.

Using Query Strings

A query string is something you can add to the end of the URL your form lives at, e.g. www.someurl.com/formid?foo=bar Primarily, query string values are used to pre-fill values in the form. The general format is that the first bit is the name of the form field, followed by an equals sign and then whatever data you wish to pre-fill that form field with. ActionTag assumes US formats for all fields (phone, postal code, amounts, etc.).

The way to add these onto a form is that the first one needs to use a question mark, and other subsequent ones use an ampersand, e.g. www.someurl.com/formid?fn=John&ln=Adams

Available visible fields to be filled:

Name

Parameter

Sample

Notes

AddressLine1

add1

add1=1250+Hancock+St.

AddressLine2

add2

add2=Ste.+202

Additional Contribution Value

AdditionalContributionValue

AdditionalContributionValue=25

Prefill the additional contribution amount on event forms only

Amount

am

am=5

AmountOptions

amtOpts

amtOpts=3,5,20.16,50,100

This sets the radio button options on a contribution page, enabling dynamic ask amounts. To select a particular contribution amount, use Amount

Elements that are specific to Events List Pages (these fields are visible on the ActionTag form):

Name

Parameter

Sample

Notes

Display Results

results

results=true

Distance in Miles

radius

radius=50

Date From

date_start

date_start=06-26-2018

Date To

date_end

date_end=06-26-2018

Event Type

event_type

event_type=285730,294375

Sort

sort

sort=2

1 • Date 2 • Distance

Elements that are specific to Events Signup Pages (these fields are visible on the ActionTag form):

Name

Parameter

Sample

Notes

Location

location

location=1816

Role

role

role=250634

Shifts

shifts

shifts=11631||11632

Elements that are specific to Contribution forms with Tribute & Gift Memberships functionality enabled (these fields are visible on the ActionTag form):

Name

Parameter

Sample

Notes

Enable Tribute Gift

t

t=true

Honoree Name

honoree

honoree=Barack+Obama

In Honor or in Memory of

ttype

ttype=1 “In memory of” ttype=2 “In honor of”

Notification Send Copy

recipient_em_copy

recipient_em_copy=1 or recipient_em_copy=truerecipient_em_copy=0 or recipient_em_copy=false

Affects checkbox used to indicate whether or not to send a copy of a notification to the donor.

Include Recipient (Gift Memberships)

tn

tn=true

Used for Gift Memberships. Displays contact details for recipient.

Notify Recipient (Tribute Gifts)

tn

tn=true

Used for Tribute Gifts. Displays all recipient details.

Recipient Information

Recipient FirstName

recipient_fn

recipient_fn=John

Recipient LastName

recipient_ln

recipient_ln=Adams

Recipient Address Line 1

recipient_add1

recipient_add1=1250+Hancock+St.

Recipient City

recipient_ci

recipient_ci=Boston

Recipient State Province

recipient_st

recipient_st=MA

Recipient Postal Code

recipient_pc

recipient_pc=02144

Recipient Country

recipient_c

recipient_c=United+States

Recipient Email Address

recipient_em

recipient_em=john.adams@example.com

Elements that are specific to Premiums functionality enabled:

Name

Parameter

Sample

Shipping FirstName

shipping_fn

shipping_fn=John

Shipping LastName

shipping_ln

shipping_ln=Adams

Shipping Address Line 1

shipping_add1

shipping_add1=1250+Hancock+St.

Shipping City

shipping_ci

shipping_ci=Boston

Shipping State Province

shipping_st

shipping_st=MA

Shipping Postal Code

shipping_pc

shipping_pc=02144

Shipping Country

shipping_c

shipping_c=United+States

There are also elements that may not be visible, but have to do with how the form submission data is entered into the database:

Name

Parameter

Sample

Notes

Attributed Contact ID

attr

attr=VN96C3TBX36

Allows you to set which contact to attribute a contribution to. This value can be a VANID for forms created in Online Actions, or an NGP ID for forms created in EveryAction 7. (Used for Contribution forms only.)

Host Committee

ac

ac=VN96C3TBX36

Select host committee contact from a list of contacts in a dropdown. This value can be a VANID for forms created in Online Actions, or an NGP ID for forms created in EveryAction 7. (Used for Ticketed Events only.)

Kiosk Mode

kiosk

kiosk=true

Using this query string parameter disables FastAction and ActionProfile integration. This is useful if the user is using a form on a tablet or laptop in a public place and do not want the submission information remembered on that device. Notably, if you configure one form to redirect to another form (what we refer to as secondary ask), the form fields on the second fom will not be pre-populated by the submission info from the first form. If you are launching the form with knowledge of who a contact is, kiosk mode does still allow you to prefill form fields using other query string values, e.g. fn=Michelle as documented above.

MarketSource

ms

ms=201409_fb_birthday_v1

Can be used to track different ad buys to the same form to compare ROI

SourceCodeId

sourceid

sourceid=57

Either adds or overrides the defined source code on the form. This only applies to contribution forms. You must use the source code ID, not the source code name.

QuickSign

quick

quick=true

Automatically submits the form and segues to the next action (thanks page, secondary ask, or an arbitrary other URL) if all the required fields are prefilled by either a query string value or ActionProfiles. This does not work for contribution or event forms.

Notice that the conversion ID and conversion labels are in two places. First in the regular javascript and second inside the <noscript> code block. These are the values you need to copy into the new code snippet.

Here’s the new code you need to use, make sure to grab the conversion ID and label from the code Google provided, and insert them below. Once you’ve updated this snippet with your account information, you can copy it and paste it into the source of the NGP form page by clicking the “source” button and paste.

Attributes

Data attributes on the ActionTag div are the way to pass certain data or instructions to ActionTag to influence its behavior.

Since these attributes are part of the div, any CMS or website system can easily write code that will consume ActionTag with the characteristics they desire. This is the way we have written our own Drupal modules in-house.

What follows are the data attributes we currently support:

data-id (required)

It is used to specify the id of the form to render. Only required if data-form-url is not used. Note that an advocacy-related form must use the data-form-url attribute instead.
Example, to load a non-advocacy-related form with id 12345:

<divclass="ngp-form" data-id="12345"></div>

data-form-url (required)

It is used to specify the url from which the form definition is retrieved. Only required if data-id is not used, or if presenting an advocacy related form, which requires getting the form definition from a different endpoint.
Example, to load a form from a url:

data-databag

(optional) - Used to specify whether to use NGP VAN ActionProfiles to fill the form fields. In order for this functionality to work, the site using this must be white-listed by NGP VAN. Contact support if you are interested in getting your URLs whitelisted.

Note: databag is the legacy name for ActionProfile, hence the attribute/name mismatch.

Default: nobody

Options:

nobody - disable this functionality

everybody - Allow pre-filling of information from any site in the NGP VAN network. Also requires sharing pre-fill data with other sites in the NGP VAN network.

Example, to enable the NGP VAN Profile filling (assuming the site on which this tag is sitting has been white-listed):

<divclass="ngp-form" data-id="12345" data-databag="everybody"></div>

data-endpoint

(optional)- Used to specify a non-default API endpoint for retrieving the form definition and submitting the resulting data. This is used mostly for hitting development servers; though, if your NGP instance is accessed by a URL other than www2.myngp.com, you likely need to use this attribute.

data-formdef-endpoint

(optional) - This attribute defines a different read endpoint from the POST endpoint defined above. Primarily this is used to call the form definitions from Amazon S3, which NGP will automatically update on every form publish. This leads to faster load times for your forms, especially in peak usage situations, so it is recommended for use in every ActionTag implementation.

Default: value of data-endpoint attribute.

Example, to read the form definition from Amazon S3 instead of the NGP API servers:

oberon - legacy template for the act.myngp.com theming, and most likely to get deprecated

Example, to load the minimal template set:

<divclass="ngp-form" data-id="12345" data-template="minimal"></div>

Callbacks

Overview & Intended Audience

Callbacks are a rather technical feature set, and are not needed for the vast majority of uses of ActionTag. The callbacks described below are powerful, but also probably require some experience doing web development, and are not needed for most uses of ActionTag. Feel free to skip the rest of these docs unless you are a developer.

We have a series of callbacks in ActionTag which allow developers to alter bits of functionality. In order for ActionTag to know about your callback, we have a simple registration process.

First create the global JavaScript variable nvtag_callbacks (but only if it doesn’t already exist). The following snippet accomplishes this:

var nvtag_callbacks = nvtag_callbacks || {};

If your code is within a closure, you will need to explicitly ensure it is declared in the global namespace so ActionTag can find and reference it. Here that’s done with a local reference so that we no longer have to reference it by calling window.nvtag_callbacks:

The last bit is callback specific. Perhaps you want to add a postRender callback to do something after the ActionTag form has been rendered.

Instantiate that callback as an array if it doesn’t yet exist

Create the actual callback function. The arguments to your function are the callback arguments listed below

Note, the first argument to a callback is always the name of that callback. This is done in an attempt to allow one function to be registered from multiple callbacks and then allow that function to handle things internally.

Push your callback onto the postRender callback array

nvtag_callbacks.postRender = nvtag_callbacks.postRender || [];
// This function can be called anything, we don't carevar sampleCallback = function() {
alert("The form has been rendered!");
}
nvtag_callbacks.postRender.push(sampleCallback);

Now your callback code will be called by the ActionTag at the time that postRender should happen! (which is after rendering of the form is complete).

At the right time in the ActionTag process, we will iterate over each of the callbacks in that array and call them.

Technical background

We use our callbacks syntax to put it into the global namespace because ActionTag loads asynchronously. Also, we wish to support multiple callback sources, hence the instructions to not redeclare it over and over again.

A warning on the power of these abilities

Since our callbacks allow you to alter internals of our system, it is possible to make quite a mess of things, sometimes even in potentially dangerous/breaking ways. With great power comes great responsibility.
For example, using the alterFormDefinition() callback:

preSegue

This hook is called after a successful form submission, but prior to the segue to the next thing.

As a quick primer, there are, at current, 3 different things which can happen after a successful form submission:

Display a thank you message

Display another form (aka Secondary ask)

Redirect to another page anywhere on the internet

preSegue() happens before the transition to this next step so it’s useful for intercepting it and altering the behavior based on the submitted values and/or the response from the server.

It receives two arguments:

submitted_values - The values which were submitted across the network

response - The response from the server to that submission

segue

segue(args)

This hook is called when a segue is happening.

As a quick primer, there are, at current, 3 different things which can happen after a successful form submission:

Display a thank you message

Display another form (aka Secondary ask)

Redirect to another page anywhere on the internet

We call the transition from one thing to another thing a segue. This callback is called when making that transition.

Note, it is NOT called in case 3 above because we have no control over another page on the internet.

It receives three arguments:

formviews - The form views in question

thank - boolean, true if this is a thank you message, false if it is not.

calling_tag - The view in question.

Third Party Integrations

Google Tag Manager Event Tracking

ActionTag integrates with Google Tag Manager Event tracking so that you can more readily understand how users are interacting with your forms. This integration is available on all form types. It is reccomended that you utilize Universal Analytics in your Google Tag Manager implementation.

Google Analytics Events

This is the data that will be passed to Gogle Analytics via Google Tag Manager upon successful integration. This data will be viewable in the Google Analytics Events reporting interface.

For each Event Tracking Parameter, using the macro selection, input each of the User-Defined Variables that were created in Step 3 to their appropriate slot.

The Tag should have Non-Interaction Hit set to “True”, so that pageviews for ActionTag form interactions are not recorded in duplicate.

Set the trigger for the Universal Analytics tag to the one created in Step 1.

Use the preview setting in the Google Tag Manager container to look at one of your forms to debug and confirm the integration is enabled successfully. Do this by submitting a form and watching (in the Google Tag Manager debugger) for your new Form Events tag to fire successfully.

Via the Data Layer tab in the debugger, inspect the data layer to make sure that the correct information has been passed.

Publish the container and ensure that it appears on all pages where ActionTag is present.

Enhanced Ecommerce tracking in Google Tag Manager

Google Tag Manager (GTM) exists to help you load your Google Analytics (GA) and any other arbitrary JavaScript or HTML tags in the same “container”.

Google Analytics also has an Ecommerce reporting feature, designed to mimic a system where items are added to a cart and then the cart is checked out. We have configured ActionTag to fire Ecommerce events on successful contribution and event form submissions. In the case of a contribution form submission, only a single item will appear in the cart for a transaction. In the case of an event ticket purchase, multiple items can will in the transaction if different ticket types are purchased by the supporter.

If you are using Google Tag Manager with Google Analytics on the same site where you embed ActionTag, and you enable Google Analytics Ecommerce collection in both Google Analytics and Google Tag Manager, the Ecommerce data should pass to the appropriate Google Analytics Ecommerce reports with the following configuration steps.

Ensure that Google Tag Manager is installed on your online form, as follows:

In Online Actions: Provide your Google Account ID Number on Step 1 of the Form Builder.

In NGP: Embed the Google Tag Manager source in the body on your form.

If you are embedding ActionTag on your site, you can install a new GTM container on your site or utilize an existing GTM container.

In Google Analytics, navigate to the property that will be utilized for tracking enhanced Ecommerce. For each view that requires Ecommerce, navigate to the view settings, ‘Ecommerce Settings’, and Enable Ecommerce. Ensure that Enhanced Ecommerce Reporting has been enabled as well.

In Google Tag Manager, create a Custom Event trigger type that is set to fire on all custom events with the event name: transaction.

Now create a Universal Analytics tag in Google Tag Manager with type “Page View”. Typically Google Tag Manager is used to house a Google Analytics tag to track page views. You can track your Ecommerce data to this same web property. Set the Tracking ID to the same property that tracks pageviews.

While configuring the tag, click “More Settings” and expand “Fields to Set.” In the “Field Name” section enter in “nonInteraction” (case sensitive), and in “Value” enter in “true.” This step ensures that pageviews are not double-counted when form events fire.

Also under “More settings”, expand “Ecommerce” and click the checkbox for “Enable Enhanced Ecommerce Features” as well as the “Use data layer” checkbox.

Once your tag has been configured, trigger the tag using the transaction Event trigger created earlier.

Use the preview setting in the GTM container to look at one of your forms to debug and confirm the integration is enabled successfully. Do this by submitting a form and watching (in the Google Tag Manager debugger) for the Ecommerce tag to fire successfully.

Via the Data Layer tab in the debugger, inspect the data layer to make sure that the correct information has been passed.

Publish the container and ensure that it appears on all pages where ActionTag is present.

Google Tag Manager utilizes a DataLayer in which information is stored in a JavaScript array and sent to the GTM container. The following code snippet is an example of data that would be passed into the GTM DataLayer upon a successful contribution form submission.

alterFormDefinition

Simple

A simple use case is to override some attribute of the definition:

// Implementation of an alterFormDefinition Callbackvar alterFormTitle = function(args) {// Note, changing this title will not make a visual change unless the title is// used in the template which it's not by default in ActionTag.
args.form_definition.title = "This title has been overridden";
$('.status').html("<pre>Form Title: " + args.form_definition.title + "</pre>");
// Must return the altered object so it will be usedreturn args;
};

Intermediate

A bit more complex example is to alter something within the form definition. Let’s say you want to change the contents of the Header HTML markup.
Note, in this example we are using the Underscore module to iterate over the elements

In this case we are creating a new fieldset for Name, moving the name fields into that fieldset, removing them from their original fieldset (ContactInformation), and changing the title of the Contact Information fieldset to Address to better indicate its purpose.

Redirect based on recurring or contribution amount values

Perhaps you want to change where a donor goes after form submission in case they choose to give over a certain threshold or choose to give a recurring contributon. Using the preSegue callback you can look at the submitted values and make conditional redirects based on that information. Note, in practice you probably only want to use one of these two conditionals, but both are shown in the same example below for expediency:

You could then call the variable contribAmount to pass off to your analytics service.

Alter country list

If you want to alter the list of countries on your forms, the following example shows you how to remove a country, rename a country, or potentially insert a new option, all using the postRender callback. Note: if adding a new country, make sure you map it back to an existing value so the address is entered to the system in a way we can process

var alterCountries = function(args) {
// Remove a country by the value in the dropdown
var removalItem = document.querySelector('select[name=Country] option[value="XK"]');
removalItem.parentNode.removeChild(removalItem);
// Rename a country publicly (but will map to the existing value in the database)
var renamedItem = document.querySelector('select[name=Country] option[value="VI"]');
// desired new text to display
renamedItem.innerText = 'US Virgin Islands';
// Insert a new country (not recommended, only use it to map a new entry to an existing value)
// replace "Dominican Republic"with the name of country that comes right before the country you wish to add
var previousCountry = document.querySelector('select[name=Country] option[value="EE"]');
previousCountry.insertAdjacentHTML('afterend','<option value="Essos">Essos</option>');
}
var nvtag_callbacks = nvtag_callbacks || {};
nvtag_callbacks.postRender = nvtag_callbacks.postRender || [];
nvtag_callbacks.postRender.push(alterCountries);