Dealer finance enquiry widget integration

These dealer instructions have been customised to include the dealer ID provided to you by Classic & Sports Finance.

Dealer name: [not specified]
Dealer ID: [not specified]

These instructions include an example dealer ID. You will need to substitute the dealer ID provided to you by Classic & Sports Finance.

Contents

• Introduction
• Developer summary
• A basic dealer link
• Prefilling vehicle information
• Enabling the dealer widget
• JS inclusion (simplest method)
• JS inclusion (best method)
• JS method for passing make/model and price parameters
• Advanced JS method for extracting make/model and price from page content
• Script tag buttons
• Standard button images
• PHP implementation
• WordPress integration

Introduction

This document provides detailed information on dealer integration with the Classic & Sports Finance enquiry form, covering various ways it can be achieved, including PHP and JavaScript libraries.

The enquiry form is here:

http://www.classicandsportsfinance.com/finance-enquiry-form/

By implementing dealer integration, you can place buttons on a vehicle’s page on the dealer website that will:

• simplify the process of a customer’s enquiry by prefilling vehicle details
• enable the dealer to receive a simple anonymised notification that a finance enquiry has been received for a particular vehicle
• pop up the finance widget: an in-page popup that will allow customers to make their enquiry without leaving your website.

Below is an example of a button configured for your Dealer ID:
Below is an example of a button:

Developer summary

The widget implementation involves two things:

• a button link on the website (just an ordinary <a href="..."> tag) that links to the CSF finance enquiry form, passing a dealer ID and optionally some information about the vehicle (make/model and price) via the query string to partially pre-fill the form.
• a JavaScript library that, included in the page, upgrades these links so they display a small embedded finance enquiry form, with a short introductory page, in a typical fancybox-type modal popup.

Additionally, the JavaScript library

• provides a method for rendering image buttons from script tags,
• allows for passing parameters in a way that avoids the need for URL-encoding, and
• can extract the make/model and price directly from the page’s Document Object Model

The widget script is minified, includes all (minified) CSS needed to display the modal, and has no pre-requisites apart from recent browser support. The script can be loaded asynchronously and a simple asynchronous loader is described below.

The popup will work on all browsers that provide the DOM method document.querySelectorAll(), which includes all major desktop and mobile browsers including Internet Explorer as far back as version 8 for sites displayed in standards mode.

The current popup design requires 600×500 pixels of space so will not display on some mobile devices. If it cannot display, the link will fall back to linking directly to the CSF site, with all passed parameters encoded.

A basic dealer link

The minimum effective integration involves passing your CSF dealer ID as a parameter within an HTML link.

This prefills your dealer name on the form and will enable email notifications when a finance enquiry has been made on a particular vehicle.

The dealer ID for [not specified] is [not specified], so the link is:

For example, if the dealer were to be assigned the ID 5690, the link is:

https://www.classicandsportsfinance.com/finance-enquiry-form/?dealer=5690

A simple link might look like this:

<a target="_blank" class="your-button-class" href="https://www.classicandsportsfinance.com/finance-enquiry-form/?dealer=5690">
  FINANCE
</a>

This link can be styled up with CSS to match the design of your site. We recommend that the link text simply read FINANCE. If you would like the button to say something else, please discuss with us first.

HTTPS: The Classic & Sports Finance website supports HTTPS but currently does not require it. As the general industry trend is towards securing web traffic, ultimately our site will be SSL-only, so we recommend using https:// links.

The JavaScript integration below will transparently upgrade plain HTTP links to HTTPS, and the PHP integration produces HTTPS links as standard.

Prefilling vehicle information

The form will prefill with vehicle information if the data is passed from the dealer website.

The following vehicle information can be passed as ordinary URL-encoded query string parameters:

So for a Porsche 928 at £40,000, the URL might look like:

https://www.classicandsportsfinance.com/finance-enquiry-form/?dealer=5690&make-model=Porsche%20928&price=%C2%A340%2C000

Price information may not always be available to customers, so alternatives such as POA / £Ask / On Request etc., are also acceptable.

URL encoding: Notice that the vehicle information in the URL above has been URL-encoded. This is a general requirement for correctly passing parameters in links.

All web programming languages/libraries provide support for URL-encoded parameters. Some examples:

Please let us know if this proves difficult. Remember to provide some information on the programming language/hosting environment etc., so we can help direct you to an appropriate solution.

Alternatively, the PHP and JavaScript integration methods will handle the encoding process for you.

Enabling the popup form

The popup form is enabled by adding a single JavaScript file to the page:

https://www.classicandsportsfinance.com/dealer-widget/widget.min.js

Once added, the script upgrades the finance enquiry links so that the popup will display instead. (Opening the link in a new tab or window will link to the form on the Classic & Sports Finance site as normal.)

This script only needs to be included once per page; it will upgrade all links in the page. The script tag can be added anywhere in the page; a good choice is just before the closing </body> tag.

The script file is compressed to a tiny size (a little over five kilobytes), so it’s safe to include in all pages and loads very quickly, but it need only be included for pages that render a finance enquiry link.

For more details you can view an uncompressed, commented version of the script.

Screen space: The popup as it is currently designed will not show if the browser window has less than 600×500 pixels of space available. So it will not appear on all mobile devices. If the popup cannot be shown, the user will be taken to the main finance enquiry form.

Browser support: It will display in all major browsers and Internet Explorer from version 8 onwards.

Tracking: The widget does not perform any persistent tracking of your customers.

A note on JS: JavaScript methods obviously won’t work if for any reason the script cannot be loaded, e.g. if the user has disabled JS support, the page has other script errors, or the script has been blocked by browser add-ons.

JS inclusion (simplest method)

You can include the JavaScript with an ordinary <script> tag, which is the simplest method and in some cases (very large pages) the most appropriate:

<script type="text/javascript" src="https://www.classicandsportsfinance.com/dealer-widget/widget.min.js"></script>

JS inclusion (best method)

The preferred method of integration provides better performance by using an asynchronous loader of a kind that will be familiar to anyone who has added Google Analytics trackers to a website:

<script type="text/javascript"> 
(function(w, d, s) { 
  function go() { j = d.createElement(s); j.async =1; j.src = "https://www.classicandsportsfinance.com/dealer-widget/widget.min.js"; d.body.appendChild(j); } 
  if (w.addEventListener) { w.addEventListener("load", go, false); } 
  else if (w.attachEvent) { w.attachEvent("onload",go); } 
})(window, document, "script"); 
</script>

This routine ensures that the script is only downloaded by the user’s browser after the main page structure has loaded so it will not delay the rendering of the dealer’s web page.

Asynchronous loading on very large or slow pages: If your page has extensive slideshows, very large imagery or other factors that can delay page completion, it is best not to use the asynchronous loader. This is because until the page load has completed, the widget cannot be enabled, and the loader link will pop up the Classic & Sports Finance website in a new window, which risks losing your customer’s attention span.

If your pages are large, use the simple loader above; this will enable the popup widget a little sooner at the cost of downloading it a little earlier.

Using an existing script loader: If the dealer website already makes use of an asynchronous script loader, the script can be included through that method. It need not be loaded until the web page has fully displayed. The script must be loaded directly from the URL above so that bug fixes and improvements can be made available immediately.

JS method for passing make/model and price parameters

Through the JavaScript integration, two other methods are available for passing vehicle details to the form.

The first involves adding the values as data-attributes on the <a> tag. The two parameters are:

• data-make-model
• data-price

For example:

<a target="_blank" data-make-model="Porsche 928" data-price="£40,000"
href="https://www.classicandsportsfinance.com/finance-enquiry-form/?dealer=5690">
  FINANCE
</a>

Advanced JS method for extracting make/model and price from page content

This integration method may not always be possible. It is provided mostly as a fallback for us to advise on a way a full integration can be achieved with only limited access to dynamic templating behaviour.

It is also only really useful when there is only one vehicle per page.

The second method involves passing these attributes:

• data-extract-make-model
• data-extract-price

The values of these attributes should be CSS selector expressions that identify elements in the page containing the make/model and price values.

For example, if the make and model were to be found in the page in the following markup:

<h1>Porsche 928</h1>

<span id="vehicle_price">£40,000</span>

Then it is possible to specify CSS selectors as follows:

<a target="_blank"
  data-extract-make-model="h1" 
  data-extract-price="#vehicle_price"
  href="https://www.classicandsportsfinance.com/finance-enquiry-form/?dealer=5690">
  FINANCE
</a>

Script tag buttons

Finally, the JavaScript method also allows for simple buttons to be generated entirely from script tags, in the following form:

<script type="CSF/Widget"
  data-make-model="Porsche 928"
  data-price="£40,000"
  data-dealer="5690" 
  data-image="black_pp_grey_white_240"></script>

The extract parameters described above can also be used. Notice that there are two further parameters:

This second parameter is optional; a default button image will be used if it is not specified.

The possible button image names are detailed below.

PHP implementation

We also provide a PHP implementation of the code that wraps up all the functionality above.

The PHP integration library can be downloaded here.

Using the code in your project is simple; either paste the library code directly into the PHP template of a page, or add the file to your site build and include it as below (taking care to specify the correct path to the file):

<?php require_once('/path/to/csfdealer.php'); ?>

Once loaded, this PHP library provides methods to render a simple button and to include the script file. For example, a very simple implementation would be:

<?php
  echo CSFDealer::widgetScript();
  echo CSFDealer::button("Porsche 928", "£40,000",5690); ?>

The library supports both script inclusion methods, and ways to specify the button image, the HTML of a button link, or simply to construct the finance link with parameters.

We can provide further support for this as needed.

WordPress integration

March 2019: we have a new, simpler WordPress plugin that provides some support for adding finance link buttons via the ordinary WP text editor GUI. We recommend this if your end users will be responsible for adding the finance links to content.

The PHP integration library can also be installed as a very basic WordPress plugin. (Just upload the zip through the WP plugin installation screens). The WP plugin is generally intended as a way to quickly explore the functionality of the widget within a WP site design.

Once enabled, configure it by adding the following to your wp-config.php file:

define('CSF_DEALER_ID', 5690);

Then it is possible to use two shortcodes to display buttons in various ways:

[csf_button makemodel="Porsche 928" price="£40,000"]

[csf_button makemodel="Porsche 928" price="£40,000" class=“mybuttonclass"]

[csf_button makemodel="Porsche 928" price="£40,000"]Finance for this vehicle[/csf_button]

[csf_image_button makemodel="Porsche 928" price="£40,000"]

[csf_image_button makemodel="Porsche 928" price="£40,000” image="white_fe_grey_orange_240"]

The source code of the plugin could be used as the basis of further integration into a WP site.