Add a Donation Form to Your Organization's Facebook Page

Created on: Mar 11, 2011 7:43 AM by Noah Cooper, Convio, Inc. Last Modified:  Sep 29, 2011 4:43 AM by Noah Cooper

This document explains how, following a few simple steps, you can add a donation form to a tab on your organization's Facebook page.

 

Before I dive into the how-to, I'll go ahead and address a few FAQ:

 

1) "So this is really just like a normal donation form? How is the donation reflected in Convio, e.g. in Constituent360 and Reporting?"

What we'll be using here is Convio's Donation API, so yes, despite being presented inside of Facebook, donations will process just like they would through any other donation form on your Web site itself. So all of the reports you'd use for any other donation can be used for these gifts made through your Page, and all of the data will show up in Constituent360 as usual.

2) "Wait, Facebook.com isn't served over https, is this secure?"

Absolutely. Despite the fact that Facebook itself is served over http, since the donation itself is posted via https, all of the donor's data is transmitted securely. Of course, donors who don't understand such technical details may be concerned by the lack of a lock icon in their browser's address bar, so it may not be a bad idea to include a link to a normal donation page atop the form, e.g. "Make a secure donation using the form below. If you'd prefer to donate through our Web site, visit https://www.foo.org/site/Donation2?df_id=XXXX.".

3) "Where does a donor go when they click 'Submit'? Do they get taken out of Facebook to my Web site?"
Nope! Donors will stay within Facebook.

4) "That Facebook newsletter sign-up form was a piece of cake, but this seems to be a bit more technical, and my organization doesn't have the skillset to implement this in-house. Can Convio assist with deploying this for me?"

Convio does indeed over a low-cost Services engagement for organizations who need assistance with implementation. If you're interested, contact your Account Manager for further details.

 

OK, now let's get to it ...

 

Step 0 is a very important one -- as I mentioned above, this donation form will use the Donation API to process gifts (don't worry, you don't need to know how to use the API necessarily -- the code will do that for you). In order for this to work, your site's API Key must be configured. If your organization hasn't done this yet, go to Site Options and then the Open API Configuration tab, and click Edit API Keys. You just need to enter any value for "Convio API Key". Don't worry about any of the other options on the Open API Configuration screen for this project. If you don't see "Site Options", open a Convio Support ticket and someone will assist you.

 

1) In Convio, create a new donation form (either from scratch or by copying one of your existing forms). For the purposes of this example, we'll want to limit the donation form to only asking for the following fields:

 

  • Standard Donation Level
  • Billing Title
  • Billing First Name
  • Billing Last Name
  • Billing Address 1
  • Billing Address 2
  • Billing City
  • Billing State/Province
  • Billing ZIP/Postal Code
  • Email Address
  • Email Opt-In
  • Payment Type
  • Buttons

 

As you can see, this is a simple one-time gift form with no bells and whistles. This is so that this example can be as widely applicable as possible, but you can certainly add additional fields to the form as needed such as monthly giving options or perhaps designated or memorial giving.

 

Be sure to configure the autoresponders as you would normally. Again, despite the fact that our donation form will be displayed in Facebook, it's still going to function like any other donation form would and autoresponders will be sent.

 

2) Download the attached HTML file. This file contains the code you'll need to update and drop into Facebook.

 

3) Open facebook_donation.html in your favorite text editor such as Dreamweaver. You'll need to make the following updates to the code:

 

  • Replace {headline} with the headline to appear atop the form (e.g. "Donate to American Health Society").
  • Replace {intro text} with the text you want to appear below the headline (e.g. "Use the form below to make a donation today."). This is a good place to include the link I referenced above for donors who prefer to make donations directly through your Web site.
  • Replace {form id} with the ID of the form you created in Step 1. You can find your form's ID by going to the Online Giving section of Convio Fundraising, and clicking Manage on your donation campaign. Under your form's name, you should see "Form ID: XXXX".
  • Replace {level id 1} and {level value 1} (and so on) with the ID and dollar value of each donation level configured on the form created in Step 1. You can find the donation level IDs by going to the second step of donation form setup, Configure Donation Levels. As needed, add additional options for additional levels, as the example only has 4, including a donor-entered amount. So, for example, if you have three levels at $25.00, $50.00, and $100.00, with respective IDs 1234, 5678, and 9012, and your donor-entered amount level has an ID of 3456, your code should look like this:
  •  

    <div class="field-wrap">
         <input type="radio" id="level_id_1" name="level_id" value="1234" checked="checked" /> <label for="level_id_1">$25</label><br />
         <input type="radio" id="level_id_1" name="level_id" value="5678" /> <label for="level_id_1">$50</label><br />
         <input type="radio" id="level_id_1" name="level_id"  value="9012" /> <label for="level_id_1">$100</label><br />
         <input type="radio" id="level_id_other" name="level_id" onclick="document.getElementById('other_amount').focus();" value="3456" /> <label id="level_id_other_label" for="level_id_other">Other:</label> <input id="other_amount" name="other_amount" onfocus="document.getElementById('level_id_other').checked=true;" onkeypress="return numbersOnly(event,true);" />
    </div>

    This example form is designed for forms where pre-defined donation levels are presented to donors, but instead, you can certainly use nothing but the donor-entered amount field if you like.
  • Replace {email opt-in label} with the text for the email opt-in checkbox label (e.g. "Yes, I would like to receive email from American Health Society").
  • Update the error and success messages that are displayed to donors with whatever text you like.

    //update the messages below as you see fit for your organization
    var transactionProcessingMessage='Processing, please wait ...';
    var errorMessageWarning='Error: Please correct errors highlighted below.';
    var requiredFieldErrorMessage='Required.';
    var invalidEmailErrorMessage='Invalid email address.';
    var donationAmountErrorMessage='A donation amount is required.';
    var thankYouMessage='<p>Thank you. Your donation has been processed.</p>';
    

    Note -- if your text includes apostrophes, ensure they are escaped, e.g. var transactionProcessingMessage='Processing, please wait ... don\'t go anywhere.';

  • (Optionally) Replace "Facebook Page Donation Form" with some other source code if you prefer. This source code will be recorded on all transactions made through your Page, and will be recorded as the Origin Source Code on any new constituent records created as a result of a donation on your Page, allowing you to track and target these donors over time.

 

4) Once you've finished the changes in Step 3 and saved your file, create a PageBuilder page in Convio, let's call it facebook_donation. Make sure to check the option "This is a secure Page that will be encrypted via SSL." on the first step of page setup. With the WYSIWYG disabled (do to the custom nature of this page, you'll want to be sure never to open the page with the WYSIWYG enabled), copy and paste your updated code into the page content and publish.

 

5) Open the PageBuilder page in your Web browser, using a URL like:

 

http://www.foo.org/site/PageServer?pagename=facebook_donation&pgwrap=n

 

... where www.foo.org is your non-secure Convio domain. Using the standard test credit card number (4111 1111 1111 1111), ensure that the form works correctly. Make sure that when you omit any required fields appropriate  error messages are displayed. Note that when using the test credit card, on successful transactions you'll get a thank you page with dummy donor info, not necessarily the info you input. Don't worry, that's expected. If everything looks OK, edit your PageBuilder page, and delete the following line then Save:

<input type="hidden" name="df_preview" value="true" />

 

6) Sign into the Facebook account you use to manage your Page. Go to http://www.facebook.com/developers/createapp.php and create a new application for your organization. Call it something like "American Healthy Society - Donate".

 

7) Once your app has been created, click the Facebook Integration tab on the left. Fill in "Canvas Page" with a name for your app, e.g. ahsdonate. Fill in "Canvas URL" with something like http://www.foo.org/site/, where www.foo.org is your non-secure Convio domain. Fill in "Secure Canvas URL" with something like https://secure2.convio.net/ahs/site/, where https://secure2.convio.net/ahs/ is your secure Convio domain. Fill in "Tab Name" with the text you want to appear on your tab (e.g. "Donate to American Health Society"). Fill in "Page Tab URL" with http://www.foo.org/site/PageServer?pagename=facebook_donation&pgwrap=n and "Secure Page Tab URL" with https://secure2.convio.net/ahs/site/SPageServer?pagename=facebook_donation&pgwrap=n, again changing out the domain names for your organization's. (Note: You'll need to change the pagename if you named your PageBuilder page something other than facebook_donation.) Click Save Changes.

 

8) Now you should be back on the main page for your app. Click on "Application Profile Page". In the left column, click "Add to My Page". In the pop-up that opens, select your organization's Page.

 

9) Go to your Page. You should now see your "Donate" tab on the left. Click on it to make sure everything looks OK. If so, click "Edit" and drag your tab up to where you want it to appear. That's it -- the form is now live, and donations should start flowing in!

 

Hopefully that all made sense, but feel free to post any questions or comments. And please do share any examples once you've had a chance to implement this on your Page!

Attachments: