@nestio/cheryl

Lead Capture & Appointment Scheduling Widget

Stats

StarsIssuesVersionUpdatedCreatedSize
@nestio/cheryl
3.4.93 months ago4 years agoMinified + gzip package size for @nestio/cheryl in KB

Readme

Cheryl

Cheryl Tunt

Lead capture and appointment scheduling widget

Setup

Install dependencies

$ npm install

Development

Start development server and watch for changes

$ npm start

For examples to use in development, use http://localhost:8080/examples/. There are three examples:

  • http://localhost:8080/examples/appointment.html - Appointment scheduler widget 1.0 embedded in an iframe.
  • http://localhost:8080/examples/lead-capture.html - Lead Capture widget embedded in an iframe.
  • http://localhost:8080/examples/widget-wrapper.html - Renders the 1.0 widget directly as part of a React app.
  • http://localhost:8080/examples/new-appointment-scheduler.html - Appointment Scheduler 2.0

If you want to use a specific API key or group ID, update the config code in each example.

Using Local API

By default the examples assume that you have chuck (our main application) running locally on http://localhost:8000 -- and will attempt to use the API running there.

In order to get the cheryl dev server to talk to the chuck dev server, you must set CORS_ORIGIN_ALLOW_ALL = True in chuck/settings_local.py

Using Production API

If you don't have chuck running locally, you can configure the widgets to use the production API. Run npm start with the NESTIO_API_DOMAIN environment variable set to https://nestiolistings.com:

NESTIO_API_DOMAIN='https://nestiolistings.com' npm start

Builds

We currently bundle Cheryl into 3 seperate builds:

Iframe Widget

This build uses the iframe-widget.js and integration.js entry points and is intended to be deployed to a CDN. End users then load the integration.js script on their own website through a script tag. The integration script tag adds a NestioLeadCapture global javascript object which the end user invokes with configuration parameters. The integration script then creates an iframe with the configuration parameters passed in via a query string.

Babou

This build uses the babou.js entry point and is intended for use with the Babou V2 widget and to be loaded from a CDN. Instead of loading the widget in an iframe, it directly inserts it into the document. Configuration parameters are passed to the widget using data attributes on an element with the id nestio-lead-capture-script (in practice, the actual script tag loading the widget).

React

This build uses index.js entry point and is intended to be distributed through NPM for use within bundled project. It exports the components directly as React components so they can be used within a React application. Configuration parameters are passed directly as props.

Configuration Params

These are the configuration parameters required for the widget to work. Depending on which build you're using, they will be passed in differently.

Required

key : 32 char uuid4 hash [required]

A private Nestio API key

d1642beb0ec944a6a4b001a0f8cf84b5

group : Integer [required]

The user group ID that appointments and/or leads will be assigned to.

1

type : String <lead_capture|lead_capture_appointment> [required]

The type of widget to initialize.

Lead Capture

Enables just Lead Capturing

lead_capture

Appointments

Enables Lead Capture & Appointment Booking

lead_capture_appointment

Optional

color : 6 char hex color String [optional]

A custom color to apply to primary elements (buttons, links, hover states, etc). Custom color used as background will always use white as text color, so keep in mind when working with lighter colors.

5AC7CF

location : String [optional]

A custom location (such as a Building or specific Unit) to apply to either lead capture or appointment booking. Any location passed is saved on the client and/or appointment, and is used on confirmation screens and emails.

60 Water

submitLabel : String [optional]

The text displayed on the submit button on the client information form.

Book a tour

unit : Integer [optional]

The ID of a unit. This unit will added as Client Listing on the Client created by the widget.

disable_pym : Boolean [optional] [dev only]

for use with iframe widget only

A development-only flag to use to disable pym. A forked version of pym.js is being used to resize a parent iframe in production, but creates an error when a parent pym is not listening. Set to true when developing directly in the browser.

disable_pym=true

Using Cheryl on your website

Iframe

<script src="https://integrations.nestio.com/contact-widget/v1/integration.js" id="nestio-lead-capture-frame"></script>
<script type="text/javascript">
    NestioLeadCapture({
        key: 'example-key',
        group: 23,
        type: 'lead_capture_appointment',
        color: '5AC7CF',
        submitLabel: 'Book A Tour',
        location: ''
    });
</script>

React

First install Cheryl

npm install @nestio/cheryl

Then render it within your compoenent

import { WidgetWrapper } from 'cheryl';

class MyComponent extends Component {
    render() {
        return (
            <WidgetWrapper
                apiKey='exampleKey'
                groupId={6}
                widgetType='lead_capture'
                customColor='#5AC7CF'
                initialValues={{
                    people: [
                        {
                          first_name: 'Jeff',
                          email: 'myname@jeff.com'
                        }
                    ],
                    price_floor: 900,
                    price_ceiling: 4000,
                    notes: 'example notes'
                }}
                appointmentLocation='60 Water'
            />
         );
     }
}

How to Release a new version

Cheryl is distributed both through a CDN and through NPM. New versions should be released to both.

NPM

  • Update version in package.json, commit, and push

  • Create a new release in github

    • Tag: new version number
    • Name: new version number
    • Description: Reference all PRs that are in the release

    Release form

  • Release a new version to cheryl

    npm publish

  • Bump the version in any corresponding package.json where cheryl is a dependency

CDN

Run

npm run deploy:production

This will update the files available at: https://integrations.nestio.com/contact-widget/v1/ Note that due to caching on the CDN it may take up to 2 minutes to update.

Testing

Run Tests

npm test

Run tests in watch mode:

npm test -- --watch

Run tests with coverage:

npm test -- --coverage

Run tests in watch mode with coverage:

npm test -- --watch --coverage

Run linting

npm run lint

Staging

In order to test v2 widget on staging, you will need to do the following:

  • Release a beta version of cheryl
  • Deploy chuck to a staging link with the updated cheryl version in archer
  • Generate AppointmentSchedulerLink through chuck staging shell and get appointment link prepending appropriate staging url (e.g chuck-pr<pr#>.nestiostaging.com/appointments/scheduler/).

To test v1 widget on staging, you should perform these steps:

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.