Fruga Relay Docs Installation

Installation

How to install, initialize, and configure the Fruga Relay SDK for your platform. This reference covers the full installation steps via package managers, 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. Configure GitHub Packages

The Fruga SDK is hosted on GitHub Packages. To install it, you must configure your environment to authenticate with the registry using a Personal Access Token (PAT).

Step A: Create a Personal Access Token (PAT)

  1. Go to your GitHub Settings > Developer settings > Personal access tokens > Tokens (classic).
  2. Generate a new token with at least the read:packages scope.
  3. Copy the token.

Step B: Configure .npmrc

Create an .npmrc file in the root of your project and add:

@frugainsurance:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}

Step C: Set the Environment Variable

Set the NODE_AUTH_TOKEN environment variable in your development environment and CI/CD pipelines.

export NODE_AUTH_TOKEN=your_token_here

2. Install the SDK

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';

3. 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
      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>
  );
};

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.
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).

⚠️
Branding is not set in init(). Colours, theme defaults, launcher copy, and related appearance are configured for your partner environment on Fruga’s side and applied when the widget loads. See Customising the Interface and Branding. 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.