Buddy Offer Component

React component for adding Buddy's Insurance Gateway

Table of Contents

• Requirements
• Installation
• Basic Usage
• Props
• Configuration Files
  • Version 2 configuration files (Recommended)
  • Version 1 configuration files
• View Types
• Checkout
  • For client-side only apps
  • For full stack apps
• Pre-filling Data
• Styling
  • Color Palettes
  • Overrides
  • Classes and Components
• Capturing Data

Requirements

• React 16.8.0+
• Contact Buddy to obtain a partnerID and compatible ions for your specific use case.

Installation

Install it from npm and include it in your React build process

npm install @buddy-technology/offer-component or yarn add @buddy-technology/offer-component

Basic Usage

import React from 'react';
import BuddyOfferElement from '@buddy-technology/offer-component';

function App() {
  return (
    <div id="app">
      <h1>My App</h1>
      <BuddyOfferElement ion="MY_ION" partnerID="my-partner-id" stage="STAGING" />
    </div>
  );
}
export default App;

Props

*required

Configuration Files

Version 2 configuration files (Recommended)

For version 2 configuration files (that utilize Buddy.embedOptions), simply pass in the URL of the file to the configSrc prop. Properties defined in a configuration file will be merged with any props defined in this implementation.

EXAMPLE

// config.js 

const configTheme = {
  baseTheme: 'base',
  palette: 'base',
  overrides: {
    styles: {
      h1: { color: 'blue' }
      h2: { color: 'blue' }
    }
  },
};

window.Buddy.embedOptions.theme = configTheme // attach our theme to embedOptions.

// React implementation

import React from 'react';
import BuddyOfferElement from '@buddy-technology/offer-component';

function App() {
  const overrideConfigTheme = {
    overrides: {
      styles: {
        h2: { color: 'red' }
      }
    }
  };

  return (
    <div id="app">
      <h1>My App</h1>
      <BuddyOfferElement
        ion="MY_ION"
        partnerID="my-partner-id"
        stage="staging"
        configSrc="https://js.buddy.insure/config.js" // URL of our config file
        theme={overrideConfigTheme} // deep merges our theme, h2's will now be red, but h1's are still blue.
      />
    </div>
  );
}
export default App;

Version 1 configuration files

NOTE: This feature is useful pairing configuration files utilizing the config variable pattern. For information on how to implement newer configs see: Version 2 Configuration Files.

For configuration files utilizing the config variable pattern, we need to first pre-load our script using the useConfig hook, then pass our options to the implementation.

import React from 'react';
import BuddyOfferElement, { useConfig } from '@buddy-technology/offer-component';

function App() {
  const { config, isLoading } = useConfig('https://config-domain.com/config.js');

  if (isLoading || !config) {
    return null;
  }

  // grab relevant properties from config
  const theme = config.themeBase;
  const data = config.data;
  const handleUserEvents = config.userEvents;

  return (
    <div id="app">
      <h1>My App</h1>
      <BuddyOfferElement
        ion="MY_ION"
        partnerID="my-partner-id"
        stage="staging"
        theme={theme}
        data={data}
        onUserEvent={handleUserEvents}
      />
    </div>
  );
}
export default App;

View Types

Buddy's Offer Element comes in three different view types:

• paginated (default) - A paginated form where users click through to the next section.
• single form - A single form where all fields are displayed in the same, scrollable view.
• offer only - View for displaying just the insurance offer with a quote and checkbox that fires onOptIn when checked and onOptOut when unchecked (see For full stack apps for more info). NOTE: Offer-Only implementations are meant to be rendered in a controlled environment with necessary data passed into it, and will require a payment integration for checkout (see Buddy's Partner API docs). If any fields are missing or invalid, a step-through form will render with the individual views that include the needed fields. Views with satisfied fields will be skipped. Once users rectify any needed info, they will land on the offer only screen.

Checkout

For client-side only apps

The embed widget's default mode includes a full checkout. Customers can go through the entire flow through to a secure purchase and policies will be delivered directly to their inbox.

To explicitly set the widget to include checkout, set the includeCheckout property to true.

For full stack apps

In server side and full-stack applications where customers are already purchasing other products, it's best to exclude the secure checkout built into the widget so customers can purchase their insurance alongside any other products as part of a single transaction. A backend integration (See Buddy's Partner API docs) is required in order to complete the transaction.

To use this mode, set includeCheckout to false, or set viewType to offer-only.

When users opt in, the onOptIn callback is fired with the completed application object. If a user opts out, onOptOut will be called.

// simple paginated example to collect data
import React from 'react';
import BuddyOfferElement from '@buddy-technology/offer-component';
import { handleAddToCart, handleRemoveFromCart } from './myApi';

function App() {
  const handleAddToCart = (payload) => {
    handleAddToCart(payload)
  };

  const handleRemoveFromCart = (payload) => {
    handleRemoveFromCart(payload)
  };

  return (
    <div id="app">
      <h1>My App</h1>
      <BuddyOfferElement
        ion="MY_ION"
        partnerID="my-partner-id"
        viewType="paginated"
        includeCheckout={false}
        onOptIn={handleAddToCart}
        onOptOut={handleRemoveFromCart}
        stage="PRODUCTION"
      />
    </div>
  );
}
export default App;

// example using offer-only and passing in customer/policy data
import React from 'react';
import BuddyOfferElement from '@buddy-technology/offer-component';
import { handleAddToCart, handleRemoveFromCart } from './myApi';

// passing down data as prop in this example
function App({ userAndPolicyData }) {
  const handleAddToCart = (payload) => {
    handleAddToCart(payload)
  };

  const handleRemoveFromCart = (payload) => {
    handleRemoveFromCart(payload)
  };

  return (
    <div id="app">
      <h1>My App</h1>
      <BuddyOfferElement
        ion="MY_ION"
        partnerID="my-partner-id"
        viewType="offer-only"
        data={userAndPolicyData} // data is passed in, if any fields are invalid, they will be displayed to user to rectify before purchasing.
        onOptIn={handleAddToCart}
        onOptOut={handleRemoveFromCart}
        stage="PRODUCTION"
      />
    </div>
  );
}
export default App;

Pre-filling Data

It's a best practice to pass in any customer and policy data that has already been collected to optimize user experience. Unless viewType is offer-only, users will be able to see and edit any data that is passed.

Data follows the application object structure. Refer to your specific ION (or offering) documentation.

import React from 'react';
import BuddyOfferElement from '@buddy-technology/offer-component';

function App() {
  const data = {
    customer: {
      firstName: 'customer first name',
      lastName: 'customer last name',
      address: {
        line1: 'street address',
        city: 'city',
        state: 'state',
        zip: 'zip',
      }
    },
    policy: {
      startDate: '12/31/2022',
    }
  };

  return (
    <div id="app">
      <h1>My App</h1>
      <BuddyOfferElement
        ion="MY_ION"
        partnerID="my-partner-id"
        data={data}
        stage="PRODUCTION"
      />
    </div>
  );
}
export default App;

Styling

Buddy's offer element supports extensive visual customization, allowing you to seamlessly match the design of your site with the theme prop.

1. Pick a base theme and color palette: Quickly get running by picking the prebuilt theme and palette that most closely resembles your website.

2. Customize even further by adding overrides: Virtually any property can be further customized using CSS object styling.

import React from 'react';
import BuddyOfferElement from '@buddy-technology/offer-component';

function App() {
  const customTheme = {
    baseTheme: "base",
    palette: "buddy",
    overrides: {
      webFonts: [
        'https://fonts.googleapis.com/css2?family=Rubik:wght@700&display=swap',
      ],
      styles: {
        h1: {
          color: 'var(--color-text-primary)',
          fontFamily: 'Rubik, sans-serif',
          fontSize: '2rem',
          '@media (min-width: 992px)': {
            fontSize: '3rem',
          },
          '&:hover': {
            boxShadow: 'none',
            backgroundColor: '#FBF9EF',
          },
        },
        body: { color: '#0A242D' },
        '.input-text': {
          border: 'none',
          color: '#333333',
        }
      },
      colors: { textPrimary: '#0A242D' },
    },
  };

  return (
    <div id="app">
      <h1>My App</h1>
      <BuddyOfferElement
        ion="MY_ION"
        partnerID="my-partner-id"
        theme={customTheme}
        stage="PRODUCTION"
      />
    </div>
  );
}
export default App;

Color Palettes

We currently offer two color palettes to start with (with more coming soon!).

Base:

primary: '#000000',
secondary: '#254E70',
tertiary: '#848484',
negative: '#e45b78',
positive: '#A3D9B1',
textPrimary: '#000',
textSecondary: '848484',
backgroundPrimary: '#fff',
backgroundSecondary: '#7d8387',

Buddy:

primary: '#DC5648', secondary: '#0A242D99', tertiary: '#46460E33', negative: '#D62719', positive: '#A3D9B1', textPrimary: '#0A242D', textSecondary: '#0A242D99', backgroundPrimary: 'linear-gradient(#D6F1F2, #F8F6D2)', backgroundSecondary: '#FBF9EF',

Overrides

The overrides object consists of three major properties:

webFonts: An array of string urls for web fonts. Note: if using web fonts, it is still necessary to set the fontFamily property on any elements using that particular webfont.

styles: A CSS styles object with any CSS overrides on a given theme. Styles will overwrite existing theme styles. Media queries and child selectors can be accessed as a string key name, and nested within a given selector (see the example above). Component classes can also be manipulated within the styles object.

colors: A colors object will override any of the color properties in the table below:

Classes and Components

Some components can be directly modified by accessing their class names in the theme object. See the full list of component class names below.

  var customTheme = {
    style: {
      h1: { fontSize: 36 },
      '.button-primary': {
        // custom styles
      },
    },
  };

Available Classes

• card
• button-primary
• button-secondary
• input-text
• input-invalid
• input-select
• input-label
• input-label-invalid
• offer-container
• field-container
• view-container

Capturing data

You can hook any CRM or analytics platform into the Buddy offer-element using the onUserEvent hook.

onUserEvent(eventType: string, data: object) ⇒ void

The onUserEvent hook property allows you to pass in a custom function to embed your analytics of choice. Simply pass in a callback to the onUseEvent option, and you will get the following 2 parameters:

• eventType: string denoting the type of event that fired (ex: "onViewChange")
• data: object with internal data regarding the event. All data objects include a timestamp property.

Quick example

import React from 'react';
import BuddyOfferElement from '@buddy-technology/offer-component';

function App() {
  const handleUserEvent = (payload) => {
    // logs an object with eventType and data to the console
    console.log(payload)
  };

  return (
    <div id="app">
      <h1>My App</h1>
      <BuddyOfferElement
        ion="MY_ION"
        partnerID="my-partner-id"
        viewType="offer-only"
        onUserEvent={handleUserEvent}
        stage="PRODUCTION"
      />
    </div>
  );
}
export default App;

Event types and data fired:

We capture several user-driven events and each has different available pieces of data associated with it. Look closely at the list below to determine which events you want to capture and how to use the data.

onOfferElementLoad

Triggers when the offer element mounts

data returned

onOfferElementUpdate

Triggers when the data prop to the Offer Element is updated

data returned

onViewChange

Triggers when users click to a new screen in a paginated view mode.

data returned

onScrollToView

Triggers when or scroll to a section in single-page view mode.

data returned

onQuote

Triggers when the app displays retrieves a quote for the policy

data returned

onCheckout

Triggers during the check out process

data returned

onFocus

Triggers when an input is focused

data returned

onBlur

Triggers when an input is blurred

data returned

onRadioSelection

Triggers when a radio button is selected

data returned

onSlide

Triggers when a slider input is changed

data returned

onCheckboxSelection

Triggers when a checkbox is selected

data returned

onBlur

Triggers when an input is blurred

data returned

onValidationError

Triggers when an input is triggered as invalid

data returned

onExternalLink

Triggers when an input is triggered as invalid

data returned

onOptIn

Triggers when a user opts into an 'offer-only' insurance offer

data returned

Google Analytics example

import React from 'react';
import BuddyOfferElement from '@buddy-technology/offer-component';

function App() {
  /* This is an example of how you could use these events
  your usage may vary depending on your analytics systems */

  const handleUserEvent = (e) => {
    // this block shows a condition looking for checkout and success, 
    // this is a completed purchase using the GA 'purchase' event for conversion
    if (e.eventType == "onCheckout" && e.data.checkoutStatus == "success") {
      gtag("event", "purchase", {
        transaction_id: e.data.orderID,
        value: e.data.premium,
        items: [{
          item_id: "SKU_12345",
          item_name: '${ion}',
          currency: "USD",
          price: e.data.premium,
        }]
      });
    }

    // This block tracks which views are displayed 
    // this is configured to use the built-in GA event 'screen_view'
    if (e.eventType == "onViewChange") {
      gtag('event', 'screen_view', {
        'app_name': 'in-offer-element',
        'screen_name': e.data.viewID
      });
    }
    // This block tracks when quotes are made
    // This is configured to use a custom event and captures a custom dimension
    if (e.eventType == "onQuote") {
      gtag('event', 'quote', {
        'app_name': 'in-offer-element',
        'price': e.data.pricing,
      });
    }
  }
  };

  return (
    <div id="app">
      <h1>My App</h1>
      <BuddyOfferElement
        ion="MY_ION"
        partnerID="my-partner-id"
        viewType="offer-only"
        onUserEvent={handleUserEvent}
        stage="PRODUCTION"
      />
    </div>
  );
}
export default App;