Skip to main content

Usage

Configuration​

All of the embedded offer framework packages consume a standard config object for setting up the offer.

export interface Config {
  /**
   * Client ID part of your API key.
   */
  client_id: string;

  /**
   * Theme options
   */
  theme?: Theme;

  /**
   * A unique id for this offer. This value should be defined if there are 
   * multiple offers being presented on a single page. You can typically
   * set this value to an order id, or an item id. 
   */
  unique_offer_id?: string;

  /**
   * Payment configuration
   */
  payments?: PaymentElementConfig;

  /**
   * Customer details. If this customer is provided, it will override any customer
   * defined in any specific product configuration.
   */
  customer?: Customer;

  /**
   * Configuration / quote information for various products
   */
  product_config?: ProductConfig;
}

Product Config​

The product_config field takes an object of product codes with an array of quote requests. These quote requests always map to one of our individual quote request endpoints. As an example, to create a quote for Ticket Refund protection, you would supply the product code that is part of the quote endpoint, and an array of quote objects. The endpoint for quoting this product is /v1/quote/ticket-refund with the product code being ticket-refund

product_config: {
    "ticket-refund": [{
      customer: {
        email_address: "user@example.com",
        state: "MN",
        country: "US",
        postal_code: "string",
        first_name: "string",
        middle_name: "string",
        last_name: "string",
        phone_number: "string",
        street: "string",
        city: "string"
      },
      metadata: {},
      partner_id: "string",
      policy_attributes: {
        insurable_amount: 2500,
        insurable_amount_currency: "USD",
        event_start_date: "2024-07-29",
        event_end_date: "2024-07-29"
      },
    }]
}

You'll notice the reference for #offer when instantiating the VerticalInsure object below. This is a document query selector and will be the element which we will mount the embedded offer.

<!-- Element where the offer will be mounted -->
<div id="offer"></div>

<script>
new VerticalInsure("#offer", {
  client_id: "test_********************************",
  product_config: {
    "gap-medical": [{
        "customer": {
            "email_address: user@example.com",
            "first_name: James",
            "last_name: Doe",
            "state: MN",
            "postal_code: 55432"
        },
        "policy_attributes": {
            "coverage_end_date": "YYYY-MM-DD",
            "coverage_start_date": "YYYY-MM-DD",
            "coverage_type": "SOCCER",
            "covered_person": {
                "birth_date": "YYYY-MM-DD",
                "state": "MN",
                "first_name": "John",
                "last_name": "Doe",
                "street": "NA"
            }
        }
    }]
  }
});
</script>

Listening for Events​

The embedded offer packages fire a standard JavaScript CustomEvent named offer-state-change. You can listen to this event using the standard addEventListener approach.

window.addEventListener("offer-state-change", (e) => {
  console.log(JSON.stringify(e.detail.quotes, null, 2));
});

This event is fired upon user interaction with the embedded offer and returns the accepted quotes that the user has selected. This means the event could come back with an empty array if no quote has been selected.

Our various packages also provide a standard way to subscribe to this event which provides an abstraction on top of the basic addEventListener functionality.

<!-- Element where the offer will be mounted -->
<div id="offer"></div>

<script>
new VerticalInsure("#offer", {
  client_id: "test_********************************",
  product_config: {
    "gap-medical": [{
        "customer": {
            "email_address": "user@example.com",
            "first_name": "James",
            "last_name": "Doe",
            "state": "MN",
            "postal_code": "55432"
        },
        "policy_attributes": {
            "coverage_end_date": "YYYY-MM-DD",
            "coverage_start_date": "YYYY-MM-DD",
            "coverage_type": "SOCCER",
            "covered_person": {
                "birth_date": "YYYY-MM-DD",
                "state": "MN",
                "first_name": "John",
                "last_name": "Doe",
                "street": "NA"
            }
        }
    }]
  }
}, 
function(offerState) {
  console.log(JSON.stringify(offerState.quotes));
});
</script>

Actions​

The embedded offer supports 3 different methods that can be used to interact with the offer in various ways.

  • validate: Validates the form in the offer to determine if the user has completed selecting required choices.
  • tokenizePaymentMethod: If payments are configured on the offer, tokenizes the payment method into a PCI-compliant token for transport to your backend.
  • update: Updates the offer with new data for the quote.
tip

With React and Vue, you don't need to explicitly perform update commands, as updating the input config update will sync these changes automatically.

<div id="offer"></div>
<button id="validate-button">Validate</button>
<button id="tokenize-button">Tokenize Payment Method</button>
<button id="update-button">Update Quote</button>
<script>
const verticalInsure = new VerticalInsure("#offer", {
  client_id: "test_********************************",
  product_config: {
    "gap-medical": [{
        "customer": {
            "email_address": "user@example.com",
            "first_name": "James",
            "last_name": "Doe",
            "state": "MN",
            "postal_code": "55432"
        },
        "policy_attributes": {
            "coverage_end_date": "YYYY-MM-DD",
            "coverage_start_date": "YYYY-MM-DD",
            "coverage_type": "SOCCER",
            "covered_person": {
                "birth_date": "YYYY-MM-DD",
                "state": "MN",
                "first_name": "John",
                "last_name": "Doe",
                "street": "NA"
            }
        }
    }]
  }
}, 
function(offerState) {
  console.log(JSON.stringify(offerState.quotes));
});

const validateButton = document.getElementById("validate-button");
validateButton.addEventListener("click", async (e) => {
  e.preventDefault();
  const status = await verticalInsure.validate();
  console.log(status);
});

const tokenizeButton = document.getElementById("tokenize-button");
tokenizeButton.addEventListener("click", async (e) => {
  e.preventDefault();
  const token = await verticalInsure.tokenizePaymentMethod();
  console.log(token);
});

const updateButton = document.getElementById("update-button");
updateButton.addEventListener("click",(e) => {
  e.preventDefault();
  verticalInsure.update({
    "gap-medical": [{
        "customer": {
            "email_address": "user@example.com",
            "first_name": "James",
            "last_name": "Doe",
            "state": "MN",
            "postal_code": "55432"
        },
        "policy_attributes": {
            "coverage_end_date": "YYYY-MM-DD",
            "coverage_start_date": "YYYY-MM-DD",
            "coverage_type": "SOCCER",
            "covered_person": {
                "birth_date": "YYYY-MM-DD",
                "state": "MN",
                "first_name": "John",
                "last_name": "Doe",
                "street": "NA"
            }
        }
    }]
  });
});
</script>

Theming​

The standard config object accepts the following theme input

export interface Theme {
  colors?: {
    background?: string;
    primary?: string;
    primary_contrast?: string;
    secondary?: string;
    secondary_contrast?: string;
    neutral?: string;
    neutral_contrast?: string;
    error?: string;
    error_contrast?: string;
    success?: string;
    success_contrast?: string;
    border?: string;
  },
  font_family?: string;
  components?: {
    border_radius?: string;
  }
}

Fonts​

The font_family field can accept any Google font name. For example, the following config will use Roboto as the standard font in the offer.

{
  theme: {
    font_family: 'Roboto'
  }
}