Scanly SDK API reference

This reference describes the supported exports of @scanly/sdk. Import lead-form domain contracts such as LeadFormDefinition, LeadFormValues, and LeadFormSubmissionReceipt from @scanly/public; the SDK does not re-export them.

Public contracts and functions

@scanly/public is the SDK-safe package for both public types and platform-neutral functions. Its exports are organized as follows:

Client and shared runtime

Import from @scanly/sdk.

Functions and classes

ScanlyClient

The client has no public constructor; create it with createScanlyClient.

Client types

Push types

Transport types

Themes for React

Import from @scanly/sdk/theme/react. React is an optional peer dependency.

The wrapper only affects descendants:

import { ThemeWrapper } from '@scanly/sdk/theme/react';
 
const theme = await client.themes.getById(themeId);
 
<ThemeWrapper theme={theme}>
  <YourContent />
</ThemeWrapper>;

Framework-independent lead forms

Import from @scanly/sdk/lead-forms.

Controller

For host-owned transport, controller.prepare({ idempotencyKey }) accepts a PrepareLeadFormAttemptInput. The same parameter object is used by useLeadForm(...).prepare(...).

Repository contracts

LeadFormsRepository methods:

Lead-form core

Import pure functions from @scanly/sdk/lead-forms/core. These functions do not render UI or perform network requests.

The core entry point also exports the parameter-object types named in the table above. Their property names match the corresponding function calls, so TypeScript autocomplete documents each argument at the call site.

LeadFormAuthoringDefinition, LeadFormAuthoringField, LeadFormAuthoringConsent, and LeadFormAuthoringListTarget are imported from @scanly/public. They describe platform-neutral authoring data, not Scanly’s private database/editor records. The compiler normalizes raw options, defaults, constraints, conditions, consent content, and list-target links; generates opaque local IDs and hashes; and validates the final contract. Its result also contains source-to-opaque list-target and consent maps for hosts that need to translate their own IDs.

LeadFormListTarget represents an audience list that may receive the submitted lead. listTargets contains the mandatory root list and any coupled lists. Optional targets are rendered as selectors; selecting one activates fields and consents whose appliesToListTargetIds contain its ID. The submitted selectedListTargetIds tell Scanly which audience-list memberships to create.

React Hook Form integration

Import from @scanly/sdk/lead-forms/react-hook-form. React, react-hook-form, and their runtime peers are optional dependencies required only by this entry point.

Hooks and helpers

Types

Managed web lead forms

Import from @scanly/sdk/lead-forms/web. React, React DOM, and React Hook Form are optional peers required by managed web forms.

Web renderer types

Import @scanly/sdk/lead-forms/styles.css once for the default stylesheet. Set unstyled when the host owns all classes and styles.

className applies to the renderer root; use classNames.form for the nested form element and the remaining LeadFormSlot keys for individual slots. Submit controls are disabled while the form is pristine by default. Set allowPristineSubmit to true when initial or default values may be submitted without a user change. Validation still runs before submission. styleTokens.spacing and styleTokens.borderRadius accept bounded numbers (CSS pixels) or 0, px, rem, and em values.

SdkLeadForm automatically creates the first-party Places provider for fields authored with autocomplete.provider: 'places'. The SDK target must include the places:read capability. WebLeadForm and custom renderers can receive the same provider explicitly:

const places = client.leadForms.createPlacesAutocompleteProvider({
  language: 'de',
});
 
<WebLeadForm definition={definition} autocompleteProviders={{ places }} />;

Resolving a suggestion returns provider-keyed values for value, formattedAddress, street, houseNumber, postalCode, city, state, country, and countryCode when supplied by Google. Authored targets determine which definition fields receive those values.

Framework-free web embed

Import or bundle from @scanly/sdk/lead-forms/web-embed.

update(options) accepts SafeLeadFormEmbedUpdate: locale and presentation changes that are safe after mounting. unmount() releases the React root.

Exported embed types are SafeLeadFormEmbedOptions, MountScanlyLeadFormOptions, SafeLeadFormEmbedUpdate, LeadFormClassNames, LeadFormRendererComponents, LeadFormWebStyleTokens, and LeadFormMessageCatalog.

The browser IIFE exposes window.ScanlyLeadForms.mountScanlyLeadForm and does not mount automatically. Non-bundler hosts must also load the version-matched lead-forms/styles.css asset once, or set unstyled and supply all presentation styles themselves.

React Native lead forms

Import from @scanly/sdk/lead-forms/react-native. React, React Native, and React Hook Form are optional peers required by this entry point.

Exported native types are SdkReactNativeLeadFormProps, ReactNativeLeadFormProps, ReactNativeLeadFormViewProps, and ReactNativeLeadFormRendererComponents, plus the native field, consent, list-target, and form-error component prop types.

Firebase push adapters

Firebase packages are optional peers. Configure only the platform used by the host application.

Browser

Import from @scanly/sdk/firebase/web.

Import registerScanlyBackgroundHandler from @scanly/sdk/firebase/web/service-worker. It accepts Firebase Messaging and a PushMessage listener, then returns a cleanup function that prevents future listener delivery.

React Native

Import from @scanly/sdk/firebase/react-native.

Testing helpers

Import from @scanly/sdk/testing. These helpers are intended for unit tests, not production code.