CarGurus Deal Rating Badge Installation Instruction

Quick Start - Build a Badge and Install on Your Website

900 x 60

HTML Code

Copy and paste this HTML code for every used vehicle in the place where you'd like to display the badge. Substitute the correct VIN and Price accordingly.

<span data-cg-vin="1GNDT13W81K248136" data-cg-price="12300"></span>

Javascript code

Copy and paste this code ONLY Once before the closing body tag.

<script>
  var CarGurus = window.CarGurus || {}; window.CarGurus = CarGurus;
  CarGurus.DealRatingBadge = window.CarGurus.DealRatingBadge || {};


(function() {
    var script = document.createElement('script');
    script.src = "https://static.cargurus.com/js/api/en_CA/1.0/dealratingbadge.js";
    script.async = true;
    var entry = document.getElementsByTagName('script')[0];
    entry.parentNode.insertBefore(script, entry);
})();
</script>

Need Help?

Refer to the Troubleshooting section, or contact us at dealerhost_support@cargurus.com

Troubleshooting

1. How do I debug?

You can turn the debug flag on, and look in the browser developer tools to see if there any messages or errors being thrown. To turn the debug flag on, update this property in the javascript CarGurus.DealRatingBadge.options.debug = true;

Any console messages from our script will start with the following text: CarGurus.DealRatingBadge.

2. Badges aren't showing up

By default, badges will show for used vehicles that fetch a Good Deal or better. You can change the default by updating the CarGurus.DealRatingBadge.options.minRating setting. The script will then fetch badges for deals that are equal or better than the minRating value.

Possible values for the minRating setting are GREAT_PRICE, GOOD_PRICE, and FAIR_PRICE. Vehicles that do not meet the minimum Deal Rating will not have a badge shown.

Other things to check:

Make sure there are no Javascript errors in the browser developer tools.
Make sure the span tags are valid HTML, contain a valid VIN and Price in the corresponding data-cg attributes, and are not hidden in the DOM. Here's an example:
```
    <span data-cg-vin="1GNDT13W81K248136" data-cg-price="12300"></span>
```
Make sure the script tag appears once on the page, at the bottom of the page before the end </body> tag.
Make sure our API is being requested by checking the network tab in the browser developer tools, and look for a request to dealRatingRequest.action

3. Can't get the badge to be the right size

For STYLE1 or STYLE2, you have the ability to size the badge via the CarGurus.DealRatingBadge.options.defaultHeight property. The badge will resize proportionally to whichever height you set it at.

BANNER1, BANNER2, BANNER3, BANNER4, BANNER5 are fixed size and should only be used where appropriate.

4. How do I change the look of the badge?

Our badge container has a CSS class of cg-dealrating-badge.

STYLE1 and STYLE2 are transparent images, and you can add a background color, padding, and other CSS properties to the container.

Still have questions, contact dealerhost_support@cargurus.com

Detailed Instructions

1. Install the Javascript SDK

Copy and paste the following code at the end of your HTML page, right before the </body> tag


<script>
  CarGurus = window.CarGurus || { DealRatingBadge: { } };
(function() {
    var script = document.createElement('script');
    script.src = "https://static.cargurus.com/js/api/en_CA/1.0/dealratingbadge.js";
    script.async = true;
    var entry = document.getElementsByTagName('script')[0];
    entry.parentNode.insertBefore(script, entry);
})();
</script>

2. Define placeholders on your page where the badge should appear

The CarGurus Deal Ratings Badge will traverse your document and replace any <span> tag with the data-cg-vin and data-cg-price attributes with the corresponding Badge if one exists.

<span data-cg-vin="1GNDT13W81K248136"
data-cg-price="12300"
data-cg-badge-style="STYLE1"
data-cg-height="60"></span>

The attributes in bold are required.

The data-cg-badge-style attribute is optional, and when it exists, specifies the Badge style for the vehicle. If not specified, will use the CarGurus.DealRatingBadge.options.style mentioned below.

The data-cg-height, when it exists, specifies the height of the badge in pixels.

We recommend setting a smaller height for the listing results page, and a larger height for vehicle detail pages.

3. Verify the Badge is working correctly

After installing the code on your website, you should be able to see CarGurus Deal Ratings Badge show up on your pages. It looks something like this:

4. Advanced usage

The CarGurus Deal Ratings Badge automatically loads and fetches the deal ratings after the page has loaded, and continues to fetch any new ratings if the vehicles on the page change at any point. If for any reason, you would like control over the fetch process, you can disable the live updating via the options hash or by calling the following API function:

CarGurus.DealRatingBadge.disableLiveUpdates();

Then to manually fetch rating badges, you can use the following API function:

CarGurus.DealRatingBadge.run();

To enable the live updates again, you can call

CarGurus.DealRatingBadge.enableLiveUpdates();

5. Customizing the widget

You can set options globally or pass an options object to the run function. To set options globally, declare the following variable with at least one option key set:

CarGurus.DealRatingBadge.options = { minRating: "FAIR_PRICE", style: "STYLE2" };

To pass a custom options object to the run function, and have it apply just for that run instance, pass it as a parameter to the function.

CarGurus.DealRatingBadge.run({ minRating: "FAIR_PRICE", style: "STYLE2" });

If no parameter is passed, the global options object will take precedence if specified.

All possible options are listed below

Option key	Type	Default value	Description
style	string	`STYLE1`	Default badge style to use if `data-cg-badge-style` is not specified for a span. The following styles are supported: `STYLE1` - default height of 40px `STYLE2` - default height of 60px `BANNER1` - 900 x 60 pixels fixed size `BANNER2` - 900 x 42 pixels fixed size `BANNER3` - 748 x 42 pixels fixed size `BANNER4` - 550 x 42 pixels fixed size `BANNER5` - 374 x 42 pixels fixed size Refer to the Badge Styles panel in the top right of this page
showContactForm	boolean	`true`	When set to `true` will show a contact form in the Vehicle Detail Page so the consumer can submit their information to the dealer
`minRating`	string	`GOOD_PRICE`	Determines the minimum deal rating to display. Can be one of `GREAT_PRICE` `GOOD_PRICE` `FAIR_PRICE`
defaultHeight	integer	`40` \| `60` depends on the style	Height in pixels that the Badge should have, if the span tag does not contain a `data-cg-height` property. This property is ignored for the `BANNER1`, `BANNER2`, `BANNER3`, `BANNER4` or `BANNER5` styles.
live	boolean	`true`	When set to `true`, enables live updates of pages anytime new vehicles are added to the page without a page refresh
liveIntervalMS	integer	`500`	Refresh interval time in milliseconds if the option `live` is set to true
debug	boolean	`false`	When set to `true`, allows for client side console debug logging. This should not be set to true in production.

Badge Styles

STYLE1

STYLE2

Need Help?

dealerhost_support@cargurus.com