This lab note corresponds with the release of Seamless Donations 4.0.15. While this release took longer to complete than I would have liked due to some family circumstances, it’s a large release with some very important compatibility options that should make life easier for many Seamless Donations users. It also adds a Donations This Month widget to the core plugin.
Seamless Donations is a plugin that runs inside of WordPress and WordPress is a program that runs in the environment created by hosting providers. Since hosting is a very big business that often runs on extremely tight margins, one key to success for hosting providers is tuning their operations stack to take maximum advantage of their resources. As a result, each host — even those with very similar stacks — is ultimately different from the next.
Some hosts install default configurations. Others change up their security protocols. Still others have implemented features and protections in response to situations they’ve found themselves in over the years. The point to all this, as the title says, is that all hosts are different.
This fact of life can make things difficult for developers and users, because while all hosts are different, we developers need to produce one version of our plugins that are intended for all hosts. As you might imagine, there is an inherent conflict in that reality.
Adding to the challenge, not only are the hosts different, so are many of the machines your donors use to access your sites. A donor could be on a Mac or a PC, on an iPhone or an Android device. He or she could be using modern technology, or still be clunking along with XP or an ancient version of Android. You just never know.
Over the past year, many of you struggled with these issues, particularly when it came to caching and protected files on your servers, and browser and JavaScript issues on the client machines. These problems will never truly go away, but the purpose of Seamless Donations 4.0.15 is to provide you some options to tune your implementation for your situation.
The new Host Compatibility Options feature
Seamless Donations 4.0.15 adds the new Host Compatibility Options sections shown below.
Let’s look at each of these settings in turn.
Process Form Via
This feature is designed to overcome some file execution challenges presented by some hosts. Here’s what’s going on. After a donation form is presented to a user’s browser and the donor clicks on the Donate button, Seamless Donations executes what’s called a form action in HTML. The donor’s browser is redirected to a file in your Seamless Donations plugin directory called seamless-donations-payment.php.
I added this capability back in April, in the 4.0.5 release [lab notes]. I moved the payment processing code from JavaScript on the client side (where we were running into no end of compatibility problems) to the server.
Nearly all of the end user machine problems went away, but over time, a new problem cropped up. Some hosts won’t let a user redirect to standalone .php file. All sorts of errors cropped up, from basic access denied errors to file not found errors, to just simply odd behavior.
What Process Form Via allows you to do is change where the form action redirect goes when a user clicks the Donate button. Rather than redirecting to the standalone .php file, it redirects the user back to the page he or she is currently viewing — and then that page redirects the user to PayPal, after all the transaction logging and pre-processing work is done.
Like the rest of the host compatibility options, this one’s not a breakthrough. It’s just an alternate way of processing the form. But it might help some of you who’ve been stymied by this problem.
Form Nonces
The form nonce capability at the initial processing of the Seamless Donations donation form is what you might call a belt and suspenders security feature. Nonce is a term that means “number used once,” and is often used to key code form submissions so that the system knows that the form it’s processing is the form that was actually submitted. This is valuable, because it helps to prevent bad guys from spoofing form entry data.
For some forms (like in the admin dashboard for WordPress), form nonces are absolutely critical. But on the front end, on a form that’s just submitting contact information and isn’t retrieving anything, nonces are good, but not essential.
Some users have run into problems with nonces and caching, because the various caching systems sometimes didn’t issue a new nonce code, and the Seamless Donations security element considered those duplicated-via-the-cache submissions to be spam or worse.
Don’t check this box unless you’re running into a challenge, but if you are, telling Seamless Donations to ignore the donation form nonce value is reasonably safe and may solve a caching problem.
Browser-based IDs
Caching has turned out to be a constant, never-ending challenge for Seamless Donations users. The idea of caching is that, to reduce the load on the server, pages aren’t constructed dynamically, but are stored in their already generated form and fed to users. This works fine for, say, blog posts. But it’s terrible if you need to serial number encode something, like the actual transaction ID for a donation.
Caching is also a challenge because it happens in places most users don’t know about. For example, many of you are familiar with caching plugins, and you have some control over those. But many hosts also cache pages at the server level, and some even cache pages at the edge of the network, at distribution centers located around the world. Sometimes you can specify that a certain page shouldn’t be cached, but some of the cheapest hosts cache anyway, and just don’t tell you.
A key reliability component that I introduced shortly after releasing the 4.0 release was the transaction table and transaction IDs. This table stores all the incoming information from the form before it transfers off to PayPal (or some other payment gateway, if I ever get any implemented). Each transaction ID has to be unique — absolutely unique. Unfortunately, when the transaction ID is computed on the server, some caching implementations wind up feeding the same ID to different users, resulting in Seamless Donations caching what it thinks are duplicate transactions and being unable to log the donation.
It is, without a doubt, best if transaction IDs are generated on the host. That’s because, if you don’t have a caching issue, you know your transaction IDs are being generated in the identical way for every single user who interacts with your donation site, regardless of what machine he or she is using.
But, it doesn’t always work. To that end, I’ve implemented an option that lets you move the ID generation computation from the server to the client, so instead of it running inside WordPress in PHP on your server, it runs in JavaScript inside your donor’s browser. When everything works, and the user’s browser and JavaScript are modern and compatible, this works just fine. But for older machines, JavaScript implementations, and browsers, not so much.
By the way, the mechanism used to achieve this is really slick. If the Browser-based ID option is selected, instead of inserting a GUID into the page to be downloaded, a code string is inserted instead. On the browser side, a very small jQuery selector checks to see if that string is in the DOM, and if so, it calls a UUID library and generates the UUID, inserting it right back into the form. It’s all of five lines of jQuery code on the browser side and it’s efficient as heck.
But that’s the choice. If you can’t get transaction IDs to generate uniquely on the server, turn on Browser-based IDs. It may introduce a bit of incompatibility for luddite donors, but it will bypass most of the caching problems you might have — particularly if you also turn on the Form Nonces option (which actually disables the form nonces).
Donations This Month widget
Seamless Donations 4.0.15 adds a Donations This Month widget. While the Basic Widget Pack adds five additional widgets, it seemed only fair that the core plugin had a widget to provide some donation information. Try it out. It’s cool. Remember, you can style everything with your theme’s CSS.
Additional features and fixes
Seamless Donations 4.0.15 adds a number of other features and fixes:
- Failover PayPal security option with cURL TLS support: As PayPal increases its security, so is Seamless Donations. This is just one of many additional security features that will need to go into Seamless Donations as PayPal migrates to an all-SSL world in September.
- Nicer styled beta labels: Just what it says. Rather than just text, beta labels are now gray blocks of text. But they’re pretty.
- Transaction IDs versioning: Transaction IDs are now prepending with version information, so if the time comes, code will be able to tell if they were generated by the server or a browser, and if there is any change in the format, what version of the transaction ID code was used to generate the ID. That will also help with ID parsing if the format has to change.
- Option to obscurify donor names shown in logs: It is now possible to obscurify donor names in logs, so if you have to post logs online or share them, donor names have been rendered indecipherable.
- Donor names in logs now default to obscurified names: This is now the default behavior, unless you use the option in the previous bullet to turn things off. Obviously, logs already generated won’t change, but if you clear your log, any new transaction will be obscurified by default.
- YouTube tutorial video in main admin panel resizes responsively: It’s a minor tweak, but now you won’t have the video extending beyond the boundary of its frame.
- Changed name of main Debug Mode section to Debug Options: There’s now more than one option, so it’s no longer just a mode.
- UK Gift Aid fix: Fixed a bug where UK Gift Aid selection was not being recorded. Unfortunately, the data wasn’t actually written to any transaction logging due to a code typo, so there’s no pre-existing gift aid data available for recovery.
There you go. It’s a big release. Stay tuned for the next release. I’ve got a long list of additional bugs to work on, and I’ll also be working towards the eventual full SSL-izing of the plugin to meet PayPal’s upcoming standards.
