Choose an SDK

Start with the application shell that receives the operating-system or browser URL.

Match the SDK to your application shell#

Integrate LocusVia once at the layer that owns URL delivery and navigation. Do not install two SDKs in the same shell to compensate for missing native association setup.

React NativeBare React Native with one root provider.Published on npm Expo RouterExpo Router native-intent navigation.Published npm subpath iOSSwift application owns Universal Links.Source ready AndroidKotlin application owns App Links.Source ready WebBrowser or SPA owns the received URL.Source ready Capacitor & IonicHybrid shell owns cold and runtime URLs.Source ready UnityUnity player owns routing and outcomes.Source only Kotlin MultiplatformShared Kotlin owns the network client.Source only

Warning

Published means a consumer install was verified from a public registry. Source ready and source only require a reviewed checkout and do not imply registry availability.

Configuration#

The SDK requires only three config values:

typescript

type LocusViaConfig = {
  appID: string;      // Maps to one App Platform
  apiKey: string;     // Authenticates your tenant
  baseUrl?: string;   // Your link domain origin
};

Parameter	Type	Required	Description
appID	string	Yes	The SDK App ID. Maps to one App Platform internally.
apiKey	string	Yes	Public SDK credential. Authenticates tenant and authorizes SDK App IDs.
baseUrl	string	No	Origin for SDK API calls and public link routes. Defaults to your link domain.

Note

The SDK-facing appID is the SDK App ID. LocusVia maps it to one App Platform. Multiple SDK App IDs can roll up to the same App through their App Platforms.

SDK lifecycle#

text

App launches
  -> SDK checks initial URL
  -> if no initial URL, SDK queries backend for deferred link
  -> SDK listens for runtime Universal/App Links
  -> SDK resolves short links when needed
  -> SDK sends analytics events

Platform behavior at launch:

On React Native, the provider performs initial URL checks, deferred lookup, runtime link listening, short-link resolution, and analytics forwarding on mount.

Backend routing inference#

The backend resolves identity in this order:

apiKey — authenticates tenant and environment
appID — resolves SDK App ID to App Platform
Request host — resolves domain and environment
Custom domain mapping — confirms tenant ownership

All three must agree: baseUrl host, apiKey environment, and appID environment. Mismatches return a generic auth response without leaking cross-environment details.

Enterprise extensions#

Optional config for multi-environment deployments:

typescript

type LocusViaEnterpriseConfig = LocusViaConfig & {
  environment?: "dev" | "sit" | "uat" | "prod";
  domainHint?: string;
};

Note

linkProcessingMode is SDK-side behavior only. Server authorization comes from SDK API Key scopes and App Platform settings, not client config.