@encheres-immo/auction-widget

Enchères Immo's auction widget

Add a real-estate auction widget to your website, powered by Enchères Immo's API 🚀

Prerequisites

To use this widget, you need an API key from Enchères Immo. If you are a real estate professional and not yet a partner of Enchères Immo, please book a demo to get started. If you are already a partner, contact us to get your API key.

Installation

This widget is available as a package on npm. To install it, run:

# Using npm
npm install @encheresimmo/auction-widget
# Using pnpm
pnpm install @encheresimmo/auction-widget
# Using yarn (not recommended)
yarn add @encheresimmo/auction-widget

This widget is also available as a standalone script. To use it, add the following script and style tags to your HTML file:

<script src="https://cdn.jsdelivr.net/npm/@encheres-immo/auction-widget@0/dist/auction-widget.js" defer></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@encheres-immo/auction-widget@0/dist/auction-widget.css">

Upgrade

To upgrade this widget to the latest version using npm, run:

# Using npm
npm update @encheresimmo/auction-widget
# Using pnpm
pnpm update @encheresimmo/auction-widget
# Using yarn (not recommended)
yarn upgrade @encheresimmo/auction-widget

To upgrade the standalone script to the latest version, update the version number after @ in the script and style tags in your HTML file. You should only write one number, e.g. @0, to get automatically the latest version of the major version you are using (see below).

We follow semantic versioning, version numbers can therefore be interpreted as follows:

Number change	Meaning	Safe to upgrade?
x.x.0	Bug fixes, performance improvements, and security patches...	Yes
x.0.x	New features, or backward-compatible changes...	Yes
0.x.x	Big breaking changes, you should consult the changelog...	No

Usage

To use the widget, add the following HTML tag to your website, and replace YOUR API KEY with your Enchères Immo API key and PROPERTY ID with the Enchères Immo's ID of the property you want to display.

<div id="auction-widget" api-key="YOUR API KEY" property-id="PROPERTY ID"></div>

Alternatively, you can retrieve your property from a CRM by replacing property-id by source-name (e.g. source-name="APIMO"), source-id (the ID of the property in the CRM), and source-agency-id (the ID of the agency in the CRM).

<div id="auction-widget" api-key="YOUR API KEY" source-name="APIMO" source-id="APIMO PROPERTY ID" source-agency-id="APIMO AGENCY ID"></div>

Configuration

Features

You can enable or disable features of the widget by setting the corresponding attributes on the HTML tag. Here are the available features:

Attribute	Default	Description
allow-user-registration	true	Display a button to allow users to register for the auction—This registration must be accepted by the agent later, or the user will not be able to place bids. If set to false, agent's contact information will be displayed instead.
tos-url	https://encheres-immo.com/cgu	URL to your custom terms of service page for auctions, must be a valid URL and confirmed by Enchères Immo.

Styling

You can customize the widget by setting CSS variables in your website's stylesheet. Here are the available variables:

Variable name	Default value
--auction-widget-highlight-color	#ef673d
--auction-widget-dark-color	#002d40
--auction-widget-error-color	#dc2626
--auction-widget-border-radius	0.5rem
--auction-widget-btn-radius	0.5rem
--auction-widget-base-font	sans-serif
--auction-widget-title-font	sans-serif
--auction-widget-countdown-font	monospace

For example, to change the highlight color to blue, add the following CSS to your website's stylesheet:

:root {
  --auction-widget-highlight-color: blue;
}

To override the default styles, you can also use the layer @auction-widget-override :

@auction-widget {
  .auction-widget-label {
    border-radius: 1rem;
  }
}

Finally—as required by OAuth2—authentication pages are hosted on the Enchères Immo domain. You can customize the look and feel of these pages through your Enchères Immo "Custom Theme" settings.

Events

The widget emits events that you can listen to in your website's JavaScript. They are all prefixed with auction-widget:. Here are the available events:

Name	Payload	Description
bid_placed	{ amount: number, date: string }	Emitted when a bid is successfully placed. Can be used to play a sound, display a notification, etc.
new_bid	{ amount: number, bidder: string, date: string }	Emitted when a new bid is placed. Can be used to play a sound, display a notification, etc.
register	{}	Emitted when the user registers for the auction. Can be used for analytics, display a message, etc.

To listen to an event, add an event listener to the widget element in your website's JavaScript:

document.getElementById('auction-widget').addEventListener('auction-widget:new_bid', (event) => {
  console.log('New bid:', event.detail);
});

This event list is meant to be extended in the future, so feel free to ask for new events if you need them!

How to contribute

This widget is maintained by the Enchères Immo team, but we also deeply appreciate any contribution from the community, no matter how small or big.

Quick Links

📖 Main repository, with all our public packages.

🐛 Report a bug, please read our contributing guidelines and code of conduct first.

🚨 Report a security vulnerability, and be sure to review our security policy.

💬 Join the discussion, if you have any questions, ideas, or suggestions.

Useful commands

All commands are run from the root of the package.

Command	Description
pnpm install	Install dependencies
pnpm run build	Build the widget (minified)
pnpm run build --watch	Build the widget and watch for changes
pnpm run test	Run tests