In my experience, one of the most challenging aspects of creating an iDonate SDK implementation has always been the ReCaptcha requirements. This article should serve to de-mystify the process of configuring ReCaptcha to work with the iDonate SDK.
Part I: The Google Side of Things
The first step to a ReCaptcha implementation is to head over to your Google Account Admin Section and register your domain for use with ReCaptcha.
Fill out the form on the Create ReCaptcha section. Completing this form will grant you two unique keys: The Site Key and the Secret Key. This is all you need to do on the Google side of things. Now, you can move on to the next step, the iDonate side of things.
The iDonate Side of Things
To continue, you will need to gather your Secret Key and your Organization ID. Contact the iDonate Support Team with a subject relating to ReCaptcha, and include your Secret Key and Organization ID.
At this point, our team will configure your organization to be associated with the ReCaptcha you have created. Now, you are ready to implement your ReCaptcha.
Part III: Including Your ReCaptcha on Your Site
To begin the ReCaptcha/iDonate experience, first we will need to include the necessary external scripts: One for ReCaptcha, and one for the iDonate SDK (pictured at right as Required Scripts).
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
<script src="https://unpkg.com/@idonatedev/idonate-sdk@1.0.0"></script>
ReCaptcha has a lot going on under the hood. However, as a user, you only need to be concerned with a narrow range of data to achieve a working implementation. Let’s take a look at how ReCaptcha looks when included in HTML (pictured at right as ReCaptcha Div):
- Class: This will always be set to “g-recaptcha”. This will indicate to the ReCaptcha script that this is the div it will be working with.
- Data Site Key: This is the Site Key that you received when you registered your domain with ReCaptcha. Remember, never include the Secret Key in your HTML.
- Data Callback: The avenue by which the ReCaptcha Token travels. This is the function that is called when the user completes the ReCaptcha prompt. In this case, we have a function called setRecaptchaToken, which, as its name suggests, takes the token returned from the ReCaptcha as a parameter, and stores it in memory for use with the iDonate client.
- Data Error Callback: This function is called if the ReCaptcha prompt results in an error.
- Data Size: This is the form the ReCaptcha prompt will take. The most familiar ReCaptcha data size, the checkbox, is included here. The other data size that is commonly used is ‘invisible’. More on that one later, as it requires a slightly different pipeline.
Now that ReCaptcha is configured, we can now utilize the iDonate SDK to complete transactions.
Required Scripts
ReCaptcha Div
Part IV: Using ReCaptcha on Your Site
Now, we can introduce the rubber to the road. Processing a transaction with the iDonate SDK has a lot of moving parts, but thankfully, for this subject, we only need to focus on the parts that require a ReCaptcha token. Let’s begin at the function that uses the ReCaptcha information to process a transaction, the createDonation method.
It may not be apparent on the surface where the ReCaptcha information is used. However, upon checking the schema of the CreateDonationRequest object type, we can see where it comes into play.
For those unfamiliar with TypeScript, basically this just means that the CreateDonationRequest object type is comprised of the RecaptchaSecuredRequest object type, then the rest of the properties described afterward within the brackets. Here’s what the RecaptchaSecuredRequest object type looks like (pictured).
As the comment in the code suggests, the ReCaptcha Token is defined during the previously mentioned Data Callback function.
The RecaptchaType object type looks like this (pictured). In most implementations, the Recaptcha Type will be Organization.
So, now that we have a complete view of what a RecaptchaSecuredRequest looks like, let’s take a look at the pipeline that leads to a successful use of the createDonation method:
- User enters billing information into HTML form.
- User completes ReCaptcha prompt.
- Upon prompt completion, ReCaptcha automatically passes the ReCaptcha token to its Data Callback function. This is where the ReCaptcha token will be stored in memory.
- Developer-defined function compiles a CreateDonationRequest object from the previously mentioned information.
- User presses the “Donate Now” button.
- The On-Click function assigned to the “Donate Now” button passes the newly-created CreateDonationRequest object to the createDonation function as its parameter.
- Transaction is completed.
The createDonation Method
The CreateDonationRequest Object Type
The RecaptchaSecuredRequest Object Type
The RecaptchaType Object Type
Part V: Review
So, to recap (no pun intended), let’s go over the process of configuring and utilizing ReCaptcha with the iDonate SDK:
- Register your domain for ReCaptcha via the ReCaptcha Admin panel to receive your Data Key and Secret Key.
- Contact our Support Team with your Organization ID and Secret Key.
- Configure ReCaptcha on your site using your Data Key.
- Build your CreateDonationRequest object using the ReCaptcha token generated by the ReCaptcha div's Data Callback function.
- Pass your CreateDonationRequest object to the createDonation function of the iDonate SDK.
- Transaction complete.