@atharly/web-sdk

The Atharly Web SDK — TypeScript NPM package for silent click-time fingerprinting and an in-app browser interstitial flow. Powers the web-side of the Atharly KSA-hosted attribution platform. Ships as ESM, CJS, and UMD bundles with full TypeScript declarations and zero runtime dependencies.

Install

npm install @atharly/web-sdk

Or via CDN (UMD bundle):

<script src="https://cdn.atharly.com/[email protected]/index.umd.js"></script>
<script>
  window.atharly.init({ apiKey: "at_pk_<tenant>_<key>_<secret>" });
</script>

Usage

import { atharly } from "@atharly/web-sdk";

atharly.init({
  apiKey: "at_pk_<tenant>_<key>_<secret>",
  // Optional — defaults to https://ingest.atharly.com.
  // Override for local dev or non-prod environments.
  apiUrl: "https://ingest.atharly.com",
});

// On a CTA click that points at a smart link:
await atharly.captureClick("click_abc123");

// On the in-app-browser interstitial landing page (e.g. when a link
// opens inside Instagram / TikTok webview):
atharly.detectAndRenderInterstitial();

What it does

1. Click-time fingerprint — collects a stable browser fingerprint (audio, canvas, WebGL caps, fonts, codecs, CPU/GPU bench) and POSTs it to /v1/click/signals so the server-side matcher can wire the eventual install back to this click.
2. In-app browser interstitial — when a link opens inside a webview that won't honour Universal Links / App Links (Instagram, TikTok, Snapchat), the SDK shows an "Open in Safari/Chrome" page that breaks out to the device's real browser, where the OS can hand off to the native app.

Layout

• src/index.ts — public surface (atharly.init, .captureClick, .detectAndRenderInterstitial).
• src/core/ — fingerprint collectors, interstitial renderer, transport.
• tests/ — vitest suite.
• vite.config.ts — multi-format library build.

Development

npm install
npm run build        # → dist/index.js, dist/index.mjs, dist/index.d.ts (+ UMD)
npm test             # vitest
npm run type-check   # tsc --noEmit (strict mode)
npm run lint         # ESLint
npm pack             # dry-run; inspect the tarball before publishing

prepublishOnly runs type-check + test + build automatically before npm publish so a broken build can't ship.

Publishing

npm login                 # only the first time
npm publish --access public

publishConfig.access = "public" is set in package.json so the scoped @atharly package goes out as public. First publish:

npm pack && tar -tf atharly-web-sdk-0.1.0.tgz   # confirm contents
npm publish

Bump version with npm version patch | minor | major before the next publish — npm refuses to overwrite an existing version.

Status

Early. The CPU bench runs synchronously on the main thread for ~50 ms; profile against a real low-end Android device before relying on the spec's entropy figure for a launch decision. The CDN distribution path (cdn.atharly.com/web-sdk@<version>.umd.js) is wired in production for current customers; the npm registry publish above is the new general-availability channel.

License

MIT. See LICENSE.