@swipefindercom/finder-sdk

Embed interactive swipeable card feeds on any website or React app.

Installation

npm install @swipefindercom/finder-sdk

Usage

Vanilla JS / Any framework (SDK)

The SDK build bundles everything (including React) so it works anywhere — plain HTML, Vue, Angular, etc.

<div id="swipefinder"></div>

<script type="module">
  import { initSwipeFinder } from '@swipefindercom/finder-sdk';

  const cleanup = initSwipeFinder({
    backendUrl: 'https://api.swipefinder.com',
    finderId: 'your-finder-id',
    element: document.getElementById('swipefinder'),
  });

  // Call cleanup() to unmount
</script>

UMD (script tag)

<div id="swipefinder"></div>

<script src="https://unpkg.com/@swipefindercom/finder-sdk"></script>
<script>
  const cleanup = SwipeFinderSDK.initSwipeFinder({
    backendUrl: 'https://api.swipefinder.com',
    finderId: 'your-finder-id',
    element: document.getElementById('swipefinder'),
  });
</script>

Floating launcher (modal over the publisher page)

Instead of embedding the widget in a container, you can show a floating round button in the bottom-right corner of the page. Clicking it opens SwipeFinder in a modal layer above the page — 300×600 centered on desktop, fullscreen on mobile — with a blurred backdrop. Clicking the backdrop or pressing Esc closes it. The launcher UI is rendered in a Shadow DOM, so it doesn't clash with the publisher page CSS.

Drop-in snippet (e.g. via Google Tag Manager or the dev console):

<script>
  window.SwipeFinderConfig = { finderId: 'your-finder-id' };

  (function (d, id) {
    if (d.getElementById(id)) return;
    var s = d.createElement('script');
    s.id = id;
    s.async = true;
    s.src = 'https://unpkg.com/@swipefindercom/finder-sdk/dist/sdk.js';
    d.head.appendChild(s);
  })(document, 'swipefinder-sdk');
</script>

The loader exposes a handle on window.SwipeFinderLauncher with open(), close(), isOpen() and destroy().

Alternatively, initialize programmatically from the ESM/UMD build:

import { initSwipeFinderLauncher } from '@swipefindercom/finder-sdk';

const launcher = initSwipeFinderLauncher({
  backendUrl: 'https://api.swipefinder.com',
  finderId: 'your-finder-id',
});

API

initSwipeFinder(options)

| Option | Type | Required | Description | | ------------ | ------------- | -------- | ---------------------------------- | | backendUrl | string | ✅ | Backend API URL | | finderId | string | ✅ | Finder identifier | | element | HTMLElement | ✅ | DOM element to mount into |

Returns a () => void cleanup function that unmounts the widget.

initSwipeFinderLauncher(options)

| Option | Type | Required | Description | | ---------------- | --------- | -------- | -------------------------------------------------------- | | backendUrl | string | ✅ | Backend API URL | | finderId | string | ✅ | Finder identifier | | buttonColor | string | — | Accent color of the floating button | | zIndex | number | — | Stacking context of the launcher (default 2147483000) | | destroyOnClose | boolean | — | Unmount the widget on close (default false) | | autoOpen | boolean | — | Open the modal right after init (default false) |

Plus all remaining initSwipeFinder config options (except element). Returns a launcher handle: { open, close, isOpen, destroy }.

When loaded via the sdk.js snippet, options are read from window.SwipeFinderConfig (with backendUrl defaulting to the production API).

Builds

| Entry | Format | React bundled? | Use case | | ----------------------- | --------- | -------------- | ------------------------------- | | @swipefindercom/finder-sdk | ESM / UMD | ✅ Yes | Vanilla JS, Vue, Angular, etc. | | dist/sdk.js (launcher loader) | IIFE | ✅ Yes | GTM snippet / floating button |

Development

npm run dev            # Dev server on :3010
npm run storybook      # Storybook on :6006
npm run build:all      # Build SDK + types
npm run test:e2e       # Playwright E2E tests

License

MIT © SwipeFinder