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
| 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
npm / yarn / pnpm
npm install avafli-sdk@^3.0.0Script 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
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
Full API Reference & Code Examples
View the complete documentation on GitHub including API reference, code examples, and advanced configuration.