Web SDK
TypeScript · Zero Dependencies · Shadow DOM
Overview
The Avafli Engagement SDK lets you add daily-entry sweepstakes and prize experiences to your site with a single configuration call. The SDK automatically opens the experience on the first visit 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
| Browser | Chrome 80+ / Firefox 78+ / Safari 14+ / Edge 80+ |
| Framework | None required (works with React, Vue, Svelte, vanilla JS) |
| Dependencies | Zero dependencies |
| Publisher API Key | Contact info@avafli.com |
Installation
Two ways to integrate — pick the one that matches how your site is built. Both are complete: one configure call and the SDK handles everything else.
Option 1 — Any website (Webflow, Squarespace, plain HTML)
No build tools, no npm. Paste this before your closing </body> tag (in Webflow: Site Settings → Custom Code → Footer Code) — this is the entire integration:
<script src="https://sdk.avafli.com/avafli-sdk.umd.js"></script>
<script>
Avafli.configure({
apiKey: 'YOUR_API_KEY', // debug? use your avafli_test_ key
bundleId: 'yourdomain.com', // your site's domain (note below)
// Only id is required — no email on file? Leave it off;
// the SDK captures it on its submit screen. Have their
// email? add email: 'jane@example.com' to pre-fill &
// lock the field. Nobody signed in? omit `user`
// entirely — the SDK runs a stable guest session.
user: { id: 'user_123', firstName: 'Jane', lastName: 'Doe' },
});
// Done — the experience auto-opens once per day. No further calls needed.
</script>bundleId on the web = your site's domain (e.g. yourdomain.com) — not a reverse-DNS app id. Add that domain under Bundle IDs in your publisher dashboard first; your API key is validated against it and configure will fail until it's listed.
Prefer to self-host the file? Build it with npm run build and serve dist/avafli-sdk.umd.jsfrom your own static hosting — it's fully self-contained (fonts and imagery embedded), with zero runtime dependencies.
Option 2 — Bundlers (npm / yarn / pnpm)
Building with Vite, webpack, Next.js, or any other bundler? Install the package:
npm install avafli-sdk@^3.1.10Then one call at app launch is the entire integration:
import { Avafli } from 'avafli-sdk';
await Avafli.configure({
apiKey: 'YOUR_API_KEY', // debug builds: use your avafli_test_ sandbox key
bundleId: 'yourdomain.com', // your site's domain
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
options: { debug: false }, // debug: true while integrating
});
// Done — the experience auto-opens once per day.
The experience opens itself on the first visit of each day — there is no manual launch API. Presentation timing, the daily cadence, and dismissal are fully managed by the SDK.
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 — a plain object with track and identify, passed in options.analyticsAdapter. Script-tag integration:
<script src="https://sdk.avafli.com/avafli-sdk.umd.js"></script>
<script>
Avafli.configure({
apiKey: 'YOUR_API_KEY',
bundleId: 'yourdomain.com', // web bundleId = your site's domain
user: { id: 'user_123', firstName: 'Jane', lastName: 'Doe' },
options: {
// Plain object literal — no build tools needed
analyticsAdapter: {
track: function (event, properties) {
// Forward to Segment, Amplitude, etc.
segment.track(event, properties);
},
identify: function (userId, traits) {
segment.identify(userId, traits);
},
},
},
});
</script>Same adapter with npm / a bundler:
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: 'yourdomain.com', // web bundleId = your site's domain
user: { id: 'user_123', firstName: 'Jane', lastName: 'Doe' },
options: { analyticsAdapter: analytics },
});Account deletion in your app
If your app has its own delete-account flow, call optOut() from it so the user's Avafli data is erased along with their account. Users can also delete their data themselves at any time from the Privacy Policy screen inside the experience — no integration required.
// From your delete-account flow
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
Full API Reference & Code Examples
View the complete documentation on GitHub including API reference, code examples, and advanced configuration.