Implementing Pushpay Embedded Campus Selector

This guide will walk you through implementing a campus selector for the Pushpay embedded giving widget.

This is a powerful feature for organizations with multiple locations, allowing givers to direct their generosity to their home campus right from your website. We'll cover how campuses are structured in Pushpay and provide a step-by-step guide with template code you can use to create a seamless and personalised campus-specific giving experience.

Caution: The following instructions are intended for web developers and require a good understanding of HTML, CSS, and Javascript. Customizations beyond those listed here are possible but may not be supported by our team and could break when we update the widget.

Try the Demo First

Before implementing the campus selector on your website, we strongly recommend exploring the demo to understand the user experience:

1. Open the Demo: Open embedded-listing-selector-demo.html in your web browser
2. Test Campus Selection: Click on different campus options to see how the widget loads dynamically
3. Observe the Transition: Notice how selected campuses highlight and non-selected options fade away
4. Test the "Change Campus" Link: After selecting a campus, click "Change Campus" to return to the selection menu
5. Test Cookie Persistence: After selecting a campus, refresh the page. The widget should automatically load your previously selected campus
   • Note: To test cookie persistence locally, you must run the demo through a local web server (e.g., using python -m http.server or a tool like Live Server in VS Code). Opening the HTML file directly with file:// protocol will prevent cookies from working properly.
6. Inspect the Code: View the page source to see the HTML structure and how elements are organized

The demo includes three sample campuses with working Pushpay QA handles. This hands-on exploration will help you understand how the selector works before you begin customizing it for your organization.

How Campuses Work in Pushpay

Before you start, it's crucial to understand how your organization's campuses are set up in Pushpay, as this determines the correct implementation path. There are two primary methods:

• Single Listing with a Campus Field: In this setup, your organization has one primary giving listing. The widget itself will contain a dropdown field labeled "Campus" where givers can select their location. If this is your configuration, you do not need this guide! The standard widget will handle campus selection automatically.
• Separate Listing for Each Campus: In this configuration, each campus has its own unique Pushpay giving listing. This means each campus has a different handle used in the widget loader script. The solution in this guide is designed specifically for this scenario. It works by dynamically swapping the widget handle based on the user's selection and history.

To confirm your setup, check your Pushpay Giving admin portal or contact Pushpay support.

How the Campus Selector Script Works

The Javascript code provided here creates a dynamic and user-friendly experience. Here’s a quick overview of what it does:

1. Detects Selection: It listens for a click within your website's campus navigation menu.
2. Loads the Correct Widget: When a user selects a campus, the script grabs the unique handle associated with that campus and loads the giving widget with that handle.
3. Remembers the User: It saves the user’s campus choice in a browser cookie.
4. Personalizes Future Visits: The next time the user visits your giving page, the script reads the cookie and automatically loads the widget for their previously selected campus, creating a personalized experience.
5. Handles Widget Cleanup: When switching between campuses, the script properly destroys the previous widget instance before loading the new one, ensuring a clean transition.
6. Provides Fallback: If the widget fails to load (network issues, script errors), it displays a fallback "Give Now" button that redirects to the campus's full giving page with a Custom Campus/Listing Selector

Step-by-Step Implementation

Step 1: Create Your Campus Selector HTML

First, you need an HTML element on your website that allows users to select a campus. This is typically a list of tiles or a dropdown menu on the giving page.

Required HTML Structure:

• A wrapper <div> with the class pushpay-widget
• An <h2> with class pushpay-campus-select-label for the heading
• A <ul> with class pushpay-listing-select-menu containing campus options
• Each campus as an <li> element containing an <a> tag with a data-handle attribute
• A hidden wrapper <div> with id pushpay-wrapper containing the widget container
• A hidden "Change Campus" link with id pushpay-change-campus-link
• The script tag pointing to embedded-listing-selector.js

Here is an example structure. You will need to replace the data-handle values with the correct handles for your organization's listings from your Pushpay admin portal.

<div class="pushpay-widget" data-env="prod">
    <h2 class="pushpay-campus-select-label">Select your campus:</h2>
    <ul class="pushpay-listing-select-menu">
        <li><a href="#" data-handle="your-campus-1-handle">Campus Name 1</a></li>
        <li><a href="#" data-handle="your-campus-2-handle">Campus Name 2</a></li>
        <li><a href="#" data-handle="your-campus-3-handle">Campus Name 3</a></li>
    </ul>
    <div id="pushpay-wrapper" class="hidden">
        <div id="pushpay-embedded-giving"></div>
    </div>
    <a id="pushpay-change-campus-link" style="display: none;">Change Campus</a>
    <script src="embedded-listing-selector.js"></script>
</div>

Step 2: Set the Correct Environment

The data-env attribute on the main wrapper div controls which Pushpay environment the widget connects to:

For Production (Live Giving):

<div class="pushpay-widget" data-env="prod">

or simply omit the attribute (production is the default):

<div class="pushpay-widget">

For the demo page (or testing using the test listings from the demo page):

<div class="pushpay-widget" data-env="qa">

Important Notes:

• You may use data-env="qa" during development and testing with the Pushpay demo page listings
• To test the page with your real listings, either change data-env="qa" to data-env="prod" or remove the attribute entirely
• QA handles point to qa.testpushpay.com while production handles point to pushpay.com

Step 3: Get Your Listing Handles

To find your listing handles, visit your existing Pushpay giving pages. The handle is the last part of the URL.

For example, in the URL https://pushpay.com/g/givecentralchurch, the handle is givecentralchurch

Handle Format: Handles are usually lowercase alphanumeric strings without spaces (e.g., givecentralchurch, downtowncampus, northlocation)

Step 4: Add Styling

You can add custom styling to the <li> elements and other components to achieve rich and dynamic menus like the one in the demo page. You are welcome to incorporate the styles from widget-styles.css and demo-styles.css into your own stylesheet, or amend them to match your brand.

The script automatically applies the following CSS classes during interaction:

• hidden - Applied to non-selected campus tiles when a selection is made
• selected - Applied to the chosen campus tile
• visible - Applied to the widget wrapper when the widget loads

You can use these classes in your CSS to create smooth transitions and visual feedback.

Step 5: Include the JavaScript

Make sure embedded-listing-selector.js is accessible from your HTML file. You can either:

• Place it in the same directory as your HTML file
• Place it in a scripts folder and update the path: <script src="/js/embedded-listing-selector.js"></script>
• Host it on a CDN if you prefer

The script will automatically initialize when the DOM is ready, so no additional JavaScript code is needed.

Step 6: Test Your Implementation

1. Test in QA first: Set data-env="qa" and use Pushpay QA handles
2. Test each campus: Click through each campus option to ensure the correct widget loads
3. Test cookie persistence: Select a campus, close your browser, reopen, and verify it remembers your choice
4. Test the "Change Campus" link: Ensure you can switch between campuses smoothly
5. Test on multiple browsers: Verify functionality in Chrome, Firefox, Safari, and Edge
6. Test on mobile devices: Ensure the experience works well on phones and tablets

Step 7: Deploy to Production

Once testing is complete:

1. Update data-env to "prod" or remove the attribute
2. Replace all QA handles with production handles
3. Deploy to your production website
4. Test again in production to ensure everything works correctly

Troubleshooting

Widget not loading:

• Verify your handles are correct for your environment (QA vs. production)
• Check browser console for JavaScript errors
• Ensure the embedded-listing-selector.js file path is correct
• Verify the HTML structure matches the required format

Campus selection not working:

• Ensure each <a> tag has a data-handle attribute
• Verify the <li> and <a> structure is correct
• Check for JavaScript errors in the browser console

Cookie not persisting:

• Check if browser cookies are enabled
• Verify there are no cookie-blocking extensions active
• Ensure your website is served over HTTPS (some browsers restrict cookies on HTTP)
• If testing locally, make sure you're running a local web server (not opening files directly with file:// protocol). Use tools like:
  • Python: python -m http.server or python3 -m http.server
  • Node.js: npx http-server or npx serve
  • VS Code: Live Server extension

Widget shows wrong campus after refresh:

• Clear browser cookies and test again
• Verify the cookie name PushpaySelectedCampus isn't being set elsewhere in your code

Additional Notes

• No Dependencies: The script uses pure vanilla JavaScript with no external dependencies
• Browser Support: Compatible with all modern browsers (Chrome, Firefox, Safari, Edge)
• Cookie Expiration: Campus selection is remembered for 365 days
• Widget Cleanup: The script properly cleans up widget instances when switching campuses to prevent memory leaks
• Fallback Handling: If the widget fails to load within 3 seconds, a fallback "Give Now" button appears that redirects to the full giving page

That's it! With the HTML structure and this script in place, your website will now offer a dynamic, campus-specific giving experience that remembers your donors' preferences and provides a seamless giving journey.