Skip to content
LFLocusVia

Documentation

SDK Overview

Configure the LocusVia SDK with three values. The backend handles everything else.

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
};
ParameterTypeRequiredDescription
appIDstringYesThe SDK App ID. Maps to one App Platform internally.
apiKeystringYesPublic SDK credential. Authenticates tenant and authorizes SDK App IDs.
baseUrlstringNoOrigin for SDK API calls and public link routes. Defaults to your link domain.
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

On React Native, the provider performs initial URL checks, deferred lookup, runtime link listening, short-link resolution, and analytics forwarding on mount. Android checks App Links, scheme links, deferred links, and resolves single-segment short links. iOS checks launch URL, Universal Link, then deferred link from API.

Backend routing inference

The backend resolves identity in this order:

  1. apiKey — authenticates tenant and environment
  2. appID — resolves SDK App ID to App Platform
  3. Request host — resolves domain and environment
  4. 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.

Compatibility modes

LocusVia supports response adapters per SDK App ID:

text
sdk_compatibility_mode:
  - detour_v1       # Detour v1 response shape
  - detour_v2       # Detour v2 response shape
  - locusvia_native # LocusVia native response

SDK request headers influence adapter selection:

text
X-LocusVia-SDK: react-native
X-LocusVia-SDK-Version: 1.0.1
X-Compatibility-Mode: detour_v1

Enterprise extensions

Optional config for multi-environment deployments:

typescript
type LocusViaEnterpriseConfig = LocusViaConfig & {
  environment?: "dev" | "sit" | "uat" | "prod";
  domainHint?: string;
};
linkProcessingMode is SDK-side behavior only. Server authorization comes from SDK API Key scopes and App Platform settings, not client config.