@nestio/cheryl

Cheryl

Lead capture and appointment scheduling widget

Setup

Ensure you are using node v10.

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 both 1.0 widgets directly as part of a React app.
• http://localhost:8080/examples/new-appointment-scheduler.html - Appointment Scheduler 2.0 (deprecated, we've fully switched to the updated multi-screen version)
• http://localhost:8080/examples/updated-appointment-scheduler.html - Multi-screen 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.

buttonTextColor : String [optional]

Used to change the color of the text on the submit button of the widget. This should be 6 digit hex code.

000000

textColor : String [optional]

Used to change the color of the headers for each field on the widget, First Name, Last Name, etc. This should be 6 digit hex code.

00FFFF

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: '[e-mail]'
                        }
                    ],
                    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 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:

• Increment the Cheryl version, using a format like 1.1.11-beta.0, then commit and push the changes.
• Create a pre-release on GitHub.
• Publish a beta version of Cheryl using the command npm publish --tag beta
• Deploy chuck to a staging link with the updated cheryl version in archer
• Generate an AppointmentSchedulerLink either through the Chuck staging shell or in Messenger 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:

• Update api.js STAGING_DOMAIN to a chuck staging webhook url you want to use (i.e. https://webhooks-chuck-pr123.nestiostaging.com)
• Run staging bundle deploy: npm run deploy:staging;
• Update html file s3://demo.nestiolistings.com/appointment-scheduling-widget/index.html to use staging bundle URL: https://integrations.nestio.com/staging-contact-widget/v1/integration.js
• The staged widget will be available on S3 Static hosted website. When testing is finished, restore widget URL back to prod value https://integrations.nestio.com/contact-widget/v1/integration.js