@authologic/omni-websdk
v0.25.0
Published
Identity verification widget by Authologic. Framework-agnostic web component, one function to start.
Readme
OmniID
Identity verification widget by Authologic. Framework-agnostic web component, one function to start.
Install
# npm
npm install @authologic/omni-websdk
# yarn
yarn add @authologic/omni-websdk
# pnpm
pnpm add @authologic/omni-websdk
# bun
bun add @authologic/omni-websdkThe package is ESM-only (import); there is no require() entry point. For
direct <script> use without a bundler, load dist/omni-websdk.umd.js from
the installed package (or a CDN mirror of it) with a global Vue already on
the page — this file is shipped but intentionally not resolvable via
require()/exports.
Quick start
<div id="authologic"></div>import { init } from "@authologic/omni-websdk"
init({
widgetId: "your-widget-id",
conversationId: "conversation-id-from-your-backend",
environment: "sandbox",
})The widget mounts into #authologic and opens in a modal. Use widgetId: "development_only" in sandbox. Switch to production (the default) when you go live.
Lifecycle
import { init, show, hide } from "@authologic/omni-websdk"
init({ widgetId, conversationId, autostart: false })
document.getElementById("verify").onclick = showinit(config)— stores config and registers<omni-websdk>. Mounts whenautostartistrue(default) or the URL carries?resumeAuth=1.Known limitation: calling
init()again with a different config does not currently tear down a previously mounted widget or refresh already-initialized language/translations. If you need to start a new process with different config,hide()the current widget first, and avoid changingtranslations/language acrossinit()calls within the same page session.show()— mounts the widget. No-op if already shown.hide()— unmounts the widget. No-op if not shown.
After onClose fires, the widget hides itself 500 ms later.
Options
| Option | Type | Default | Description |
| --------------------- | --------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------- |
| widgetId | string | — | Required. |
| conversationId | string | — | Required. Created by your backend via the Authologic API. |
| environment | "production" \| "sandbox" \| string | "production" | Target environment or a custom base URL. |
| divId | string | "authologic" | Id of the container element. |
| layout | "modal" \| "inline" | "modal" | Overlay drawer or inline in the container. |
| dismissable | boolean | true | Allow dismissing the modal (X, Escape, backdrop). Ignored for inline. |
| showCompletedScreen | boolean | true | Show the final "completed" screen. When false, the final redirect runs immediately. |
| showRedirectScreen | boolean | true | Show the screen before redirecting to an external step. When false, the redirect runs immediately. |
| autostart | boolean | true | Mount on init(). |
| theme | "system" \| "ios" \| "android" \| "desktop" | "system" | Visual preset. system detects the platform. |
| colorScheme | "system" \| "light" \| "dark" | "system" | Follows prefers-color-scheme when system. |
| animations | boolean | true | Transitions. Always respects prefers-reduced-motion. |
| language | Language (see below) | browser | Forced UI language. Falls back to en when unsupported. |
| hooks | WidgetHooks | {} | See below. |
| debug | boolean | false | Verbose [Authologic] console logs. |
Supported languages: be, bg, cs, da, de, el, en, es, et, fr, ga, hi, hu, id, is, it, lt, lv, nl, no, pl, pt, ro, ru, sk, sr, sv, tr, uk, zh.
Hooks
init({
widgetId,
conversationId,
hooks: {
onInit: () => {},
onNavigation: ({ name, step }) => {},
onError: (error) => {},
onClose: (reason) => {},
onOpenUrl: ({ url, type, reason }) => ({ handled: false }),
},
})| Hook | Payload | When |
| -------------- | ------------------------------------------- | ---------------------------------------------------------------- |
| onInit | — | Widget mounted. |
| onNavigation | { name, step? } | Screen changed. |
| onError | Error | Unhandled error inside the widget. |
| onClose | "completed" \| "suspended" \| "cancelled" | Process ended. Confirm the result on your backend. |
| onOpenUrl | { url, type, reason } → { handled } | Before navigating away. Return { handled: true } to take over. |
CloseReason—completedwhen the process finished,suspendedwhen the user dismissed the modal,cancelledreserved.OpenUrlType—redirectreplaces the current page,opentargets a new tab.OpenUrlReason—completedfor the final redirect,external_actionfor intermediate hops such as bank login or OAuth.
onClose("completed") fires once, after the final redirect flow has run: when the user presses "Continue" on the completed screen, or immediately when showCompletedScreen is false. It fires even if onOpenUrl returned { handled: true }, so you can skip the final redirect and close the widget yourself:
init({
widgetId,
conversationId,
showCompletedScreen: false,
hooks: {
onOpenUrl: ({ reason }) => ({ handled: reason === "completed" }),
onClose: (reason) => {
if (reason === "completed") {
// show your own completion UI; the widget hides itself 500 ms later
}
},
},
})Hooks are isolated. A throwing hook is logged and never interrupts the flow.
Native webview
hooks: {
onOpenUrl: ({ url }) => {
window.NativeApp?.openUrl(url)
return { handled: true }
},
}Resume after redirect
External methods may leave your page. On return, the URL carries ?resumeAuth=1 and init() mounts the widget regardless of autostart. Call init() with the same conversationId on the return page. Nothing else is needed.
Appearance
init({ widgetId, conversationId, theme: "ios", colorScheme: "dark" })| theme | Feel |
| --------- | ------------------------------------------ |
| system | Detects the platform from the user agent. |
| ios | Human Interface Guidelines. Safari counts. |
| android | Material 3. |
| desktop | Quiet, neutral. |
The widget renders in a Shadow DOM. Page styles never leak in or out.
Errors
show() throws an Error with a code property, one of:
CONFIG_NOT_SET—init()has not been called.INIT_REQUIRED— config has nowidgetId.ELEMENT_NOT_FOUND— no element with iddivId.
The code values above are the stable, public contract; the error class itself is not currently exported from the package, so check the error by its code property rather than an instanceof check.
Pass debug: true for verbose [Authologic] logs.
TypeScript
import type {
WidgetConfig,
WidgetHooks,
WidgetLayout,
CloseReason,
NavigationEvent,
OpenUrlParams,
OpenUrlType,
OpenUrlReason,
HandlerResponse,
ThemePreset,
ColorScheme,
} from "@authologic/omni-websdk"Full example
<button id="verify">Verify identity</button>
<div id="authologic"></div>
<script type="module">
import { init, show } from "@authologic/omni-websdk"
const { conversationId } = await fetch("/api/conversation").then((r) => r.json())
init({
widgetId: "your-widget-id",
conversationId,
environment: "sandbox",
autostart: false,
hooks: {
onClose: (reason) => reason === "completed" && location.assign("/done"),
onError: console.error,
},
})
document.getElementById("verify").onclick = show
</script>Backend
Conversations, webhooks and results live server-side. See developer.authologic.com.
Any option, method, or behavior not described in this document is not officially supported. Treat it as unavailable — it may be removed or change without notice at any time.
