Skip to content
LocusVia

LocusVia

Technical documentation

Quickstart

Go from a managed subdomain to a production-ready mobile route in about 15 minutes of hands-on work — plus a signed-device test. Custom domains add DNS propagation time.

Prerequisites#

You need three things before creating your first link:

  • A LocusVia-managed subdomain like acme.locusvia.com (all plans), or a custom domain pointed at LocusVia (Enterprise plan)
  • An app record with at least one platform (iOS or Android)
  • An SDK API key scoped to the target environment

Note

Use separate keys and app identities for staging and production. Environment isolation is enforced server-side.

Warning

Measured timing: steps 1–6 below take about 10–12 minutes; wiring the SDK and verifying on a signed device take about 5–8 more. Most teams reach a verified link journey in under 30 minutes — the device test is the long pole, not the setup.

Step-by-step#

This order matches the Getting started checklist on your dashboard Overview.

  1. 1

    Connect your domain (~2 min)

    In the control plane, navigate to Domains and add your hostname. LocusVia will provision TLS and begin serving association files immediately. For managed subdomains, DNS is handled automatically.

  2. 2

    Register your app (~3 min)

    Add an App, then attach platform identities:

    • iOS: Team ID + Bundle ID
    • Android: Package name + SHA-256 signing fingerprint
  3. 3

    Publish app associations (~1 min)

    Attach your platform identities to the domain. LocusVia generates the Apple App Site Association and Android Asset Links files and serves them at the well-known paths.

  4. 4

    Configure fallbacks (~2 min)

    Create a fallback policy with web, App Store, and Play Store destinations so users without the app always land somewhere useful.

  5. 5

    Create a link (~3 min)

    The link API runs on the control-plane host of your environment (https://locusvia.com for production, https://staging.locusvia.com for staging) — not on your link domain. The call authenticates with the admin session cookie, or with an Admin API key in the Authorization header. Tenant and environment are taken from your membership (or scope the call with x-tenant-slug and x-environment-key headers):

    bash
    export LOCUSVIA_ADMIN_API_KEY="lv_admin_live_..."

    Then create your first link (grab domainId from the Domains page):

    bash
    curl -X POST https://locusvia.com/api/v1/admin/links \
  -H "Authorization: Bearer $LOCUSVIA_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domainId": "<domain-id>",
    "slug": "summer",
    "url": "https://yourapp.com/summer",
    "mobileBehavior": "app_preferred",
    "mobileFallback": "install_page",
    "desktopBehavior": "web_redirect"
  }'

    Platform-specific route targets (the deep routes opened inside your app) are added to the link from the Links view after creation.

  6. 6

    Issue an SDK key (~3 min)

    Create an SDK API key under SDK Access. Assign scopes for the actions your app needs (resolve, analytics). The key is shown once — store it securely.

    Test SDK key

    Live probe: POST /api/v1/sdk/short-link/resolve

    Sends one resolve probe with the key. No real link needed — auth runs before link lookup.

    The check probes POST /api/v1/sdk/short-link/resolve exactly as the SDK will. A failed check explains the cause (invalid key, wrong environment, missing scope, or wrong host) and the next action.

  7. 7

    Resolve from the SDK (Golden Paths, ~5 min)

    Copy-ready golden paths for React Native, iOS Swift, and Android Kotlin live in sdk/samples/.

    Install the SDK, then wrap your app:

    bash
    npm install @locusvia/react-native-sdk
# optional peer used by the provider:
npm install @react-native-async-storage/async-storage
    typescript
    import { LocusViaProvider, useLocusVia } from "@locusvia/react-native-sdk";

export default function App() {
  return (
    <LocusViaProvider config={{ appID: "lf_ios_native", apiKey: "pk_live_xxx", baseUrl: "https://staging.locusvia.com" }}>
      <MainScreen />
    </LocusViaProvider>
  );
}

    baseUrl is your control-plane API origin — the SDK posts to {baseUrl}/api/v1/sdk/*. Your link domain only serves links; it rejects SDK POST calls.

Verify on device#

Warning

Association files prove configuration. Always finish with a signed-device Universal Link and App Link test before shipping to production.

On iOS, verify the Associated Domains entitlement matches your domain. On Android, run adb shell pm verify-app-links --re-verify com.yourapp and confirm the verified state.

If verification fails, run the domain diagnostics check to compare your configured app platforms against the live association files.

Was this page helpful?

PreviousOverviewNextConcepts