Frontend widget integration

The Hakuna widget is a quick and easy way to offer your customers product protection in your online store without having to add protection products to your ERP system or handle the insurance premiums. Once customers complete their transaction with you, they'll be able to click a link to a Hakuna-hosted payment page where they can activate their chosen product protection plan.

To offer your customers product protection with the frontend widget, all you need to do is initialize the Hakuna widget and then display it on your product detail pages, in the cart, and at checkout.

We'll walk you through the three steps below:

1. Initialize the widget

To ensure that your widget configuration loads properly and your customers see your tailored protections, content, and design, add the following script to each page you want to display the widget on:

<script async src="https://protection-widget.hellohakuna.com/sdk.js?pk="></script>

2. Render the widget

To actually display the offering on a page and give your customers the option to add product protection to the products they're purchasing, you need to render the widget on the product detail page, in the cart, and/or at checkout. It's up to you which placement option(s) you choose, but you will need to choose at least one!

On the product detail page

On the product detail page, the widget gives customers the option to add product protection to a product before they add it to the cart. If they click on the link to learn more, a modal with a button to add protection and more information about the offering will pop up.

Product detail page example

Modal example

To render the widget on the product detail page, define a <div> with two data-* attributes by placing the following code where you want the widget to be displayed on the page:

<div
  data-hakuna-component="hakuna-details-page"
  data-hakuna-props='<PLAN_DETAILS_PROPS_AS_JSON_STRING>'
><!--Hakuna widget placeholder--></div>

Within the widget components, pass us the following properties as a JSON string:

interface HakunaDetailsPageProps {
  productId: string;
  productBrand: string;
  productTitle: string;
  hakunaProductCategory: number; // provided by Hakuna
  productPriceAmount: number; // product price in cents
  productPriceCurrency: 'eur'; // product price currency code
}

Example

<div
  data-hakuna-component="hakuna-details-page"
  data-hakuna-props='{
	  "productId": "444010197",
	  "productBrand": "Apple",
	  "productTitle": "iPhone 14",
	  "hakunaProductCategory": 101,
	  "productPriceAmount": 81900,
	  "productPriceCurrency": "eur"
	}'
><!--Hakuna widget placeholder--></div>

In the cart

In the cart, the widget enables customers to add and/or manage their product protection for each line item. They can see which products they have already opted to add protection to, add protection to any unprotected products, and remove previously added protection.

Cart example

To render the widget in the cart, place the following code below each item in the cart:

<div
  data-hakuna-component="hakuna-cart-item"
  data-hakuna-props='<CART_ITEM_PROPS_AS_JSON_STRING>'
><!--Hakuna widget placeholder--></div>

Within the widget components, pass us the following properties as a JSON string:

interface HakunaCartItemProps {
  productId: string;
  productBrand: string;
  productTitle: string;
  hakunaProductCategory: number;
  productPriceAmount: number; // product price in cents
  productPriceCurrency: 'eur'; // product price currency code
  itemQuantity: number;
}

If the quantity of a cart item is updated, the quantity passed to the associated Hakuna cart item components should also be updated.

If a cart item is removed from the cart, the associated Hakuna cart item component should also be removed from the page.

Example

<div
  data-hakuna-component="hakuna-cart-item"
  data-hakuna-props='{
	"productId": "444010197",
	"productBrand": "Apple",
	"productTitle": "iPhone 14",
	"hakunaProductCategory": 101,
	"productPriceAmount": 81900,
	"productPriceCurrency": "eur",
	"itemQuantity": 3
	}'
><!--Hakuna widget placeholder--></div>

At checkout

At checkout, the widget gives customers another opportunity to add and/or manage their product protection. They can still adjust the product protection as they see fit by adding or removing it.

Checkout example (address)

To render the widget at checkout, place the following code below each item:

<div
  data-hakuna-component="hakuna-checkout-item"
  data-hakuna-props='<CHECKOUT_ITEM_PROPS_AS_JSON_STRING>'
><!--Hakuna widget placeholder--></div>

Within the widget components, pass us the following properties as a JSON string:

interface HakunaCheckoutItemProps {
  productId: string;
  productBrand: string;
  productTitle: string;
  hakunaProductCategory: number;
  productPriceAmount: number; // product price in cents
  productPriceCurrency: 'eur'; // product price currency code
  itemQuantity: number;
}

Example

<div
  data-hakuna-component="hakuna-checkout-item"
  data-hakuna-props='{
	"productId": "444010197",
	"productBrand": "Apple",
	"productTitle": "iPhone 14",
	"hakunaProductCategory": 101,
	"productPriceAmount": 81900,
	"productPriceCurrency": "eur",
	"itemQuantity": 3
	}'
><!--Hakuna widget placeholder--></div>

3. Confirm checkout

To pass the required transaction data to Hakuna after a successful purchase in your shop and display confirmation to the customer (including a CTA for them to complete payment and activate their protection), you will need to render the widget on your order confirmation page.

Confirmation example

To render the widget at purchase confirmation, place the following code where you want the widget to be displayed:

<div
  data-hakuna-component="hakuna-checkout-confirmation"
  data-hakuna-props='<CHECKOUT_CONFIRMATION_PROPS_AS_JSON_STRING>'
><!--Hakuna widget placeholder--></div>

Within the widget components, pass us the following properties as a JSON string:

interface HakunaCheckoutConfirmationProps {
  orderId: string; // identifier of an order placed for checkout
	customer: {
		email: string;
		firstName: string;
		lastName: string;
	};
	customerBillingAddress: {
		line1: string;
		line2 string;
		zipCode: string;
    		city: string;
		country: 'de'; // 2-letter country code
	};
  purchasedItems: Array<{
		productId: string;
		itemQuantity: number;
  }>;
}

Example

<div
  data-hakuna-component="hakuna-checkout-confirmation"
  data-hakuna-props='{
		"orderId": "K-TPWNK-12345678",
		"customer": {
			"email": "[e-mail]",
			"firstName": "Max",
			"lastName": "Mustermann"
		},
		"customerBillingAddress": {
			"line1": "Hauptstr. 1",
			"line2": "",
			"zipCode": "12345",
			"city": "München",
			"country": "de"
		},
		"purchasedItems": [
			{
				"productId": "444010197",
				"itemQuantity": "3"
			}
		]
	}'
><!--Hakuna widget placeholder--></div>

That's all you need to do!

---

What happens after checkout confirmation?

We will send customers an email with a link to the payment page immediately after they complete their purchase in your store.

Example email

Whether they click on the link on your order confirmation page or in the email, the customer will be redirected to the Hakuna payment page.

Hakuna payment page example

Once the customer completes their payment for product protection, we will fully activate their protection, and send them a confirmation email with their insurance documents.

On customizing the widget

The widget is fully customizable, so we can adjust the colors, fonts, branding, content, etc. to make it perfectly fit your business! Just contact your Hakuna Onboarding Team for more information.