๐ŸŒ

Web SDK

TypeScript ยท Zero Dependencies ยท Shadow DOM

Overview

WINR lets you add daily-entry sweepstakes and prize experiences to your app with a single configuration call. The SDK automatically opens the experience on the first app-open of each day, captures the user, and claims their daily entries โ€” no scheduling or session logic on your side. You customize your logo, prize image, and brand color from the WINR dashboard; everything else is managed server-side.

Requirements

BrowserChrome 80+ / Firefox 78+ / Safari 14+ / Edge 80+
FrameworkNone required (works with React, Vue, Svelte, vanilla JS)
DependenciesZero dependencies
Publisher API KeyContact info@avafli.com

Installation

npm / yarn / pnpm

npm install winr-web-sdk@^2.9.0

Script tag (self-hosted UMD)

Alternatively, build the bundle (`npm run build`) and serve `dist/winr-sdk.umd.js` from your own static hosting โ€” the file is fully self-contained (fonts and imagery embedded), with zero runtime dependencies.

<script src="/assets/winr-sdk.umd.js"></script>

Quick Start

One call at app launch is the entire integration:

ES Modules

main.js
import { WINR } from 'winr-web-sdk';

await WINR.configure({
  apiKey: 'YOUR_API_KEY', // debug builds: use your winr_test_ sandbox key
  bundleId: 'com.example.myapp',
  user: {
    id: 'user_123',            // only id is required โ€” pass whatever identity you have
    firstName: 'Jane',
    lastName: 'Doe',
    email: 'jane@example.com', // include it when you have it โ€” pre-fills & locks the capture form
  },
  // Nobody signed in? omit `user` entirely โ€” the SDK runs a stable guest session
  debug: false, // true while integrating
});

// Done โ€” the experience auto-opens once per day.

The experience opens itself on the first app-open of each day โ€” there is no manual launch API. Presentation timing, the daily cadence, and dismissal are fully managed by the SDK.

CDN (UMD)

<script src="/assets/winr-sdk.umd.js"></script>
<script>
  (async function () {
    await WINR.configure({
      apiKey: 'YOUR_API_KEY',
      bundleId: 'com.example.myapp',
      // Only id is required โ€” no email on file? Leave it off; the SDK captures it on its submit screen.
      // Already have their email? add email: 'jane@example.com' to pre-fill & lock the field. No user? omit `user` entirely.
      user: { id: 'user_123', firstName: 'Jane', lastName: 'Doe' },
    });
    // Done โ€” the experience auto-opens once per day. No further calls needed.
  })();
</script>

Customization

Publisher customization is managed server-side through the WINR Dashboard:

  • Your Logo โ€” Displayed throughout the experience
  • Prize Image โ€” The hero image for the active giveaway
  • Brand Color โ€” Your primary color, applied across the UI

Everything else is designed and managed by WINR. Changes apply instantly across all web applications without requiring a deployment.

Analytics

Connect your analytics system with a simple adapter interface:

import { WINR, AnalyticsAdapter } from 'winr-web-sdk';

const analytics: AnalyticsAdapter = {
  track(event, properties) { 
    // Forward to Segment, Amplitude, etc.
    segment.track(event, properties); 
  },
  identify(userId, traits) { 
    segment.identify(userId, traits); 
  },
};

await WINR.configure({
  apiKey: 'YOUR_API_KEY',
  bundleId: 'com.example.myapp',
  user: { id: 'user_123', firstName: 'Jane', lastName: 'Doe' },
  options: { analyticsAdapter: analytics },
});

GDPR Compliance

Handle erasure requests with a single method call. It removes the person's personal information everywhere it is held, covers all their devices, and keeps the experience silenced through a reinstall:

// Erase the user's personal data (Right-to-be-Forgotten)
await WINR.optOut();

Testing? Your dashboard also shows a winr_test_ sandbox key. Use it in debug builds: identical behavior against the production backend, but users and entries land in an isolated sandbox โ€” your testers can never enter your real giveaway, and sandbox usage never counts toward MAU.

SDK Features

Escalating Streak Ladder with Milestone Accelerators
Daily or Visit-Based Streak Modes
Winner Announcements & Celebrations
Auto-Open on First Daily App-Open
Email Capture & Age Gate (18+)
Server-Driven Configuration
GDPR Compliance
Shadow DOM UI (isolated styles)
Zero Dependencies
TypeScript Support
ESM + UMD Bundles
Framework Agnostic
Modal & Inline Presentation
Custom Logo, Prize Image & Brand Color

Full API Reference & Code Examples

View the complete documentation on GitHub including API reference, code examples, and advanced configuration.