Fruga Relay Docs Installation

Installation

How to embed, initialize, and configure the Fruga Relay SDK for your platform? The Relay Web SDK is a script-tag embed that mounts the widget into any container element on your page. This reference covers the full installation steps, all configuration options, and how to handle SDK lifecycle events.

💡
If you are setting up Relay for the first time, start with the Getting Started guide, which walks through the full integration end to end. This page is the SDK-specific reference for the frontend integration.

1. Install the SDK

You can integrate the SDK via your package manager (recommended for React, Vue, and modern frameworks) or directly via a CDN script tag.

Option A: NPM / PNPM (Recommended)

Install the @frugainsurance/sdk package using your preferred package manager.

💡
Always use `pnpm` unless your project strictly enforces another package manager.
pnpm add @frugainsurance/sdk

Then, import the required methods in your component:

import { init, mount, unmount } from '@frugainsurance/sdk';

Option B: CDN Script Tag

Add the SDK script to your HTML file before the closing </body> tag. This makes the window.FrugaLoader global available.

<script src="https://cdn.jsdelivr.net/npm/@frugainsurance/sdk/dist/index.global.js"></script>

2. Adding the container (Optional)

The widget can render as a modal overlay or mount inline within a specific element. If you want it to render inline, add an empty container element to your page.

<div id="fruga-widget-root" style="width:100%; min-height:600px;"></div>

3. Initialising the widget

Call init() to boot up the widget. By default, the widget will mount immediately (autoMount: true).

⚠️
Security Reminder: Do not embed private secrets. The SDK uses your public `partnerKey` and handles token exchanges securely through its backend.

Initialisation (NPM / React)

If you use React, initialize the widget within a useEffect and optionally disable autoMount to render it manually based on state.

import React, { useEffect } from 'react';
import { init, mount, unmount } from '@frugainsurance/sdk';

export const FrugaWidget = ({ partnerKey, userId }) => {
  useEffect(() => {
    init({
      partnerKey,
      userId,             // Optional identity context
      theme: 'light',      
      primaryColor: '#2563eb', // Matches your brand's primary color
      autoMount: false,   // Developer controls the mount timeline manually
      onClose: () => {
        console.log('Fruga: Widget was dismissed.');
      }
    });

    return () => {
      // Cleanup to prevent memory leaks if component unmounts
      unmount();
    };
  }, [partnerKey, userId]);

  return (
    <div className="flex flex-col gap-4">
      <!-- Container where the widget will mount if containerId is configured -->
      <div id="fruga-widget-root"></div>

      <button
        onClick={() => mount()}
        className="px-4 py-2 bg-blue-600 text-white rounded"
      >
        View Offers
      </button>
    </div>
  );
};

Initialisation (CDN)

Use the globally exposed FrugaLoader.init() method.

<script>
  document.addEventListener("DOMContentLoaded", () => {
    window.FrugaLoader.init({
      partnerKey: 'pk_live_fruga_demo',
      containerId: 'fruga-widget-root', 
      theme: 'light',
      primaryColor: '#2563eb', 
      autoMount: true,         // Mounts immediately on page load
      onClose: () => {
        console.log('Customer closed the widget.');
      }
    });
  });
</script>

Configuration Options

OptionTypeRequiredDescription
partnerKeystringYesYour public key identifying your partner environment. Use pk_test_... in development and pk_live_... in production.
containerIdstringNoThe ID of the DOM element where the widget should mount (defaults to fruga-widget-root). If provided, it renders inline.
theme'light' | 'dark'NoThe base theme of the widget. Defaults to 'light'.
primaryColorstringNoHex code string representing your brand’s primary accent color (e.g., #2563eb).
autoMountbooleanNoControls automatic DOM injection. Defaults to true. Set to false if you want to call mount() manually later.
onClosefunctionNoCallback function emitted when the widget is closed or dismissed internally by the user.
userIdstringNoOptional identity context. Passing this ensures the user’s session inherits any pre-authenticated state you’ve established.

Architecture & Styling

The SDK mounts an iframe shell to prevent your CSS from leaking into our widget and vice versa (Shadow DOM isolation).

⚠️
Styling is intentionally restricted to the configuration options like `theme` and `primaryColor`. Do not attempt CSS overrides on the internal iframe structure, as it will break isolation.

Troubleshooting

  • Widget fails to render: Verify your partnerKey is correct for the environment. Ensure your mount() logic aligns with your autoMount setting.
  • Multiple widgets rendering: If using React 18+ strict mode, ensure the component isn’t unmounting/remounting excessively without proper cleanup (unmount()), or wrap the initialization carefully so it only executes once.