@frontend-sdk/klaviyo NPM

Klaviyo

Klaviyo integration for Shogun Frontend.

Klaviyo is an email marketing platform created for online businesses — featuring powerful email and SMS marketing automation.

Klaviyo website →

Installation

yarn add @frontend-sdk/klaviyo

npm install @frontend-sdk/klaviyo

Background

@frontend-sdk/klaviyo covers the following use-cases/features:

display signup forms (both popup and embedded) designed in the Klaviyo app
subscribe to notification for an out-of-stock product
tracking for arbitrary events as well as for "visited product" and "added to cart" events

📘
With @frontend-sdk/klaviyo, you don't need to add manually any snippet stated in Klaviyo's documentation.

Signup Forms

In Klaviyo, you can design a signup form to collect users into subscription lists.

Inject Klaviyo's script with your site ID:

import { useKlaviyo } from '@frontend-sdk/klaviyo'

const App = () => {
	useKlaviyo('<Klaviyo site ID>')
	return …
}

Popup forms will be displayed automatically based on their rules.
For embedded forms, add a div with form ID where you want this form to be displayed.
```
<div class="klaviyo-form-Abc123"></div>

```
There is a known problem when embedded forms are not displayed when a user navigates to a page with an already loaded script. To fix that, there is a hacky solution.
You need to use a different hook (useKlaviyoForceReload) to inject script each time you need to show embedded form.
Take a note that if you want to use this hook, use it in all places instead of useKlaviyo.
```
import { useKlaviyoForceReload } from '@frontend-sdk/klaviyo'

const Footer = () => {
  useKlaviyoForceReload('<Klaviyo site ID>')
  return (
    <>
      {/* … */}
      <div class="klaviyo-form-Abc123"></div> {/* Abc123 — form id */}
      {/* … */}
    </>
  )
}
```

Custom embedded signup forms

You can also make custom signup forms and not load Klaviyo's script (improving performance).

It can utilize:

either Klaviyo's signup page (https://manage.kmail-lists.com/subscriptions/subscribe)

<form action="https://manage.kmail-lists.com/subscriptions/subscribe" method="POST">
  <input type="hidden" name="g" value={listId} />
  <input type="email" name="email" placeholder="Email" />
  <button type="submit">Subscribe to newsletter</button>
</form>

or Klaviyo's API endpoint (https://manage.kmail-lists.com/ajax/subscriptions/subscribe)

const emailRef = useRef(null)
const firstNameRef = useRef(null)
const lastNameRef = useRef(null)
const onSubmit = (event) => {
  event.preventDefault()
  const email = emailRef.current?.value
  const firstName = firstNameRef.current?.value
  const lastName = lastNameRef.current?.value
  const data = {
    g: listId,
    email: email ?? '',
    $fields: '$first_name,$last_name',
    $first_name: firstName ?? '',
    $last_name: lastName ?? '',
  }
  const urlData = new URLSearchParams(data)
  fetch(`https://manage.kmail-lists.com/ajax/subscriptions/subscribe`, {
    method: 'POST',
    body: urlData,
  })
}
return (
  <form onSubmit={onSubmit}>
    <input type="email" name="email" placeholder="Email" ref={emailRef} />
    <input type="text" name="firstName" placeholder="First Name" ref={firstNameRef} />
    <input type="text" name="lastName" placeholder="Last Name" ref={lastNameRef} />
    <button type="submit">Subscribe to newsletter</button>
  </form>
)

Tracking

To use Klaviyo's tracking, just use one of the provided functions:

identifyUser(userData) — to identify user, must be called before other functions to track properly
trackEvent(name, eventData) — to track arbitrary event with custom name
trackRecentlyViewedItem(product) — to track product as recently viewed
trackVisitedProduct(product) — to track "Visited Product" event
trackAddedToCart(product) — to track "Added to Cart" event

import { identifyUser, trackVisitedProduct, trackAddedToCart } from '@frontend-sdk/klaviyo'

const Component: React.FC<Props> = ({ siteId }) => {
  useKlaviyo(siteId) /* Klaviyo's script should be loaded */
  identifyUser({ $email: 'user@email.local' }) /* identify user before tracking events */
  return (
    <>
      <button type="button" onClick={() => trackVisitedProduct(product)}>
        visit product
      </button>
      <button type="button" onClick={() => trackAddedToCart(product)}>
        add to cart
      </button>
    </>
  )
}

Back-in-Stock

If a product is out-of-stock, the user may want to be notified when it is back in stock.

For that purpose, Klaviyo has a back-in-stock flow. You need to add integration to your store (Shopify or BigCommerce) in the Klaviyo.

Klaviyo then collects emails for each product separately, and when inventory for such product, increases it notifies users.

Klaviyo's script

Klaviyo has a script that can detect if a product on a page is out-of-stock and automatically adds the "Notify me" button that opens a modal form to enter an email.

Unfortunately, such use case has limitations:

for Shopify in all products should have /products/ in their path
for Shopify product should have and access to Shopify's product.js JSON to get information about inventory
for BigCommerce product page should have a form with action={//${location.hostname}/cart.php} and inside an input with name="product_id" value=<product id>
for BigCommerce product page should have meta tag with property="og:type" content="product"
behavior is limited to a custom button that appears in the form if a product is out-of-stock; on click it opens a modal form that collects email
customization is limited to Klaviyo's API (for Shopify, for BigCommerce)

Using custom form

To overcome those limitations, it is better to create a custom form for collecting email and control when it should be shown.

To send data on this form submit we provide a subscribeToBackInStock() function with following parameters:

name	type	description
`siteId`	required	Klaviyo ID of site
`email`	required	user email
`product`	required	product ID
`variant`	required	variant ID
`platform`	required	`'shopify'` or `'bigcommerce'`
`shouldSubscribe`	optional	(`boolean`) whether to additionally subscribe to a newsletter
`listId`	optional	Klaviyo ID of the newsletter to subscribe

Example of a form with option to subscribe to a newsletter:

import { subscribeToBackInStock } from '@frontend-sdk/klaviyo'

const Component = ({ siteId, listId, productId, variantId }) => {
  const [email, setEmail] = useState('')
  const [shouldSubscribe, setShouldSubscribe] = useState(false)
  const onSubmit = (event) => {
    event.preventDefault()
    subscribeToBackInStock({
      siteId,
      email,
      product: productId,
      variant: variantId,
      listId,
      shouldSubscribe,
      platform: 'shopify' /* or 'bigcommerce' */,
    })
  }
  return (
    <form onSubmit={onSubmit}>
      <input type="email" placeholder="Email" value={email} onChange={(e) => setEmail(e.target.value)} />
      <br />
      <input
        type="checkbox"
        id="newsletter"
        checked={shouldSubscribe}
        onChange={() => setShouldSubscribe(!shouldSubscribe)}
      />
      <label htmlFor="newsletter">Subscribe to newsletter</label>
      <br />
      <button type="submit">Notify me when available</button>
    </form>
  )
}

Or in case of no need of option to subscribe to a newsletter:

import { subscribeToBackInStock } from '@frontend-sdk/klaviyo'

const Component = ({ siteId, productId, variantId }) => {
  const [email, setEmail] = useState('')
  const onSubmit = (event) => {
    event.preventDefault()
    subscribeToBackInStock({
      siteId,
      email,
      product: productId,
      variant: variantId,
      platform: 'shopify' /* or 'bigcommerce' */,
    })
  }
  return (
    <form onSubmit={onSubmit}>
      <input type="email" placeholder="Email" value={email} onChange={(e) => setEmail(e.target.value)} />
      <br />
      <button type="submit">Notify me when available</button>
    </form>
  )
}

Examples

You can see usage examples in Storybook stories.

@frontend-sdk/klaviyo v0.25.1