Enhancing Your Website with Perch's Embeddable Tools: A Step-by-Step Guide

Introduction

Perch’s new Embeddable Tool Service opens up a realm of possibilities for our partners by offering a suite of embeddable Perch experiences. These include tools like mortgage calculators, real-time mortgage rates, and more with the goal of adding value to your site by providing your visitors with helpful financial tools, all while keeping them engaged within your domain.

This guide outlines the purpose and value of integrating Perch Tools into your website and walks through the simple process of adding them to various Content Management Systems (CMS) like WordPress (with Elementor), Webflow, Wix, and Squarespace.

You can check out all of our currently available widgets here.

Benefits of Perch Tools

User Engagement:
- Perch Tools are designed to enhance user experience by providing valuable financial tools and information directly on your site.
- By offering real-time mortgage rates and calculators, you keep your visitors engaged and provide a one-stop solution for their needs.
Professional Appearance:
- Embedding sleek, modern financial tools and experiences lends a professional appearance to your website and reflects well on your brand.
Ease of Integration:
- The simplicity of embedding a Perch Tool—a mere matter of adding a div tag and a script tag—means you can enhance your site’s functionality with minimal technical know-how.
Referral Tracking:
- We automatically track user referrals from your embedded tools so that we can offer provide you (our partners) with referral conversion details.

Embedding a Perch Tool

The process of embedding a Perch Tool is straightforward and similar across different CMS platforms.

Your Perch representative will provide you with your code snippet which you can simply paste into a code/embed block within your website CMS to render the Perch Tool.

You may be provided with multiple code snippets if you've requested different tools for different pages in your application.

Your code snippet will look similar to the following:

<!-- DIV PORTION -->
<div class="perch-widget" widget-id="ABC123">
    <div class="perch-widget-loading-indicator">Loading...</div>
</div>

<!-- SCRIPT PORTION -->
<script src="https://embeds.myperch.io/assets/perch-embed-widget.js"></script>

Please do not use this code, it is simply an example...

We'll quickly break down the code snippet. The first <div> tag denotes the location where tool will appear in your page. You can place this anywhere in your page and the javascript that will be loaded by the <script> will automatically replace the <div> with the expected widget.

💡 Please Note: to improve the client user experience of our tools we have added a feature to provide a custom loading indicator. More specifically, you can use the inner <div> with the class .perch-widget-loading-indicator to insert a plain text loader (e.g. 'loading...') that will be visible while the tool is being downloaded and rendered. As soon as the tool is loaded our script will remove this loading indicator.

You can replace the contents of this <div> with a custom message or a loading indicator of your choice to better match your branding. Be sure that you retain the .perch-widget-loading-indicator as this is what our script looks for when removing the loading indicator.

You can see an example of a custom loader on the rates tool located on the Perch Home Page.

Pre-filling Data in an Embedded Tool

Our embeddable tools also support the ability to pre-fill certain information in the calculator or widget using our injectable variable service. Setting values is simple and can be dynamically added to any webpage.

To learn more check out our article on customizing Perch's embeddable tools.

CMS Specific Instructions

We've created a quick video walkthrough to guide you in adding a Perch Tool to your website below as well as platform specific instructions.

WordPress + Elementor:

Navigate to the page where you want to embed the tool within your editor.
Add a new HTML element using Elementor.
Paste the provided <div> and <script> tags into the HTML element.
Save and publish your changes.

Webflow:

Go to the page you wish to embed the tool on.
Add an "Embed" element to your page.
Paste the provided <div> and <script> tags into the Embed element.
Publish your site to see the tool in action.

Squarespace:

Go to the page where you want to embed the tool.
Click on the + icon to add a new block and select ‘Code’.
Paste the provided <div> and <script> tags into the Code block.
Apply and save your changes.

KVCore:

KVCore is a little bit different than other website CMS in that you will need to enter the <div> and <script> tags in different locations in the CMS admin portal.
Hover over Web & IDX in your sidebar navigation which will reveal a new menu. Select Website Settings to open your website's setting panel.

Once loaded, scroll down to the "custom header" section. Put your <script> tag (<script src="https://embeds.myperch.io/assets/perch-embed-widget.js"></script>) in this box and hit save.
Next go into your custom page editor, click the embed option <> and paste the <div> portion of your tool into the box and then hit save.
Apply and save your changes to the site.

💡 IMPORTANT:
In most cases, the CMS editor will not execute our Javascript and therefore the tool will not render in the editor setting. Instead you will see the "loading..." text.

To view the rendered tool, select your CMS's "preview" option to render an instance of the page where Javascript can be execute to view a live version of the rendered tool.

Single Page Application Integration

Perch Widgets can be easily integrated into single-page applications (SPAs) like Angular, Vue.js, or React. However, SPAs manage the DOM differently compared to traditional multi-page websites. In a traditional setup, the widget script relies on the DOM ready event to initialize, but in SPAs, the DOM is often dynamically updated, and elements containing the widget may not be available at the traditional DOM ready event.

To ensure the widget initializes correctly in your SPA, you need to manually trigger the widget initialization at the appropriate point in your app's lifecycle. This can be done using our event service, which listens for an event to signal when the widget should be initialized.

Steps to Initialize a Widget in an SPA

Here’s a simple guide to handling widget initialization within an SPA:

Insert the widget into your HTML as you normally would.
Listen for the appropriate lifecycle hook in your framework that guarantees the element containing the widget is present in the DOM. For example, in Angular, this would be ngOnInit, in Vue.js it would be mounted, and in React it would be componentDidMount.
Emit the Perch widget initialization event once the widget’s DOM element is available. This will signal the widget script to initialize.

// Set the widget ID for the Perch widget 
var widgetId = "abc123"; 

// Create a custom event that signals the Perch widget to initialize
const event = new CustomEvent('perch-widget:init', { 
  detail: { 
    perchWidgetId: widgetId 
  } 
}); 

// Dispatch the event on the window object 
window.dispatchEvent(event);

Angular Example

import { Component, OnInit } from '@angular/core';

@Component({
  selector: 'app-widget-container',
  template: `<div perch-widget="abc123"></div>`, // Example of widget embedding
})
export class WidgetContainerComponent implements OnInit {

  ngOnInit() {
    // Initialize the Perch widget when the component is initialized
    const event = new CustomEvent('perch-widget:init', {
      detail: {
        perchWidgetId: 'abc123' // Replace with your actual widget ID
      }
    });
    window.dispatchEvent(event);
  }
}

Vue.js Example:

export default {
  mounted() {
    // Dispatch widget initialization when the component is mounted
    const event = new CustomEvent('perch-widget:init', {
      detail: {
        perchWidgetId: 'abc123' // Replace with your actual widget ID
      }
    });
    window.dispatchEvent(event);
  }
}

Best Practices:

Ensure that each widget is initialized only once per page, particularly in SPAs where pages may not fully reload. This ensures you do not encounter multiple initializations.
Dispatch the event at the earliest point where you can guarantee the DOM element for the widget is present.

By following this approach, you can successfully embed and initialize Perch widgets in your single-page applications, ensuring smooth functionality across various frameworks.

Wrapping Up...

Embedding Perch’s Tools into your website is a straightforward way to enhance your site’s functionality and user engagement. Whether you are using WordPress, Webflow, Wix, Squarespace or another platform to manage your website, the process is simple and adds significant value to your overall user’s experience.

Customizing Perch's Embeddable Tools