LinkIO Backend

Self-hosted deep linking backend for mobile apps. Open-source alternative to Branch.io.

🚀 Quick Start

npm install linkio-backend

import express from "express";
import { LinkIO, InMemoryStorage } from "linkio-backend";

const app = express();

const linkIO = new LinkIO({
  domain: "yourdomain.com",
  iosAppId: "123456789",
  iosTeamId: "TEAMID123",
  iosBundleId: "com.yourapp.ios",
  iosAppScheme: "myapp", // For smart redirect (myapp://)
  androidPackageName: "com.yourapp.android",
  androidAppScheme: "myapp", // For smart redirect (myapp://)
  androidSHA256Fingerprints: ["YOUR_SHA256_FINGERPRINT"],
  fallbackTimeout: 2500, // Wait before redirecting to store
  storage: new InMemoryStorage(),
});

// Domain verification endpoints
app.get("/.well-known/*", linkIO.setupWellKnown());

// Generic deep link handler
app.get("/link", linkIO.handleDeepLink());

// API endpoints - Deferred deep linking
app.get("/pending-link/:deviceId", async (req, res) => {
  const data = await linkIO.getPendingLink(req.params.deviceId);
  res.json(data);
});

// Fingerprint-based pending link (for deferred deep linking)
app.get("/pending-link", async (req, res) => {
  const ip = req.ip || req.socket.remoteAddress || "";
  const userAgent = req.headers["user-agent"] || "";
  const data = await linkIO.getPendingLinkByFingerprint(ip, userAgent);
  res.json(data);
});

app.listen(3000);

📦 Features

• Universal Links (iOS) - Automatic apple-app-site-association generation
• App Links (Android) - Automatic assetlinks.json generation
• Smart Redirects - Tries to open app first, falls back to App Store/Play Store
• Deferred Deep Linking - Fingerprint-based matching preserves link data through install
• Referral Tracking - Track who referred whom
• Storage Options - In-memory, Redis, or custom storage
• TypeScript - Full type definitions included
• Tested - 31 unit tests with full coverage

📚 Documentation

Configuration

interface LinkIOConfig {
  domain: string; // Your domain (e.g., 'yourdomain.com')
  iosAppId: string; // Apple App Store ID
  iosTeamId: string; // Apple Developer Team ID
  iosBundleId: string; // iOS bundle identifier
  iosAppScheme?: string; // Custom URL scheme (e.g., 'myapp' for myapp://)
  androidPackageName: string; // Android package name
  androidAppScheme?: string; // Custom URL scheme (e.g., 'myapp' for myapp://)
  androidSHA256Fingerprints: string[]; // Android SHA256 cert fingerprints
  fallbackTimeout?: number; // Ms to wait before store redirect (default: 2500)
  storage: LinkIOStorage; // Storage implementation
}

API Endpoints

// Well-known endpoints (auto-generated)
app.get("/.well-known/*", linkIO.setupWellKnown());

// Generic deep link handler - works with ANY params
app.get("/link", linkIO.handleDeepLink());

// Example URLs:
//   https://rokart.in/link?referralCode=ABC123
//   https://speekfeed.in/link?userId=456
//   https://ejaro.com/link?carId=789

// Optional: Path-based routes for cleaner URLs
// app.get("/refer/:referralCode", linkIO.handleDeepLink());
// app.get("/profile/:userId", linkIO.handleDeepLink());

// ===========================================
// API ENDPOINTS - Match your SDK's backendURL
// ===========================================

// Get pending link for deferred deep linking
app.get("/pending-link/:deviceId", async (req, res) => {
  const data = await linkIO.getPendingLink(req.params.deviceId);
  res.json(data);
});

// Track referral
app.post("/track-referral", async (req, res) => {
  const { referralCode, userId, metadata } = req.body;
  await linkIO.trackReferral(referralCode, userId, metadata);
  res.json({ success: true });
});

// Get referrals for a user
app.get("/referrals/:referrerId", async (req, res) => {
  const referrals = await linkIO.getReferrals(req.params.referrerId);
  res.json({ referrals });
});

Storage Options

In-Memory (Development)

import { InMemoryStorage } from "linkio-backend";
const storage = new InMemoryStorage();

Redis (Production)

import { RedisStorage } from "linkio-backend";
import { createClient } from "redis";

const redis = await createClient().connect();
const storage = new RedisStorage(redis);

Custom Storage

import { LinkIOStorage } from "linkio-backend";

class CustomStorage implements LinkIOStorage {
  // Implement interface methods
}

🔗 Related Packages

• iOS SDK: LinkIO-iOS
• Android SDK: LinkIO-Android
• React Native: LinkIO-React-Native

🛠️ Development

# Install dependencies
npm install

# Build
npm run build

# Run example server
npm run dev

# Run tests
npm test

📄 License

MIT

🤝 Contributing

Contributions are welcome! Please read the contributing guidelines first.

📞 Support

• GitHub Issues
• Documentation

⭐ Show Your Support

Give a ⭐️ if this project helped you!