Integrate ExtMonetize in 5 minutes

#Installation

The SDK is a TypeScript client with zero runtime dependencies, shipping ESM, CommonJS and type declarations. It works in Chrome and Chromium browsers on Manifest V3, in a service worker or a page, as well as in Firefox.

npm install @extmonetize/ciiti

#Quick start

1. Sign up, then in Extensions, create your extension and at least one plan (monthly or yearly subscription, or a one-off payment).
2. On your extension’s Keys tab, grab the publishable key (pk_pub_…) and the verification public key — its own signing pair if it has promoted one, the platform pair otherwise. Neither is a secret: both ship in your bundle.
3. Instantiate the SDK in your service worker.

import { Ciiti } from '@extmonetize/ciiti';
import { EXTMONETIZE_PUBLIC_KEY } from './extmonetize-key.js';

const ciiti = Ciiti.create({
  apiKey: 'pk_pub_xyz789',
  publicKey: EXTMONETIZE_PUBLIC_KEY,
});

// Once at startup: registers the device.
await ciiti.init();

const status = await ciiti.getPremiumStatus();
if (!status.isPremium) {
  await ciiti.openCheckout({ planId: 'plan_pro' });
}

#Offline verification (recommended)

Premium status is delivered as an RS256-signed token. For the SDK to verify that signature locally, pin the public key in your bundle via publicKey. It is then read from your store-signed bundle and never from writable storage: an attacker cannot slip in their own key to self-sign a fake token.

A cached token is answered offline only while its signature verifies against the pinned key, it was minted for this extension and this device, it has not expired, and it is less than four hours old — so a subscription cancelled mid-period cannot stay premium offline until the period ends.

// src/extmonetize-key.ts — embedded at build time
export const EXTMONETIZE_PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA1f8s...QIDAQAB
-----END PUBLIC KEY-----`;

import { Ciiti } from '@extmonetize/ciiti';
import { EXTMONETIZE_PUBLIC_KEY } from './extmonetize-key.js';

export const ciiti = Ciiti.create({
  apiKey: 'pk_pub_xyz789',
  publicKey: EXTMONETIZE_PUBLIC_KEY, // ← enables offline verification
});

const status = await ciiti.getPremiumStatus();
console.log(status.isPremium, status.features);

#Gating a feature

canUse() reads the entitlements carried by the token — no need to hit the network on every click.

if (await ciiti.canUse('ai_gen')) {
  runAiGeneration();
} else {
  await ciiti.openCheckout({ planId: 'plan_pro' });
}

The name comes from your dashboard: declare it under Features on the extension, then tick it on the plans that unlock it. A name that is not declared can never be granted, which is what stops a typo from silently returning false forever.

#Opening the paywall

openCheckout() opens Stripe checkout in a tab. You write no payment form and never touch card data.

await ciiti.openCheckout({
  planId: 'plan_pro',                     // required — the plan to check out
  email: 'user@mail.com',                 // pre-fills the checkout email
  successUrl: 'https://myapp.dev/thanks', // optional — origin must be allowed
  onSuccess: (status) => console.log('Premium!', status),
  onCancel:  () => console.log('closed without paying'),
  onError:   (err) => console.error(err),
});

Once a checkout has completed, openManagePage() opens the Stripe-hosted billing portal: payment method, invoices, cancellation. Wire it to a “Manage subscription” button shown when isPremium is true.

await ciiti.openManagePage({
  returnUrl: 'https://myapp.dev/settings',
  onError: (err) => console.error(err),
});

#API reference

#Security note