Getting Started

Prerequisites

Before you begin, you’ll need:

Overview of the integration

A Relay integration has two distinct parts that work together: a small amount of backend code that signs tokens, and the widget loaded on your frontend. Here’s how they connect:

Step 1 — Add the Relay script to your page

Add the following script tag to your page, before the closing </body> tag. This loads the Relay SDK from Fruga’s CDN and makes the Fruga global available.

<script src="https://cdn.fruga.com/relay/v1/widget.js"></script>

Then add a container element on your page where the widget will mount:

<div id="fruga-relay"></div>

Step 2 — Create a backend endpoint that returns an assertion

Before you can initialise the widget, you need a server endpoint that generates a signed assertion JWT for the currently authenticated user. The widget will call this endpoint each time it loads.

The following example creates a simple endpoint in Node.js (Express), but the same approach applies in any backend language that supports JWT signing.

import express from 'express';
import jwt from 'jsonwebtoken';
import { v4 as uuidv4 } from 'uuid';

const app = express();

app.get('/fruga/assertion', (req, res) => {
  // Ensure the user is authenticated in your own system first
  if (!req.user) return res.status(401).end();

  const now = Math.floor(Date.now() / 1000);

  const assertion = jwt.sign(
    {
      iss: 'partner:p_123',          // your partner ID, provided by Fruga
      aud: 'fruga:external_token_exchange',
      iat: now,
      exp: now + 60,              // 60 seconds — keep this short
      jti: uuidv4(),              // unique ID — prevents replay attacks
      userRef: req.user.id,        // your internal user ID for this user
    },
    process.env.FRUGA_SIGNING_SECRET,
    { algorithm: 'HS256' }
  );

  res.json({ assertion });
});

Step 3 — Initialise the widget

With the script loaded and your backend endpoint ready, initialise the widget on your frontend. Fetch the assertion from your backend first, then pass it to Fruga.init() along with your Partner Key.

// 1. Fetch the assertion from your own backend
const { assertion } = await fetch('/fruga/assertion')
  .then(res => res.json());

// 2. Initialise the Relay widget
Fruga.init({
  partnerKey: 'pk_test_xxxxxxxxxxxx',  // your Partner Key
  assertion,                            // the JWT from your backend
  mountTo: '#fruga-relay',            // the container element on your page
});

If the assertion is valid and the Partner Key is recognised, the widget will mount inside your container and your user will be authenticated automatically.

Verifying it works

Open your browser’s developer tools and check the Network tab. You should see two requests after the widget initialises:

If you see a 401 on the token exchange, the most common causes are an expired assertion (check that your server clock is accurate and that exp is set correctly), a mismatched iss or aud claim, or an incorrect Signing Secret.

Next steps

With the widget running, the next thing to set up is cashback claims — the server-to-server call that tells Fruga when a user is entitled to a payout. Head to the Authentication guide to go deeper on how the token flow works, or jump straight to Partner API → Cashback Claim if you’re ready to set up payouts.