Encore Web SDK

A JavaScript/TypeScript SDK that enables web applications to display targeted offers to users, granting them provisional access to premium features when they complete advertiser offers.

Features

• 🎯 Targeted Offer Presentation - Display offers at critical moments (cancellation flows, paywalls, onboarding)
• 🔐 Entitlement Management - Two-tier system (provisional + verified) for instant UX and reliable billing
• 📱 Framework Agnostic - Works with React, Vue, Angular, Svelte, vanilla JavaScript, or any web framework
• 🎨 Responsive UI - Beautiful, accessible modal interface that works on desktop and mobile
• 📦 Lightweight - < 50KB gzipped bundle size
• 🔌 Offline Support - Queues signals and syncs when connectivity restored
• ♿ Accessible - WCAG 2.1 Level AA compliant

Installation

npm install @encorekit/web-sdk

Or via CDN:

<script src="https://encorekit.com/encore.min.js"></script>

Quick Start

import Encore from '@encorekit/web-sdk';

// Configure the SDK
Encore.configure({
  apiKey: 'your-api-key-here',
  environment: 'production'
});

// The SDK auto-generates and persists an anonymous user ID.
// Identify the user after login to attach your own ID (optional)
Encore.identify('user-123', {
  email: '[email protected]',
  subscriptionTier: 'free'
});

// Present an offer
const result = await Encore.presentOffer();
if (result.granted) {
  console.log('User granted entitlement:', result.entitlement);
  console.log('Offer granted:', result.entitlement);
  // Handle user completed Encore offer
} else {
  console.log('User declined:', result.reason);
}

// Check entitlement on YOUR server (not client-side)
// See: https://docs.encorekit.com/server-side-validation

Layout Templates

show() renders the default 'list' layout. For post-purchase surfaces (a payment success page), use the 'thankYou' layout — a complete success view: status check, your payment copy, the offer carousel, and an optional trust footer.

const placement = Encore.placement('post-purchase', {
  layout: 'thankYou',
  appearance: { accentColor: '#0A6' },
  header: { title: 'Payment Successful' },   // constants — plain strings
  offerContext: { title: 'A little thank you, just for you.' },
  footer: { text: '🔒 Secured by Acme' },
});

// Per transaction, pass the typed receipt — the SDK renders
// "You paid $9.99 for Pro Plan" under the header:
await placement.show({ receipt: { amount: '$9.99', purpose: 'Pro Plan' } });

Notes:

• header is the sheet's top heading block in EVERY layout — the modal title/subtitle in 'list' (a local override of the remote copy) and the payment-status block in 'thankYou'. One name, one meaning.
• receipt values are rendered verbatim as plain text (pre-format currency yourself), never sent to Encore servers, and override header.subtitle when provided.
• offerContext is 'thankYou'-only priming copy ABOVE the offers (why they're being shown), not any offer's own copy — 'list' ignores it. When the active offer's campaign carries a perk line (e.g. "Enjoy 30 days of Apple Music free") the perk takes the subtitle slot and follows the carousel as it pages; offerContext.subtitle is the static fallback.
• Need a custom confirmation line? Skip receipt and pass your own pre-built string as header.subtitle — placement options are per-call.
• Unknown layout values warn and fall back to 'list', so older SDK versions degrade gracefully when layout selection later moves to remote config.
• In 'thankYou' the carousel pages one card per view at every breakpoint, with round chevron navigation bubbles when there is more than one offer (hidden for a single offer).
• Pair with redemptionMode: 'immediate' for post-purchase: Claim opens the advertiser in a new tab within the tap gesture and show() resolves { status: 'claimed' } — the SDK renders nothing after a claim. The host owns that moment: render your own confirmation if you want one, keyed off the result. The result deliberately makes no claim about advertiser conversion (it is asynchronous and server-authoritative — verify entitlements/conversions server-side by user, never from the client). show() never rejects: failures resolve as { status: 'dismissed', reason }.

Browser Support

• Chrome/Edge (last 2 versions)
• Firefox (last 2 versions)
• Safari (last 2 versions)
• iOS Safari 15+

iOS HTML Tag Integration

The simplest possible integration - just build a URL and open it in a WKWebView. No SDK, no dependencies, no complexity.

Quick Start (3 Lines of Code!)

// 1. Build URL
let url = EncoreURL.build(apiKey: "your_key", userId: "user_123")!

// 2. Create WebView and load it
let webView = WKWebView(frame: view.bounds)
view.addSubview(webView)
webView.load(URLRequest(url: url))

// That's it! 🎉

Complete Example

import UIKit
import WebKit

// Copy EncoreURLBuilder.swift to your project (one file!)
func showEncoreOffer() {
    let url = EncoreURL.build(
        apiKey: "pk_live_...",
        userId: currentUser.id,
        attributes: [
            "email": currentUser.email,
            "subscriptionTier": currentUser.tier
        ]
    )!
    
    let webView = WKWebView(frame: view.bounds)
    webView.backgroundColor = .clear
    view.addSubview(webView)
    webView.load(URLRequest(url: url))
}

SwiftUI Version

import SwiftUI

struct MyView: View {
    var body: some View {
        EncoreWebView(
            apiKey: "pk_live_...",
            userId: currentUser.id
        )
    }
}

What You Get

• ✅ Zero dependencies - Just one Swift file
• ✅ 3 lines of code - Build URL, create WebView, load
• ✅ Auto-initialization - Embed handles everything
• ✅ Full features - Offers, entitlements, tracking
• ✅ Works everywhere - UIKit, SwiftUI, any iOS app

Documentation

• EncoreURLBuilder.swift - URL builder (copy this!)
• SimpleExample.swift - Working examples

Advanced: With Callbacks

Need callbacks when offers complete? Use the full bridge integration.

When to Use

| Feature | Simple (URL) | Native iOS SDK | |---------|-------------|------------| | Integration | 3 lines | ~50 lines | | Dependencies | None | Requires SPM | | Callbacks | No | Yes | | Works? | ✅ | ✅ |

Use simple integration for 99% of cases. Only need the full bridge if you require granular callbacks.

Documentation

• Full Documentation

Local Development

Develop, run, and validate the SDK locally — all through make:

npm install
make dev     # build + watch the SDK, open the harness at http://localhost:3000
make         # print all targets

See docs/runbooks/local-development.md for the full guide: framework examples (make dev FRAMEWORK=react), published-release validation (make published), environment switching, and troubleshooting.