Web SDK

TypeScript · Zero Dependencies · Shadow DOM

Overview

The Avafli Engagement SDK 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 Avafli 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 avafli-sdk@^3.0.0

Script tag (self-hosted UMD)

Alternatively, build the bundle with npm run build and serve dist/avafli-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/avafli-sdk.umd.js"></script>

Quick Start

One call at app launch is the entire integration:

ES Modules

main.js
import { Avafli } from 'avafli-sdk';

await Avafli.configure({
  apiKey: 'YOUR_API_KEY', // debug builds: use your avafli_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/avafli-sdk.umd.js"></script>
<script>
  (async function () {
    await Avafli.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 Avafli 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 Avafli. Changes apply instantly across all web applications without requiring a deployment.

Analytics

Connect your analytics system with a simple adapter interface:

import { Avafli, AnalyticsAdapter } from 'avafli-sdk';

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

await Avafli.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 Avafli.optOut();

Testing? Your dashboard also shows a avafli_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.

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.