Double the Donation Matching Integration
      Back to home
      1. Partnerships and Integrations | Double the Donation
      2. Integrate Double the Donation Into Your Platform
      3. Double the Donation Matching Integration

      Online Donations (Required for Online Donation Tools)

      This article walks through how to integrate an online donation tool with Double the Donation.

      Donation Form

      Confirmation Page

      Troubleshooting

      Page Reload

      Dynamically Generated Forms

      Async Issues

      Unlikely async issues

       

      The integration will collect information during the donation process and register that information with Double the Donation after the donation is complete.

      Donation Form

      Step 1: Include CSS and JavaScript on the page.

       

      Include the following CSS and JavaScript somewhere on the page:

       

      1. <!--Listing 1-->
      2. <script src="https://doublethedonation.com/api/js/ddplugin.js"></script>
      3. <link href="https://doublethedonation.com/api/css/ddplugin.css" rel="stylesheet" />

       

      Step 2: Insert the streamlined search field.

       

      Insert the following div element in the form where the streamlined search field should appear. Ensure that it is placed within the form tag of the donation form.

       

      1. <!--Listing 2-->
      2. <div id='dd-company-name-input'></div>
      3. <script>window.DDCONF = {API_KEY: "360MATCHPRO_PUBLIC_KEY"};</script>

       

      The streamlined search field should appear on the donation form.

       

      As soon as a donor starts typing into the streamlined search field, data begins to be captured. The data is stored in hidden input elements in the nearest enclosing form:

      1. The donor's search text is stored in the doublethedonation_entered_text input element.

      2. The search status (e.g., no interaction, entered text, not found, found) is stored in the doublethedonation_status input element.

      3. When a company is found, the company ID is stored in the doublethedonation_company_id input element.

       

      This data is stored in the browser's DOM but is not submitted to 360MatchPro from the donation page. Instead, this data must be passed to the confirmation page after the donation form is submitted.

       

      Streamlined search field not appearing on the donation form?
      If you don't see the streamlined search field on the donation form after Steps 1 and 2, refer to the Troubleshooting section of this page.

      Confirmation Page

      Step 1: Include CSS and JavaScript on the page.

       

      Include the following CSS and JavaScript somewhere on the page:

       

      1. <!--Listing 1-->
      2. <script src="https://doublethedonation.com/api/js/ddplugin.js"></script>
      3. <link href="https://doublethedonation.com/api/css/ddplugin.css" rel="stylesheet" />

       

      Step 2: Transfer data to Double the Donation.

       

      Register the donation with 360MatchPro using the register_donation JavaScript function that is loaded into the browser in Step 1.

       

      NOTE: You must register ALL donations with 360MatchPro, even when "doublethedonation_company_id" and "doublethedonation_entered_text" are not available (e.g. when the donor skipped the streamline search tool on the donation form). More information here.

       

      NOTE ON RECURRING DONATIONS: You must register recurring donations with Double the Donation, broken up into their recurring cadence. For example, if someone chooses to donate $25 a month, you must submit the $25 donation record of that recurring donation to 360MatchPro each month. If a donor pledges to give $100 over 4 monthly installments, you must submit the $25 donation record of that donation to 360MatchPro each month until the end.  More information here.

       

      A sample submission follows:

       

      1. //Listing 2
      2.  if (window.doublethedonation) { // Don't break your page if our plugin doesn't load for any reason
      3.   doublethedonation.integrations.core.register_donation({
      4.     "360matchpro_public_key": "XXXXXXXXXXXXXXXX",    // Replace this key with the client's 360MatchPro public key.
      5.     "partner_identifier": "XXXXX-123456789",    //  Replace this with your partner identifier. This will be securely provided to you by the Double the Donation Partnerships Team and is NOT the same as your partner API key.
      6.     "campaign": "EY_2017_Fall", // You should use a field that your clients would easily recognize as the donation form or campaign that the gift came from. 
      7.     "donation_identifier": "I-YE238388",
      8.     "donation_amount": 123.30,
      9.     "donor_first_name": "John",
      10.     "donor_last_name": "Doe",
      11.     "donor_email": "john@example.com",
      12.     "donor_address": {"zip": 30301,
      13.                       "city": "Atlanta",
      14.                       "state": "GA",
      15.                       "address1": "8769 Party Central Drive",
      16.                       "address2": "suite 901",
      17.                       "country": "US"},
      18.     "donor_phone": "123-456-7890",
      19.     "donation_datetime": "2018-12-25T10:15:30-05:00",
      20.     "anonymous": "false",
      21.     "in_memoriam": "false",
      22.      "athletic": "true",
      23.      "recurring": "false",  
      24.     "doublethedonation_company_id": 50,    // Only needed if the donor used the streamlined search field.
      25.     "doublethedonation_entered_text": "Home Depot"    // Only needed if the donor used the streamlined search field.
      26.   });
      27.  };

       

      Reference the Double the Donation Donation Data Schema for guidance.

       

      In most cases, this code may be placed in the JQuery.ready() callback (if using JQuery) or the DomContentLoaded Event, since the code must execute after the ddplugin.js file (Step 1) is fully loaded and executed.

       

      Step 3: Insert and initialize the matching gift plugin.

       

      Insert the following div element on the confirmation page where the matching gift plugin should appear.

       

      1. <!--Listing 3 -->
      2. <div id="dd-container"></div>

       

      If a donation form styling or size is not compatible with the standard matching gift plugin, the partner may use the condensed matching gift plugin. Review the documentation here and discuss with Double the Donation Partnerships Team before implementing.

       

      Include the following code on the confirmation page, replacing some fields as indicated below with the values from Step 2.

       

      1. //Listing 4
      2. // Initialize the following variable to be the doublethedonation_company_id
      3. // if a streamlined search is used and a company was found. Otherwise, set it to null.
      4. var dtd_selected_company = DOUBLETHEDONATION_COMPANY_ID;
      5. window.DDCONF = {API_KEY: "360MATCHPRO_PUBLIC_KEY", COMPANY: dtd_selected_company};
      6. if (window.doublethedonation) { // Don't break your page if our plugin doesn't load for any reason
      7.     doublethedonation.plugin.load_config();
      8.     doublethedonation.plugin.set_donation_identifier("DONATION_IDENTIFIER");    // Replace with actual identifier or an empty string.
      9.     doublethedonation.plugin.set_donation_campaign("CAMPAIGN");    // Replace with actual campaign.
      10.     if (dtd_selected_company) {
      11.       doublethedonation.plugin.set_company(dtd_selected_company);
      12.     } else {
      13.       var domain = doublethedonation.integrations.core.strip_domain("DONOR_EMAIL_ADDRESS") ;    // Replace with actual email.
      14.       doublethedonation.plugin.email_domain( domain );    // Checks for a company based on the email address.
      15.     }
      16. }

       

      If the donor selected a company from the streamlined search field or if the donor email address has a corporate domain that matches a company entity in the Double the Donation database, the matching gift plugin presents matching gift information about that company. If not, the matching gift plugin appears blank and prompts the donor to select their company. The plugin tracks what the donor selects at this stage.

      Troubleshooting

      Page Reload

      We detected input errors on the donation form and refreshed the page. Can we reload the streamlined search tool so that it shows the company that was selected before the donor attempted to submit the payment?

       

      Yes. Use the doublethedonation.plugin.set_company_name_input(string) function, calling the function with the search string that the user typed in. If the donor had selected a company, call the doublethedonation.plugin.set_company(string) function with the doublethedonation_company_id corresponding to the company selected.

       

      The search text and doublethedonation_company_id are stored in the browser's localStorage. You can use the following code: JSON.parse(localStorage.doublethedonation || "{}"); to retrieve these values. In the JSON, look for the doublethedonation_entered_text and doublethedonation_company_id properties. These properties will be missing if the donor does not use the streamlined search tool.

       

      Alternatively, you can find these values in hidden input elements (see Step 3 above) in the DOM. The hidden input elements will likely be wiped clean when the donor attempts to submit the payment, so you'll have to capture these values beforehand.

      Dynamically Generated Forms

      My donation form is dynamically generated with JavaScript, so the plugin doesn't appear after steps 1 and 2 above. How do I embed the streamlined search in this scenario?

       

      Continue to follow steps 1 and 2 above, but also run the following JavaScript after the donation form has been inserted into the DOM.

       

      1. if (window.doublethedonation) { 

      2.   //Load the search into a DOM element with id="dd-company-name-input"
      3.   doublethedonation.plugin.load_streamlined_input();
      4. }

      5. // The preceding code block is wrapped in an if statement so your

      6. // page doesn't break if the ddplugin.js script doesn't load for any reason.

       

      Make sure that the preceding code runs after the donation form is inserted into the DOM. Just place the code in an appropriate callback function that will be invoked after the DOM loads. For JQuery users, consider $(document).ready. Otherwise, consider using a browser event like DOMContentLoaded or readystatechange

       

      What if I can't add elements to the HTML markup (step 2 above)?

       

      If you are not able to add <div id="dd-company-name-input"></div> per step 2 above, consider creating the div using JavaScript, attaching it to the DOM, and calling the overloaded load_streamlined_input method, as follows:

       
      1. //This example uses JQuery, just to keep things simple. 
      2. if (window.doublethedonation) {
      3.   //Create Element
      4.   var streamlined_search = jQuery("<div id='dd-container'></div>"); 
      5.   //Inject element into DOM. Assumes DOM element with id 'placeholder' exists
      6.   streamlined_search.insertAfter("#placeholder");
      7.   //Call overloaded method, passing in the newly created element
      8.   doublethedonation.plugin.load_streamlined_input(streamlined_search[0]);
      9. }

      Async Issues

      If the streamlined search field is still not appearing on the donation form, load the donation form into your browser. Go into the Developer Tools (F12 on most browsers), and then go into the Console tab. In your console, type doublethedonation.plugin.load_streamlined_input() and press enter. Consider the following outcomes:

      1. Outcome: The streamlined search plugin DOES NOT appear, and I get an error that indicates that doublethedonation is not defined.

        Try this: Make sure you load ddplugin.js and ddplugin.css per step 1 above.

      2. Outcome: The streamlined search plugin DOES NOT appear on the page, and I don't get a console error.

        Try this: Make sure there is a div element with id='dd-company-name-input' somewhere in the DOM.

      3. Outcome: The streamlined search plugin appeared on the page.

        Success: The ddplugin.js script loaded successfully, but there is a timing issue. Consider using the Dynamically Generated Forms method in the Troubleshooting section.

      Unlikely async issues:

      If you use a third-party site builder platform that allows you to fetch external scripts or write inline JavaScript, the provider may append an async or defer attribute to the external JavaScript file. The defer attribute shouldn't cause problems because it blocks events that you likely rely upon, like the DOMContentLoaded. But the async attribute doesn't block any of these events, so you may have to rely on the window.onload instead. If you suspect that you are having async issues, consider injecting the code in the Dynamically Generated Forms section under Troubleshooting into the callback function of your window.onload event.

       

      In some cases, providers explicitly hard code timeouts to inlined JavaScript code, which may be the source of the async issues. When debugging your code, please be cognizant of this possibility.

       

      If external scripts are not loaded using the async attribute and inline JavaScript isn't wrapped in a timeout function, then you probably are not having async challenges.