Page Related Tools¶

How Tests Work¶

When a test is active, users who visit a page are “enrolled” with one variation or another, and see that version of the page. Enrollments are sticky between requests, so if a user reloads a page, or clicks away and then returns, they’ll see the same variation again.

If you’re using AK’s new sharing tracking tools, enrollments are also sticky across share links, so if a test is active when a user creates a share link, and then another user clicks on that link, they will see the same variation as the user who created it.

When a test is active, each page view, action, and share link has records attached which show the variations the user was enrolled in at the time. This data enables a calculation of which variations led to more actions.

Adding A New Test¶

To create a test, follow these steps:

1 click the A/B Tests link in the sidebar on the Pages Tab, then click Add test.

2 Optionally enter a name, some internal notes, and select tags to categorize your test.

3 Choose the test's scope, by selecting one or more pages which it will apply to.

4 You can choose how users will be allocated to the alternative groups. The default Balanced allocation divide new users evenly among the variations. A Custom allocation allows you to set numeric weights for each variation, and new users will be divided up based on their relative values. The Optimizing choice reveals an additional Optimize for field where you can choose one of several statistics you want to maximize, and the division will be automatically calculated to send more users to the best-performing variation.

5 Select one or more changes that you want to test in the test. Changes can include on-page text options such as the Page title or Page intro, layout controls such as Templateset, and post-action follow-up choices such as Sharing title and Twitter message.

• The Intro text variation field corresponds to the About text field for Letter and Petition pages, to the Introduction text field for Signup, Survey, Call, LTE, Unsubscribe and Whipcount pages, to the Ask text field on Donation pages, to the Host text field for Event Create pages, to the Signup text field for Event Signup pages, to the Please stay text field on Recurring Cancel pages, and to the Update card text field on Recurring Update pages.
• The Statement Lead-in variation field corresponds to the Statement Lead-in field on Petition and Letter pages; it has no effect on other page types.
• The Statement Text variation field corresponds to the Statement Text field on Petition pages, the Letter field on Letter pages, and the Script field on Call and Whipcount pages; it has no effect on other page types.
• The Survey Text variation field corresponds to the Survey Question Text field on Call, Unsubscribe, and Whipcount pages; it has no effect on other page types.
• The Donation Amounts, Default Donation, and Amount Order fields apply to the corresponding fieldss on Donation pages; they have no effect on other page types.
• The Recognize User field will modify the page setting that controls whether user recognition is disabled.

6 At the bottom of the page are spaces for two test variations, but you can add more variations if you want to test three or more alternatives. Enter values for each change field you selected in each of the variation sections.

• If you leave a change field value empty, no change will be made and the page's original value will be used.

7 Click Save and go to next step to view the test dashboard.

The Test Dashboard Screen¶

After saving a test you'll be brought to its dashboard, which summarizes the test and provides links to several useful features.

In the Test section, you can see the settings for the test. If you wish to change them, you can click the Edit link.

In the Pages section, all of the pages partaking in this test are listed.

You have some options for managing the pages:

• See what other tests are running on these pages by clicking Manage.
• Go to the individual pages by clicking View.
• Edit the individual pages by clicking Edit.
• Start or stop the test on a given page by clicking Start/Stop for that page.
• You can Start/Stop the test for all of the pages.

And you also have options specific to each variation:

The Apply links under each of the variation labels (A, B, etc) in the Pages section will stop the test and apply that variation to all of the pages.

The View links under each of the variation labels (A, B, etc) in the Pages section allow you to preview what the page will look like with that variation.

And finally, the Stats checkboxes let you choose whether that page should be included in the analysis of results at the bottom of the page.

Read more about Starting and stopping tests and Viewing statistics to learn what else you can do from this screen.

Starting and Ending Tests¶

From the test's dashboard screen, click the Start link for each page in the test that you want to start testing. A test doesn't have any effect for users until you start it by clicking the Start link on its dashboard screen.

After a test has run for a while, you can choose to end it by clicking the Stop link on its dashboard screen. When a test has been stopped, it will revert to its original appearance; new users will not be allocated to its variations, and any users who had previously been enrolled will no longer see the alternative version of the page.

You can start and stop a test more than once. The Trial Periods section of the dashboard screen shows the date and time each each period of activity started and stopped.

Instead of simply stopping a test, you can choose to implenent one of the variations by clicking its Apply link, and your page will be updated to match it. (This also stops the test if it had been running.)

Viewing Test Statistics¶

On the Statistics section of the test dashboard screen you can see results for each variation.

You can click the Refresh button to reload the latest statistics.

At the bottom of the page are a series of Display checkboxes that allow you to select which statistics you want to see.

If your test has multiple trial periods or multiple pages, there will be a series of Stats checkboxes next to each of them which allow you to show the performance for the selected subset of interactions. For example, if you start a test and then later decide you want to modify some of the test variations, you might want to be able to view just the statistics for after you made that change, so you could stop the test, make the necessary changes, and then re-start it; later, you would be able to view the statistics for the entire test or just the later period as desired.

Note that the statistics include all actions processed on a page while an A/B test is running, including those processed via the API. If the user interactions you process through the API do not incorporate the changes relevant to the A/B test, you will need to adjust the statistics accordingly.

Multiple Pages In A Test¶

You can run the same test on multiple pages. Simply add more pages to the Pages field, and the test will be active on all of them.

This only makes sense if you’re testing content that could be applicable across several different pages at once -- for example, if you were testing layout changes by comparing one templateset vs. another.

This simplifies creation of tests and makes it easy to aggregate statistics across multiple actions.

Multiple Tests On A Page¶

You can conduct several simultaneous independent tests on the same page. For example, you might independently test different page titles and different share images.

Users will randomly be assigned to all possible test combinations (1A 2A, 1A 2B, 1B 2A, 1B 2B).

From a test dashboard screen, find the Pages listing for one of the pages and click the Dashboard link to reach the page dashboard.

The Manage Page Tests dashboard shows all of the tests that are associated with a page.

Under the Tests section of the dashboard, you can manage the tests on this page:

• Add a new test by clicking the "Add" link.
• Go to the test dashboard for each test on this page by clicking on the test name or the "Dashboard" link.
• Stop or start a test on this page by clicking "Stop" or "Start" as appropriate.

The Trial Periods section gives you details about when each test was started and stopped, and allows you to choose whether to include those results in the Stats section.

The Variations section displays all of the variations for each of the tests on this page.

The Statistics display for a page will correlate activity across all test variations, using the test IDs to differentiate between them. For example, if you're running test 1 with two title variations (1A and 1B) and test 2 with two templatesets (2A and 2B), you'll see four separate sets of statistics contrasting the users who saw variation 1A and 2A against the users who saw 1A and 2B, those who saw 1B and 2A, and finally 1B and 2B.

If a page has multiple tests linked to it but you want to ignore some tests to focus on the results of others, you can use the Stats checkboxes next to each test to select which ones to include in the reporting.

Testing Page Layout Changes With Custom Fields¶

If you want to A/B test changes to your page layout, without creating a second templateset, you can add code to your templateset that modifies the pages' appearance based on a custom field and then A/B test changing that field's value.

For example, if you'd like to A/B test the value of including a thermometer-style display on your pages, you could create a custom page field named "disable-thermometer" and modify the progress_meter.html template to hide the thermometer display if that custom field had a non-empty value. Then you could run an A/B test in which some users had the custom page field set to 1 and others did not.

Similarly, you could A/B test changes to the colors or images used by your site's layout by adding code to your wrapper.html template that either did or did not include a block of CSS code depending on the value of a particular custom page field, and then run an A/B test that set the value of that field.

Accessing Test Information Via Templates¶

When you visit a page for which one or more tests are active, you can access information about the current user's enrollments via template variables that are available to the templates defined on the page's "Edit content" screen.

These template variables are also available to the templates of after-action messages sent by the confirmation email, tell-a-friend email, and notification email features.

If any A/B tests are active for the current page, the tests variable will contain a dictionary keyed by test ID, with values containing the following keys:

• test_id: the numeric ID of the applicable test.
• test.title: the admin-entered name or generated description of the test.
• variation_id: the numeric ID of the selected variation.
• letter: the letter code of the variation.
• trial_start: the date and time (in GMT) that the current round of testing began.

For example, you could modify the layout of your page header by including some code like this in your wrapper template:

{% if tests.123.letter = 'B' %}
  <div>Special Page Header</div>
{% else %}
  <div>Normal Page Header</div>
{% endif %}

Here's an example of the type of data you might find in tests for a page with two active tests:

tests.74.test_id = 74
tests.74.test.title = "Page title for Signup"
tests.74.letter = "B"
tests.74.variation_id = 93
tests.74.trial_id = 114
tests.74.trial.started_at = "2015-11-16T04:32:24"

tests.42.test_id = 42
tests.42.test.title = "Confirmation Changes"
tests.42.letter = "A"
tests.42.variation_id = 51
tests.42.trial_id = 219
tests.42.trial.started_at = "2015-11-25T05:14:04"

Accessing Test Information Via JavaScript¶

When you visit a page for which one or more tests are active, you can access information about the current enrollments via the ActionKit context.

After actionkit.forms.onContextLoaded has been called, if tests are active, actionkit.context.tests will contain an object mapping test ID keys to objects that include the following keys:

• test_id: the numeric ID of the applicable test.
• test: the admin-entered name or generated description of the test.
• variation_id: the numeric ID of the selected variation.
• variation: the letter code of the variation.
• trial_start: the date and time (in GMT) that the current round of testing began.
• changes: an object containing the changed values applied by this variation, with keys corresponding to the fields in core_variation.

Here's an example of the type of data you might find in actionkit.context.tests for a page with two active tests:

{
    74: {
        "trial_start": "2015-11-16T04:32:24",
        "trial_id": 114,
        "variation_id": 93,
        "variation": "B",
        "test": "Page title for Signup",
        "test_id": 74,
        "changes": {
            "page_title": "Please Sign Up"
        }
    },
    42: {
        "trial_start": "2015-11-25T05:14:04",
        "trial_id": 219,
        "variation_id": 51,
        "variation": "A",
        "test": "Confirmation Changes",
        "test_id": 42,
        "changes": {
            "email_enabled": true,
            "email_subject": "Thanks for Signing Up",
            "email_body": "<p>You signed up! That's great</p>",
        }
    }
}

Running Tests on Pages Hosted Outside of ActionKit¶

The A/B testing system is available for action pages hosted on your own CMS rather than within ActionKit, but the process of updating the page based on test enrollment requires some additional work.

The standard attribute overrides and template variables described above will not work to update your page's HTML, because the templateset rendering does not take place at the time the user visits the page.

However, you can still conduct A/B tests for externally-hosted action pages as follows:

• A/B testing of Facebook and Twitter share text and images will work automatically if you are using the new ActionKit share customization and tracking system.
• You can write custom JavaScript that detects A/B test enrollments using the technique described in Accessing Test Information Via JavaScript and then makes changes to your page content or appearance as desired.
• You can add a class="ak-test-rewrite" attribute to HTML elements which contain text which you would like to be rewritten as part of an A/B test as described below.

Templateset List View¶

You can access a list of all your existing templatesets by clicking Appearance and then Customize Page in the sidebar on the right of the Pages Tab.

Click on a column header to sort the list by that header. Click a second header to sort first by that header, and second by the previously selected header.

You Create A New Templateset by copying one of the existing templates.

Creating Templatesets¶

You'll want someone who knows HTML to make changes. Templates are a powerful tool but their flexibility means you can break them!

Before you begin creating templatesets we recommend reviewing the information about managing templatesets to help avoid unnecessary proliferation. You can find other detailed information in the Developer Guide under How To Customize Your Pages Using Templates.

You'll also need to pick an existing templateset to copy. The only way to create a new set is to copy an old one. The Original Templateset is the default we provide with the latest built-in functionality. We recommend that you copy this set, or one of your own that was created from the current Original.

To create a new Templateset:

1 Open your templateset list.

The list of available Templatesets is displayed. The Original Templateset is the default we provide with the latest built-in functionality. We recommend that you copy this set, or one of your own based on the current Original.

2 Copy a templateset.

The only way to create a new set is to copy an old one. Click Copy to the right of the Templateset you wish to start from to create a clone with "copy" appended to the name.

3 Name your new templateset.

On the Change Templateset screen:

• Name: Name your template. Required.
• Description: Include how this templateset is different from your others. Required.
• Language: Default is English. If this will be a foreign language set, select the language from the drop down. Use Templatesets along with Language settings to display pages entirely in another language, including error messages, privacy policy and any other text. Read more about Languages.
• Github Connection: You can connect a GitHub repository to your Template Set. This allows you to keep your Templateset in GitHub, while automatically sending the changes to ActionKit when you push. Changes made in ActionKit will never be sent to GitHub, it's a one-way connection. Read more about connecting your templateset to a github repository.
• Custom Templateset Fields: If you have created a templateset field, you'll be able to select it from the drop down in this section. Or click the + to create a new one.

4 Click Save. You will be directed to the Templates screen.

5 Edit your templates.

The Anatomy of a Page documentation describes how the templates work together to form each page type and may help you pick which template you want to modify.

You have a few choices for how you edit your templates:

• Edit in the ActionKit Admin: You can edit templates directly in the ActionKit admin by clicking on the Template name. The Change Template screen opens and the HTML is displayed. Other templates are available in the drawer on the left of the editor.
• Edit locally using manual uploads: Download the full set of templates from the Templates screen. Make your edits locally and upload the modified template(s) using the Upload templates files button. Most browsers will allow you to upload multiple templates, but you can also create a zip archive if you are on a slow connection.
• Edit locally using "Link local files": After downloading the templates, drag and drop the files onto the link local files dialog. As long as you keep this window open, we'll automatically upload the changed files, and try to reload the current preview window. Sorry Safari users, this feature not available.

You can customize your templates using Snippets. You can click to insert most snippets using the snippets menu at the top of the template if you're editing in the admin. Or cut and paste these into your template if you're editing locally.

You can also add your own templates. This does not allow you to create a new page type, but you can re-use the template code in any of your pages.

From this screen you can also select:

• Settings: Takes you to back to the Change Templateset screen.
• History: Displays a history of changes to individual Templates with who made the change and the time. Click on a change and then scroll to the bottom or click on "View diff" to see highlighted diffs.

6 Save and preview your changes.

Saving your changes allows you to work on changes to multiple templates before publishing. Templates with changes will be listed under "Changed pages" and marked as "Draft" under status on the Templates page.

Previews are available from the Templates screen and the Change Template page.

On the Templates screen, Use the auto-select to search for a page to preview. If you are using the Link local files or Upload template files, we will try to refresh the preview screen automatically. However, if the refresh doesn't happen automatically you can refresh manually, or click the preview button again.

On the Change Template screen, either click the "Preview" button or click the + to open the Preview drawer on the right hand side of the screen. You can use the auto-select to search for a page to preview. We also try to suggest relevant pages, based on the template you are editing, as well as showing pages you recently previewed.

Once you have a preview window open, you can use the forms, submit actions and navigate to other pages without leaving preview mode. As you make changes to templates, we'll still try to refresh the window automatically. For example, to work on the look and feel of error messages, you could load a Petition page, submit the form with an error and as you make changes to different templates, the preview mode will reload with the errors.

Warning

You're still viewing a live page in preview mode. If you make a donation in preview mode a donation is recorded in ActionKit and a charge is made to your credit card.

While you're previewing the changes, you'll see the preview toolbar at the bottom of your screen:

• Click Switch to see the same page with another Templateset.
• Click Exit Preview Mode to return to the normal published version of the site.
• Click Publish to make your changes live for all pages using the Templateset.

You can also preview how a templateset would look on an existing page by appending ?template_set=[TEMPLATE_SET_NAME] to the end of the URL.

For example, let's say we want to see how our templateset "dev" would look like on http://docs.actionkit.com/survey/test/.

We'd type the following URL into the browser:

http://docs.actionkit.com/survey/test?template_set=dev

7 TEST!

You can do a lot of things by customizing your Templates, but it's easy to make mistakes. If you make a mistake you can break your Pages in ways that may or may not be obvious to your end users.

Test new or modified Templates before making them public. You can do this by creating a page that uses the Template and taking action on the Page. Unless the changes are minor, you should view the Page in several browsers. If you're logged in as an administrator, you'll see a detailed traceback/error message for related problems to help with troubleshooting.

We recommend following a testing protocol whenever you make any changes to your Templateset. We've outlined a full testing scenario that you can use.

8 Publish.

When you are satisfied with your changes click Publish. Your changes are published immediately and applied to all Pages using this Templateset.

Adding A New Legislative Group¶

To activate state legislatures or to create a new target group from a subset of state or federal legislators (like Blue Dog Dems or House Democrats), you must first add them:

1 Click Legislative in the Targets section under Related tools on the Pages Tab.

2 Select Add Legislative Target Group.

3 Name the group. Pick something that will be obvious to others on your staff.

4 Select a type from the drop down (you can only select one per group, so if you want to target US Senators and US House Reps you need to create two groups).

5 Select one or more states for state legislative targets or to narrow federal legislative targets by state. For example, select U.S. Senate then enter "CA" to target Senators Boxer and Feinstein. If you don't enter a state, you'll get all legislators in the body you selected in every state (e.g., every state senator in all 50 states).

6 Narrow your target list further by party or individual if desired.

To limit to or exclude specific people click in the relevant box and select names or type to search by name or seat. You can also select records in bulk by copy-and-pasting in a group of district codes ("AZ_03 MI_13 CA_12") or a comma-separated list of names ("Conyers, Grijalva, Pelosi").

You'll see a running count of targets in the group at the bottom of the screen.

After you save your group, the name will be a selection in the Target groups box for all Petition, Letter, Call and Whipcount Pages.

Note

If you want to target any state legislative bodies, you must first activate each one following the steps above. Each state body you activate will then be available as a target group for all staff.

Overview¶

You can also create and select custom target groups. Custom targets can be anyone: Governors, school board members, CEOs, whoever you want. A custom target group can consist of one target or many.

Custom target groups can have the following jurisdictions:

• City and state
• City and country
• County and state
• State
• Country

By default, All users is selected, which means all actions on the Page are directed to all targets in the group.

Groups with a jurisdiction work like legislative targets where the target only receives actions from their constituents. Specifically:

• You can use snippets to show your users information about their target.
• Only users who we know live in the states or countries specified can take action on a Call Page (you can provide a fallback URL for others). Recognized users see the correct target automatically.
• Signature deliveries only include constituents.
• You can use the target constituents checkbox as a shortcut to limit a Mailing to users in the states or countries specified.

Adding a Custom Group¶

To start, select Add Custom Target Group on the Pages tab or click Custom in the Targets section on the Action basics screen of your Page.

Enter a name that’s descriptive (e.g. "Chamber of Commerce" for the group or "Chamber President" for an individual).

Select a jurisdiction if that's relevant. If you select a jurisdiction you must specify the targets jurisdiction (e.g. if you select state, we need to know the target's state).

Then add your target or targets by:

• Entering the relevant contact information in the boxes. To add additional targets to this group click the blue Add another special target link.
• Uploading a CSV of custom targets. The first line of the file should be a header row containing the column names. Column names can include: title, first, last, phone, fax, email, gender (for pronouns), state, country; of these, first or last is required.

We ask for the target's gender so you can use "snippets" in your bulk mailing to select the preferred pronoun for each target. For example, if you target state governors, the emails could say, "She supported this" for the female governors; "He supported this" for the male governors; and "They supported this" when gender is left null in the upload file, for any governors that prefer the prounoun They.

Once you add a custom target group, it will be available in the Target groups box on the Action basics screen during page creation.

Overview¶

Custom boundaries allow unique geographic areas to be defined for custom target jurisdictions or other local organizing needs. If you are targeting a local school board, electoral districts for a country other than the United States, or users who live in an affected watershed, custom boundaries can help!

Each Boundary belongs to a Boundary Group, which collects boundaries of the same type. So, the School District #23 boundary might belong to the Madison School District group, along with the other districts.

Custom Targets may use custom boundaries for their jurisdictions. This permits users to be matched to custom targets according to their location for letter, petition, and call pages, and for associated functions, like targeting a mailing based on a landing page.

Creating a Boundary Group¶

Start on the Pages Tab, under Targets in the tools sidebar on the right select Custom Boundaries. Then click Add boundary group.

Associating With Custom Targets¶

Once a custom boundary group has been created, it can be associated with custom targets. When setting up the custom target group, select custom as the jurisdiction. Then, choose the boundary group that this target group will use. For each target, select the corresponding boundary. (Multiple targets can share the same boundary.)

If uploading a CSV of custom targets, you can include a "boundary" field with the name of the corresponding boundary. Targets will be associated with the matching boundary.

In either case, the boundary must belong to the selected boundary group.

Managing Existing Boundaries¶

Start by selecting Custom Boundaries under Targets in the tools sidebar on the right of the Pages Tab. On this screen you can view a list of boundary groups, their names, counts and links to edit, hide, or delete them.

Clicking on a group's count ("15 boundaries") will show a list of its boundaries, each with a link to edit the boundary's name and shape.

If you click the group's id, you can edit the group name and description, and optionally upload a new file of boundaries. If an upload contains a boundary with a name that already exists in the group, the existing boundary will be updated from the upload.

Uploads to existing boundary groups do not delete existing boundaries, but you can delete obsolete boundaries from the group's boundary list.

Other Supported Features¶

• Mailings can target users within one or more boundaries, or boundary groups. For boundary groups, a user will be included/excluded if they are within any of the group's boundaries.
• Pages utilizing target groups with custom jurisdictions rely on the user's location to determine the target for that specific user. Because this is dependent on geocoding </docs/manual/guide/pages.html#geocoding>, users with inaccurate or missing latitude and longitude may not match as expected.
• Boundaries and Boundary Groups can be viewed and changed via the REST API.

Overview¶

Delivery Jobs have several uses. You can create a PDF for in-person delivery or press events. Delivery jobs are the first step in setting up a bulk delivery-- a mailing to a petition or letter page's advocacy targets with a link to a secure site where the targets can download signatures as a PDF or CSV file. A delivery job is created automatically to track downloads for batch delivery.

Creating A Delivery Job¶

Start by selecting Delivery Jobs under Targets in the tools sidebar on the right of the Pages Tab. Then click to Add petition delivery job.

Overview¶

ActionKit provides basic support for product sales and give aways. Products can be premiums, merchandise for sale, or something less tangible (for example, 'adopting' an endangered tiger).

Products are used with donation pages. If you have set up any products, you'll be able to select them in the More options section on the Action Basics screen when you create your page.

The default layout offers users options to select a product and to make an additional donation. You can change the layout, offer products with no option for an additional donation, or allow users to donate without selecting a product on a page with products by editing the donate.html template.

Our product system is not designed to function as a storefront. If you need shipping and tax calculations and fulfillment tracking, we recommend using an external storefront and integrating the data using our API.

Read about product settings under Adding products.

Adding products¶

Add new products by clicking the + next to the products box or from Page Related Tools.

Then enter a product name. The default templateset displays this name on the page, so use something short, descriptive and compelling. You can also enter an optional Admin Name which will never be displayed to the user, but whose existence will let you create two products with the same display name. For example, you could have a product "Gold Sponsor" with an Admin Name of "Annual Fundraiser" and another product "Gold Sponsor" with an Admin Name of "July Conference."

Add a description or, even better, a photo in the description section. If you have an image, enter the HTML for displaying the image in the description box (e.g., <img src=”url” alt=”Alternative text” height="XX" width="XX"/>).

Be sure to view the final page on site whenever you include a product in case you need to edit the layout, by editing the "Donate" template in the relevant templateset) or resize an image.

Enter a price for the product. Products can have a price of $0. By default users wiil be able to order a free product without making a donation on the page (although users will be offered the opportunity to donate). If a user only orders a free product the user won't be required to enter their credit card information.

If you indicate that a product is shippable, ActionKit will automatically ask the user to enter their shipping information, which is saved in the core_order_shipping_address table.

You can mark a product as "inactive" to remove it from the "product" selection box in step 1 of donation page creation and to remove it from any live pages (so future users can't order it).

Maximum order is often used to limit the number of free or below cost items one user can order in a session.

Use tags to categorize your products. Users are not associated with tags based on the products they order.

Suggested Ask Uses¶

Donation page: Pick a suggested ask formula on the Action basics screen for your Donation Page. The suggested ask determined by the formula is displayed to the user on the donation page along with any greater amounts entered on the Edit content screen.

If only one amount would be displayed, ActionKit will fall back to displaying all the amounts you entered on the Edit Content screen.

Mailings: Insert the suggested ask template tag in the body of your Mailing to display the amount defined by the formula you selected on relevant Donation Page. You must select a Donation Page with a suggested ask formula from the Landing page dropdown so ActionKit knows which formula you mean.

Implementation¶

ActionKit provides two sets of rules as examples, "Default" and "Default Recurring". You can edit or copy these or create a new rule set.

Suggested Ask Rules are based on either the donor's highest previous gift, 2nd highest previous gift, or gift average. Select the one you'd like to use under "Which amount". Imported donations are included.

The column on the left sets the thresholds that ActionKit will use to determine the suggested ask, shown in the column on the right. For example, users with a value above threshold two but below threshold three, will see the suggested amount ask for threshold three. You can have as many rows as you'd like in any set of rules.

The ask amount you enter on the $0 row ($25 by default) is the amount that will be shown to non-donors or users who aren't recognized.

You also have the option to exclude tags if there are donation pages you don't want included in the calculation. Be sure the page you want to exclude is associated with the tag you select here. You might use this if you do a one-time fundraiser for another group, or if you wanted to exclude unusually generous one-time gifts for a capital campaign.

Example¶

Here's an example of how this works: Susie has a highest previous contribution (HPC) of $150. If I use the default formula, I see that puts her above the $140 and under $160, so I look at the suggested ask for $160. Her suggested ask is $175.

I enter the following donation amounts on step 2 when I create my donation page: $50, $100, $200, $250, $350, $500, $1000.

When Susie follows a link from a fundraising email she'll see the following amounts: $175, $200, $250, $350, $500, $1000.

Overview¶

These are screens your end users can access to manage their own profile. You can have only one of each of these screens:

• login
• set/reset password
• view account profile
• edit account profile

Click Account Tools on the Pages Tab to see a list of URLs.

Your default Templateset defines the appearance of these screens. You can change your default Templateset here, but note that the Templateset you select will become your default set for all Pages.

Account Tool Templates¶

Each screen type has templates that you can edit to change its appearance. The templates are as follows:

• login.html, the login screen
• logout.html, the logout screen
• password.html, where users request a password reset email
• reset_password_email.html, the email with the link to reset a password
• reset.html, where users set or reset their password
• user_view.html, the "My Account" page (accessible at yourinstance.actionkit.com/me/)
• user_update.html, the "Edit My Account" page

Like other templates, you can edit all of these through the "Customize Page" link on the Pages Tab.

Though you aren't likely to need it often, it is possible to create account tools links that will use a templateset of your choice. Just add ?page=page_name to the link: for example, https://mysite.actionkit.com/login/?page=petition1 uses the templateset from https://mysite.actionkit.com/sign/petition1/.

Overview¶

Notifications are emails to someone aside from the action taker, prompted by actions on the Page.

You can use these for a variety of purposes including:

• sending an email to the honoree about gifts made in their honor,
• alerting field organizers to each new event created in an event campaign,
• notifying a campaign director every 1,000 new actions on a page,
• emailing your development staff for each new recurring commitment.

Create your notifications and then select the ones you want to associate with each page on the After action info screen. Each action can prompt multiple notification emails.

Notification emails will only send if there are values for the subject line, to emails, from email, and mailing body. So you can use conditional content to control whether the notification requirements have been met.

We provide a few sample notifications that you can use or customize:

• In honor of: This example shows how you'd prompt a notification email to the honoree after each gift in his/her honor. First you need to add an action field with the label 'action_in_honor_of_email' to the Donation Page template you'll be using. Then you can use the to line in the example -- {{ action.custom_fields.in_honor_of_email }}. The example also shows some conditional content you might include in the notification email by adding additional custom action fields to your template.
• Tell staff about monthly donation: In this example, the subject includes the criteria to prompt the sending of the email. Whichever staff you select from the list or enter in the "to" line will receive this notification after each new monthly donation is created. The body includes some conditional content.
• Notify every 1000: In this example, the send criteria is in the body and the subject includes conditional content.

Here are some other examples that aren't included in your instance but that you might add:

• Notify someone when a donation is greater than $250:

Subject: {% if action.order.total > 249 %}New $250+ Donation!{% endif %}

* Notify event hosts of new attendees:

To: {% for host in action.event.hosts %}{{ host.email }}{% if not forloop.last %},{% endif %}{% endfor %}

Subject: Subject {{ user.first_name }} has RSVPed for your event

Read about adding notifications.

Adding and editing notifications¶

The steps are:

1 Follow the Notifications link from the Donations section in the right sidebar on the Pages Tab.

2 You'll see we've got a few example notifications set up for you. You can edit or copy these or create new ones.

3 Name your notification then select from the standard email options shown for the wrapper, from line, etc.

4 Select the recipients for your notification.

Enabling fraud filters¶

If you want to use this service, you have to turn it on by clicking Fraud Filters under Donations on the Pages Tab. You'll see the two default filters. To turn these on, click the filter and select the Check Maxmind box. If the box isn't checked, the filter isn't enabled and won't work, even if you select it when you create a Donation Page.

• Default for users from Mailings: This applies to users with an AKID who follow a link from a Mailing to your Donation Page. These users are already in your database and receive email at the address used and are less likely to be fraudsters. Our default setting under Maxmind threshold is 90, meaning we only reject orders the MaxMind believes have a higher than 90% chance of being fraud.
• Default for users from Web: This filter applies to users who arrive at your Donation Page from any link aside from one in a Mailing. Here, the default setting is to reject orders from users coming in off the Web that MaxMind believes have better than 50% odds of being fraudulent. That's under 2% of orders across MaxMind's client base, according to the table on their site (http://www.maxmind.com/en/riskscore).

Turning these on tells ActionKit to apply the default filters to all Donation Pages. You can add additional filters and apply them on a page-by-page basis (although the two above will always be the defaults).

You might create additional filters if you want a super stringent option to apply to a particular Donation Page that you think will see a lot of new traffic and/or shut off the filter for Pages that you're only directing existing trusted donors to. For the latter, just add a filter and leave Check Maxmind unchecked.

Override your organizational default fraud filters by selecting the appropriate choices for a Page in the More options section on the Action basics screen.

As with any nontrivial change to your Donation Page, it's worth making some test donations when you set this up.

Overview¶

Tags are categories that you can associate with a Page or Mailing. They may represent issue areas or campaigns (e.g. food_safety or Paris_climate_talks_campaign).

You can use Tags to group Pages or Mailings. Tags are displayed on the Dashboard and the Browse all listing, and you can filter by Tag, so for example, you can quickly view the list of all the Tages you have created for a particular campaign.

Tags can also be used to group users for mailing targeting and analysis. Users who take action on a Page are associated with that Page's Tag(s).

Every user who takes action on the Page is associated with the Page's current Tags. There is no way to associate only some of those who took action on a Page with a Tag (for example, you can't tag only donors giving over $X on a page).

Read more about managing Tags including how to add Tags and reorder your Tag list.

Working With Tags¶

Add, edit or hide Tags from the Tags link under Other in the sidebar on the Pages Tab. This link brings you to a list of all your visible Tags.

You can reorder your Tags from this screen. By default, your Tag list is sorted from most to least frequently used.

Change the sort order by either clicking the column header you'd like to sort by or by dragging the rows into your preferred order. Then hit Save Tag Order. Tags will display in the new order in all tag-selection drop downs and in the filter section on the Browse all screens.

To add a Tag click the button and enter a name. Tag lists can get unwieldy so it can be helpful to establish a naming protocol for your organization and to keep Tag names short.

Overview¶

User Groups are categories that you can associate with Users and Pages. They are similar to tags but have some important differences.

User Groups can be used for mailing targeting and analysis. Users who take action on a Page are associated with that Page's Groups(s).

Every user who takes action on the Page is associated with the Page's Groups at the time of the action. This is a key distinction from Tags, which associates users with a page's current tags, meaning if you change a page's tags, a user may gain or lose tags as a result.

Read more about User Groups vs Tags to determine which situations are best for tags and which are best for groups.

Working With User Groups¶

Add, edit or hide Groups from User Groups in the sidebar on the Users Tab. This link brings you to a list of all your visible User Groups.

To add a User Group click the button and enter a name. User Groups lists can get unwieldy so it can be helpful to establish a naming protocol for your organization and to keep User Group names short; reserve additional context for the description field.

Overview¶

Custom page fields are a powerful and flexible tool that allows you to add a section of content or code to an individual page.

For example, if you want to ask users to tweet about an action they've taken, you could add a page field called "twitter" and include a suggested message specific to the page. If you have a Protect Parrots petition your sample message might be "Parrots are smart. I just signed to save them here: action_URL"

Page fields you've created are available on the Action basics screen for each page.

Use this syntax to include page fields in your templatesets or to reference them when creating a page: {{ page.custom_fields.YOUR_FIELD_NAME_HERE }}. Or, if your custom page field contains template tags or filters that need to be interpreted, then use this syntax instead: {% include_tmpl page.custom_fields.YOUR_FIELD_NAME_HERE %}.

Read more about Creating your Page fields.

Adding Page Fields¶

Follow these steps to set up and use custom page fields:

1 Click Custom Page Fields under Other on the sidebar on the right on the Pages Tab.

2 Click Add allowed page field.

3 Enter the name and other settings for your page field and then save. The name cannot be changed once the field has been created.

4 Add your custom field to a Templateset. Use this syntax to insert the custom field: {{ page.custom_fields.YOUR_FIELD_NAME_HERE }}.

If you want the field to display only if it's used on a particular page, use this syntax: {% if page.custom_fields.YOUR_FIELD_NAME_HERE%} Post this!: {{ page.custom_fields.YOUR_FIELD_NAME_HERE }} {% endif %}

5 Create or edit a Page and scroll down to the bottom of the Action basics screen.

6 Enter the custom field content by selecting your field from the dropdown in the Custom Page Field section and entering the content in the text box.

Special Page Fields¶

While generally you can use any name you'd like for your custom fields, there are a few special cases in which custom fields with a certain name trigger a built-in behavior at ActionKit.

• A value in a field named redir will cause all requests to view this action page to be redirected to this URL.
• A value in a field named migration_redirect_url will cause requests from users who are not logged in as ActionKit administrators to be redirected, which can be especially useful when first setting up ActionKit.
• A value in a field named ak_recaptcha_enabled will override your site's default settings for enabling captchas.
• A value in a field named image or og_image will be used as the sharing image URL for Facebook if one has not been set on the After-Action Info screen.
• A value in a field named description or og_description will be used as the sharing description text for Facebook if one has not been set on the After-Action Info screen.
• A non-blank value in a field named disable_cookie_prefill will turn off prefill on the associated page.

Overview¶

Another way of handling bogus or malicious requests is to enable captcha tests.

Captcha is an acronym for "Completely Automated Public Turing test to tell Computers and Humans Apart" and refers to an approach in which tasks which are easy for people to solve, but difficult for computer programs, must be completed in order to perform an action. The most common form of captcha has traditionally been to read and enter words that appear in a garbled or noisy image, but current versions more often involve pictures or audio recordings.

ActionKit's captcha support is provided via Google's reCAPTCHA service. A page that has captcha tests enabled will show a small reCAPTCHA logo in the bottom right corner. ActionKit invokes the "invisible captcha" mode, which attempts to recognize "trustworthy" users and allows them to bypass the captcha challenge altogether; other users will be presented with a captcha challenge when they submit the action form.

Enabling Captchas¶

You can enable captchas for an individual page by setting the "Recaptcha Enabled" custom page field to "Enabled".

Alternately, you can contact ActionKit support and request that this feature be turned on by default for all pages on your site. (If you do this, you can override it to turn the captcha checks off for a particular page by using the "Recaptcha Enabled" custom page field set to "Disabled".)

Captchas are never used on unsubscribe, donation, recurring donation update, or recurring donation cancel pages; attempting to enable this feature on any of these pages will have no effect.

Captchas for Pages Hosted Outside of ActionKit¶

Captchas work as usual if you host your pages outside of ActionKit, as long as the domain name of the site where the page is hosted is included in the client domains list. If the site's domain is not included in the client domains list, any actions attempted on that page will be declined with a "Bad Request" error.

(You may also encounter problems if you are using a locally-modified version of actionkit.js hosted on your servers, rather than loading it from our servers as recommended.)

Integrating Captchas With REST or AJAX Requests¶

Authenticated REST API requests do not require captcha values, as they are protected by the underlying password authentication, but if you want to submit an action from a page on your own server via unauthenticated REST or AJAX to an ActionKit page that has captchas enabled, you will need to perform the challenge on your site before sending the request.

First, ensure you are including actionkit.js on your page. Without this, the Captcha challenge may appear but ActionKit won't know whether it was successful or not, and we will reject the action with a Bad Request error. As noted above, make sure you link to actionkit.js from our servers rather than using a locally-modified version of actionkit.js hosted on your servers:

<script src="https://docs.actionkit.com/resources/actionkit.js"></script>

It's important to note that actionkit.js requires JQuery, so you must include JQuery 1.8 before loading actionkit.js or you'll get errors like $ is not a function. (Other versions of JQuery may work as well, especially if you are using JQuery Migrate.)

You must also add the following script tag to your page's head tag:

<script src="https://www.google.com/recaptcha/api.js" async defer></script>

Finally, add the recaptcha widget to your page in one of the following ways:

• (Recommended) Attach the "invisible" behavior to your submit button:

<form id="your-form">
  ...
  <script>
    function gotCaptcha() {
      document.getElementById("your-form").submit();
    }
  </script>
  <button class="g-recaptcha" data-callback="gotCaptcha"
    data-sitekey="6LetQiEUAAAAAC5mkK_YsHGJjLE7vxjMTIaNn3MA">Submit</button>
  ...
</form>

• Place the "I am not a robot" checkbox anywhere within your form:

<form>
  ...
  <div class="g-recaptcha"
    data-sitekey="6LetQiEUAAAAAC5mkK_YsHGJjLE7vxjMTIaNn3MA"></div>
  ...
</form>

You can read more about implementing the reCAPTCHA challenge in Google's documentation.

Set up an endpoint¶

To use the Push API, you will need an endpoint that can handle incoming POST requests.

This could be your own webserver, or a service like zapier or AWS Lambda. For testing, Request Bin or Webhook.site may be useful.

As an example, this server code accepts requests at a URL like http://example.com/actionkit/log_action, and logs the emails of action-takers:

@app.route('/actionkit/log_action')
def actionkit_logger(request):
    if request.method == 'POST':
        data = request.get_json(force=True)
        if 'user' in data:
            log('Action taken by user email: %s', data['user']['email'])
        else:
            log('Unexpected request to log_action: %r', data)
    return 'ok'

You can use a tool like httpie to send test data to your endpoint to make sure it is working correctly.

Create the Push API Endpoint in ActionKit¶

Under Pages -> Related Tools -> Other, you'll find 'Edit Push API Endpoints', which will take you to a list of your existing Push API Endpoints. Click Add endpoint to create a new one.

• URL: the URL that will accept incoming push requests (required)
• Name: to identify this endpoint elsewhere in ActionKit (optional).
• Triggers: a list of conditions which trigger a push request to this endpoint. Note that this list is in addition to any endpoints configured per page in a page's After-action info section. More below. (optional)
• Rate Limit: the maximum number of pushes per second that we'll send to this endpoint.
• Retries: the number of retries per push that will be attempted if delivery fails.

Confirmation¶

REQUIRED: before your endpoint can receive push requests, you must confirm it.

When you save an endpoint, AWS SNS will send a confirmation message to the endpoint URL containing a SubscribeURL. You should retrieve this URL to confirm the subscription. (Copy-pasting it into a browser window, or using httpie or curl is fine.)

If you change an endpoint's URL, you will need to confirm the subscription again.

If you lose the confirmation message before confirming the subscription, you can have SNS send another by simply re-saving the endpoint in the ActionKit admin.

Saving an existing endpoint (even if only changing non-URL fields like triggers) will cause confirmation messages to be send, but you can ignore these as long as the endpoint is already confirmed.

Authentication¶

If needed, you can specify authentication credentials in the endpoint URL like https://user:password@domain.com. Only Basic and Digest authentication are supported, see AWS documentation for more information.

Push Triggers¶

A push to an endpoint is triggered when the endpoints' configured conditions are met. For actions on pages, a push can be triggered in any of the following ways:

• After-action: action on page with the endpoint set in the page's "Push notification" after-action
• Page Type: Action on a page type matching the endpoint's configured trigger
• Everything: Any action for an endpoint set to trigger on "Everything"

Endpoints just need to match one of those conditions; that is, you don't need to have both the page type and after-action configured. (And unchecking a page's "Send pushes" will not turn off pushes by page type!)

Also, a single action can trigger multiple pushes if it meets conditions for multiple endpoints.

Note: "Everything" includes import actions, and will include non-action triggers at some point as well.

How to add a Push API Endpoint to a page's after-action¶

In the "After-Action" step of page creation, there is a section called Push API. Check the box and choose by name the endpoints that should receive a push when a user completes an action on this page.

Format and Content¶

The Push API sends pushes as POST requests with JSON-encoded data. The push request content is based off the REST API's representation of objects relevant to the trigger: actions, users, etc.

As such, the Push API is designed to interoperate with the ActionKit REST API, though not every application requires this.

For an action-triggered push, the request data will contain the keys action, page, and user with their respective API representations, as well as type ("action" in this case) and timestamp with the time the notification was generated.

Here's an example of an action-triggered push request:

{
  "action": {
    "akid": ".1595942.pnNSn4",
    "created_at": "2021-09-28T18:55:05.883198",
    "created_user": true,
    "fields": {},
    "id": 153187,
    "type": "Signup",
    "updated_at": "2021-09-28T18:55:05.942574",
    "user": "/rest/v1/user/1595942/",
    ...
  },
  "timestamp": "2021-09-28T18:55:06.071123",
  "type": "action",
  "page": {
    "actions": "/rest/v1/action/?page=12",
    "allow_multiple_responses": false,
    "cms_form": "/rest/v1/action/2/",
    "created_at": "2022-09-15T20:51:55.226010",
    "fields": {},
    ...
  },
  "user": {
    "actions": "/rest/v1/action/?user=1595942",
    "address1": "",
    "address2": "",
    "city": "Madison",
    "country": "United States",
    "created_at": "2021-09-28T18:55:05.882540",
    "email": "[email protected]",
    "first_name": "Puyic",
    "last_name": "Jujayiwo",
    "resource_uri": "/rest/v1/user/1595942/",
    "source": "website",
    "state": "WI",
    "subscription_status": "subscribed",
    ...
  }
}