@buddy-technology/offer-component 0.2.5 → 0.3.1

package/API.md

@@ -20,6 +20,12 @@
 <dd></dd>
 <dt><a href="#ThemeObject">ThemeObject</a> : <code>Object</code></dt>
 <dd></dd>
+<dt><a href="#LogoOverride">LogoOverride</a> : <code>Object</code></dt>
+<dd></dd>
+<dt><a href="#EventObject">EventObject</a> : <code>Object</code></dt>
+<dd></dd>
+<dt><a href="#OnUserEventCallback">OnUserEventCallback</a> : <code>function</code></dt>
+<dd></dd>
 <dt><a href="#BuddyOfferElementProps">BuddyOfferElementProps</a> : <code>Object</code></dt>
 <dd></dd>
 </dl>
@@ -114,6 +120,38 @@ const theme = {
 		},
 	};
 ```
+<a name="LogoOverride"></a>
+
+## LogoOverride : <code>Object</code>
+**Kind**: global typedef  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| url | <code>String</code> | destination url when users click the trust badge |
+| src | <code>String</code> | src of the img for displaying the trust badge |
+| [alt] | <code>String</code> | alt text for trust badge image |
+
+<a name="EventObject"></a>
+
+## EventObject : <code>Object</code>
+**Kind**: global typedef  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| eventType | <code>string</code> | the type of user event (eg:'onCheckout') |
+| data | <code>object</code> | data object related to the user event. |
+| data.timestamp | <code>object</code> | timestamp of the event. All events have a timestamp property. |
+
+<a name="OnUserEventCallback"></a>
+
+## OnUserEventCallback : <code>function</code>
+**Kind**: global typedef  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| type | [<code>EventObject</code>](#EventObject) | the type of user event (eg:'onCheckout') |
+
 <a name="BuddyOfferElementProps"></a>
 
 ## BuddyOfferElementProps : <code>Object</code>
@@ -124,9 +162,13 @@ const theme = {
 | --- | --- | --- | --- |
 | ion | <code>String</code> |  | The ion id for the offering. |
 | partnerID | <code>String</code> |  | The partner ID required for instantiating the Offer |
+| [stage] | <code>String</code> | <code>&quot;STAGING&quot;</code> | toggle's the environment for the Offer Component. Defaults to STAGING. Must be set to "PRODUCTION" before going live. |
 | [viewType] | <code>String</code> | <code>&quot;paginated&quot;</code> | establishes how the offer should display to the user. One of: 'paginated', 'single-form' or 'offer-only.' |
+| [theme] | [<code>ThemeObject</code>](#ThemeObject) |  | theming object for customizing offer component's styles |
 | [data] | [<code>DataObject</code>](#DataObject) |  | Any customer or policy data to pre-fill the offer with. Refer to your individual ION for data structure. |
-| [onAddToCart] | [<code>AddToCartFunction</code>](#AddToCartFunction) |  | - |
-| [onRemoveFromCart] | [<code>RemoveFromCartFunction</code>](#RemoveFromCartFunction) |  |  |
-| [theme] | [<code>ThemeObject</code>](#ThemeObject) |  |  |
+| [onUserEvent] | [<code>OnUserEventCallback</code>](#OnUserEventCallback) |  | callback function for tracking user behavioral data. Triggers on user interactions such as input focus/blur, in-app navigation, etc. Refer to the docs for more details. |
+| [onAddToCart] | [<code>AddToCartFunction</code>](#AddToCartFunction) |  | callback function triggered when users opt into an offer-only offer. |
+| [onRemoveFromCart] | [<code>RemoveFromCartFunction</code>](#RemoveFromCartFunction) |  | callback function triggered when users opt out of an offer-only offer. |
+| includeCheckout | <code>boolean</code> |  | toggles whether or not to display the card capture checkout view. Defaults to true. When false, an AddToCart callback must be provided. |
+| [logoOverride] | [<code>LogoOverride</code>](#LogoOverride) |  | object for overriding Buddy's trust badge. |
 

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # CHANGELOG 
 
+### v0.3.1  
+2023-06-27  
+ 
+- add missing props to types file   
+- update docs    
+---  
+  
+
+### v0.2.6  
+2022-11-09  
+ 
+- Added testing as an environment    
+---  
+  
+
 ### v0.2.5  
 2022-08-09  
  

package/README.md

@@ -38,11 +38,12 @@ export default App;
 | *ion | string | | The ion ID for the product to be presented |
 | stage | enum | "STAGING" | One of: `"STAGING"`, `"PRODUCTION"`. Set to `"STAGING"` (default) for testing and development. |
 | viewType | enum | `"paginated"` | Sets how the offer element is displayed. One of: `"paginated"`, `"single-form"`, `"offer-only"`. _See [View types](#view-types) for details._|
+| data | object | | Customer or policy data to pre-load the offer with. Refer to specific ION documentation for the data structure.  |
+| theme | object | |The [theme](#styling) object for passing in styles and color palettes |
+| onUserEvent | function | | A callback for tracking user behavioral data. See [Capturing Data](#capturing-data) for details. |
 | includeCheckout | boolean | `true` | Toggles whether to render the secure checkout.  |
 | onAddToCart | function | | The callback fired when a user opts into an offer. See Buddy's Partner API docs for details on how to complete the transaction.|
 | onRemoveCart | function | | The callback fired when a user opts out of the offer. |
-| data | object | | Customer or policy data to pre-load the offer with. Refer to specific ION documentation for the data structure.  |
-| theme | object | |The [theme](#styling) object for passing in styles and color palettes |
 _*required_
 
 ---
@@ -292,4 +293,251 @@ Some components can be directly modified by accessing their class names in the t
 - 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
+
+```javascript
+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.
+
+##### `onViewChange`
+
+Triggers when users click to a new screen in a paginated view mode.
+
+_data returned_
+| Name      | Type   | Description                                             |
+|-----------|--------|---------------------------------------------------------|
+| `viewId`    | string | the id of the current view                              |
+| `timestamp` | number | the timestamp when the event occurred in milliseconds   |
+
+
+##### `onScrollToView`
+
+Triggers when or scroll to a section in single-page view mode.
+
+_data returned_
+
+| Name      | Type   | Description                                             |
+|-----------|--------|---------------------------------------------------------|
+| `viewId`    | string | the id of the current view                              |
+| `timestamp` | number | the timestamp when the event occurred in milliseconds   |
+
+##### `onQuote`
+
+Triggers when the app displays retrieves a quote for the policy
+
+_data returned_
+
+| Name      | Type   | Description                                                                       |
+|-----------|--------|-----------------------------------------------------------------------------------|
+| `pricing`   | number | if successful, the price of the policy                                            |
+| `error`     | string | if unsuccessful, a message explaining the type of error encountered when attempting to quote |
+| `timestamp` | number | the timestamp when the event occurred in milliseconds                           |
+
+
+##### `onCheckout`
+
+Triggers during the check out process
+
+_data returned_
+
+| Name               | Type   | Description                                                                       |
+|--------------------|--------|-----------------------------------------------------------------------------------|
+| `checkoutStatus` | enum   | one of `['start', 'success', 'error']`                                               |
+| `premium`        | number | the total premium of the purchase                                                 |
+| `error`          | string | if unsuccessful, a message explaining the type of error encountered              |
+| `timestamp`      | number | the timestamp when the event occurred in milliseconds                            |
+
+		
+##### `onFocus`
+
+Triggers when an input is focused
+
+_data returned_
+
+| Name             | Type   | Description                                             |
+|------------------|--------|---------------------------------------------------------|
+| `elementId`    | string | the id of the invalid field/input                       |
+| `timestamp`    | number | the timestamp when the event occurred in milliseconds   |
+
+
+##### `onBlur`
+
+Triggers when an input is blurred
+
+_data returned_
+
+| Name             | Type   | Description                                             |
+|------------------|--------|---------------------------------------------------------|
+| `elementId`    | string | the id of the invalid field/input                       |
+| `timestamp`    | number | the timestamp when the event occurred in milliseconds   |
+
+##### `onRadioSelection`
+
+Triggers when a radio button is selected
+
+_data returned_
+
+| Name        | Type   | Description                                             |
+|-------------|--------|---------------------------------------------------------|
+| `elementId` | string | the id of the invalid field/input                      |
+| `value`     | any    | the value of the selected radio                         |
+| `timestamp` | number | the timestamp when the event occurred in milliseconds   |
+
+##### `onSlide`
+
+Triggers when a slider input is changed
+
+_data returned_
+
+| Name        | Type   | Description                                             |
+|-------------|--------|---------------------------------------------------------|
+| `elementId` | string | the id of the invalid field/input                      |
+| `value`     | any    | the value of the selected radio                         |
+| `timestamp` | number | the timestamp when the event occurred in milliseconds   |
+
+##### `onCheckboxSelection`
+
+Triggers when a checkbox is selected
+
+_data returned_
+
+| Name         | Type    | Description                                             |
+|--------------|---------|---------------------------------------------------------|
+| `elementId` | string  | the id of the invalid field/input                       |
+| `checked`   | boolean | whether the box is checked/unchecked                    |
+| `value`     | string  | the label of the selected checkbox                      |
+| `timestamp` | number  | the timestamp when the event occurred in milliseconds   |
+
+##### `onBlur`
+
+Triggers when an input is blurred
+
+_data returned_
+
+| Name             | Type   | Description                                             |
+|------------------|--------|---------------------------------------------------------|
+| `elementId`    | string | the id of the invalid field/input                       |
+| `timestamp`    | number | the timestamp when the event occurred in milliseconds   |
+
+##### `onValidationError`
+
+Triggers when an input is triggered as invalid
+
+_data returned_
+
+| Name                 | Type   | Description                                             |
+|----------------------|--------|---------------------------------------------------------|
+| `elementId`        | string | the id of the invalid field/input                       |
+| `validationError`  | string | the type of validation error encountered                |
+| `timestamp`        | number | the timestamp when the event occurred in milliseconds   |
+
+##### `onExternalLink`
+
+Triggers when an input is triggered as invalid
+
+_data returned_
+
+| Name                 | Type   | Description                                             |
+|----------------------|--------|---------------------------------------------------------|
+| `externalLinkUrl`  | string | the url of the link                                     |
+| `timestamp`        | number | the timestamp when the event occurred in milliseconds   |
+
+### Google Analytics example
+
+```javascript
+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;
+```

package/dist/index.js

@@ -81,15 +81,38 @@ function _interopRequireWildcard(obj, nodeInterop) { if (!nodeInterop && obj &&
  * 	};
  */
 
+/**
+ * @typedef {Object} LogoOverride
+ * @property {String} url - destination url when users click the trust badge
+ * @property {String} src - src of the img for displaying the trust badge
+ * @property {String} [alt] - alt text for trust badge image
+ */
+
+/**
+ *@typedef {Object} EventObject
+ *@param {string} eventType - the type of user event (eg:'onCheckout')
+ *@param {object} data - data object related to the user event.
+ *@param {object} data.timestamp - timestamp of the event. All events have a timestamp property.
+*/
+
+/**
+ *@typedef {Function} OnUserEventCallback
+ *@param {EventObject} type - the type of user event (eg:'onCheckout')
+*/
+
 /**
  * @typedef {Object} BuddyOfferElementProps
  * @property {String} ion - The ion id for the offering.
  * @property {String} partnerID - The partner ID required for instantiating the Offer
+ * @property {String} [stage="STAGING"] - toggle's the environment for the Offer Component. Defaults to STAGING. Must be set to "PRODUCTION" before going live.
  * @property {String} [viewType="paginated"] - establishes how the offer should display to the user. One of: 'paginated', 'single-form' or 'offer-only.'
+ * @property {ThemeObject} [theme] - theming object for customizing offer component's styles
  * @property {DataObject} [data] - Any customer or policy data to pre-fill the offer with. Refer to your individual ION for data structure.
- * @property {AddToCartFunction} [onAddToCart] -
- * @property {RemoveFromCartFunction} [onRemoveFromCart]
- * @property {ThemeObject} [theme]
+ * @property {OnUserEventCallback} [onUserEvent] - callback function for tracking user behavioral data. Triggers on user interactions such as input focus/blur, in-app navigation, etc. Refer to the docs for more details.
+ * @property {AddToCartFunction} [onAddToCart] - callback function triggered when users opt into an offer-only offer.
+ * @property {RemoveFromCartFunction} [onRemoveFromCart] - callback function triggered when users opt out of an offer-only offer.
+ * @property {boolean} includeCheckout - toggles whether or not to display the card capture checkout view. Defaults to true. When false, an AddToCart callback must be provided.
+ * @property {LogoOverride} [logoOverride] - object for overriding Buddy's trust badge.
  */
 
 /**

package/dist/util.js

@@ -31,9 +31,14 @@ const SCRIPTS = {
     URL: 'http://localhost:8008/index.js',
     REGEX: /^http:\/\/localhost:8008\/index\.js\/?(\?.*)?$/
   },
+  // TODO: Delete this in favor of "testing", once we're sure nothing is using it.
   DEVELOPMENT: {
     URL: 'https://js.buddy.insure/v2/dev/index.js',
-    REGEX: /^https:\/\/js\.buddy\.insure\/v2\/staging\/index\.js\/?(\?.*)?$/
+    REGEX: /^https:\/\/js\.buddy\.insure\/v2\/dev\/index\.js\/?(\?.*)?$/
+  },
+  TESTING: {
+    URL: 'https://js.buddy.insure/v2/testing/index.js',
+    REGEX: /^https:\/\/js\.buddy\.insure\/v2\/testing\/index\.js\/?(\?.*)?$/
   },
   STAGING: {
     URL: 'https://js.buddy.insure/v2/staging/index.js',

package/lib/types.d.ts

@@ -70,21 +70,54 @@ declare type ThemeObject = {
     overrides?: OverridesObject;
 };
 
+/**
+ * @property url - destination url when users click the trust badge
+ * @property src - src of the img for displaying the trust badge
+ * @property [alt] - alt text for trust badge image
+ */
+declare type LogoOverride = {
+    url: string;
+    src: string;
+    alt?: string;
+};
+
+/**
+ * @param eventType - the type of user event (eg:'onCheckout')
+ * @param data - data object related to the user event.
+ * @param data.timestamp - timestamp of the event. All events have a timestamp property.
+ */
+declare type EventObject = any;
+
+/**
+ * @param type - the type of user event (eg:'onCheckout')
+ */
+declare type OnUserEventCallback = (type: EventObject) => void;
+
 /**
  * @property ion - The ion id for the offering.
  * @property partnerID - The partner ID required for instantiating the Offer
+ * @property [stage = STAGING] - toggle's the environment for the Offer Component. Defaults to STAGING. Must be set to PRODUCTION before going live.
  * @property [viewType = paginated] - establishes how the offer should display to the user. One of: 'paginated', 'single-form' or 'offer-only.'
+ * @property [theme] - theming object for customizing offer component's styles
  * @property [data] - Any customer or policy data to pre-fill the offer with. Refer to your individual ION for data structure.
- * @property [onAddToCart] - -
+ * @property [onUserEvent] - callback function for tracking user behavioral data. Triggers on user interactions such as input focus/blur, in-app navigation, etc. Refer to the docs for more details.
+ * @property [onAddToCart] - callback function triggered when users opt into an offer-only offer.
+ * @property [onRemoveFromCart] - callback function triggered when users opt out of an offer-only offer.
+ * @property includeCheckout - toggles whether or not to display the card capture checkout view. Defaults to true. When false, an AddToCart callback must be provided.
+ * @property [logoOverride] - object for overriding Buddy's trust badge.
  */
 declare type BuddyOfferElementProps = {
     ion: string;
     partnerID: string;
+    stage?: string;
     viewType?: string;
+    theme?: ThemeObject;
     data?: DataObject;
+    onUserEvent?: OnUserEventCallback;
     onAddToCart?: AddToCartFunction;
     onRemoveFromCart?: RemoveFromCartFunction;
-    theme?: ThemeObject;
+    includeCheckout: boolean;
+    logoOverride?: LogoOverride;
 };
 
 declare function BuddyOfferElement(options: BuddyOfferElementProps): FunctionComponent<BuddyOfferElementProps>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buddy-technology/offer-component",
-  "version": "0.2.5",
+  "version": "0.3.1",
   "author": "Buddy Technology",
   "main": "dist/index.js",
   "types": "./lib/types.d.ts",