Relay - Deferred linking and referral attribution library for React Native and Expo

Relay

Relay is a powerful deferred linking and referral attribution library designed for React Native and Expo applications. It enables seamless attribution tracking by matching users across app installations using device fingerprinting.

What is Deferred Linking?

Deferred linking allows you to attribute a user's actions before app installation to their behavior after installation. This is crucial for:

Referral Programs: Track who referred a new user
Marketing Campaigns: Attribute app installs to specific campaigns
Deep Linking: Redirect users to specific content after installation
User Attribution: Match pre-install and post-install user sessions

How Relay Works

Relay uses a two-step process to match users across sessions:

1. Capture Phase (Pre-Install)

When a user clicks a referral link or visits your landing page:

// User clicks referral link with returnTo parameter
// e.g., yourapp.com/relay/capture?returnTo=https://example.com/invite/abc123

await relayExpoClient.capture(returnToUrl);

Relay captures a unique device fingerprint including:

Device manufacturer and model
Operating system details
Screen dimensions and pixel ratio
Timezone and language settings
IP address
Clipboard content (optional)

2. Process Phase (Post-Install)

When the user opens your app after installation:

const result = await relayExpoClient.process();

if (result.url) {
  // Match found! Redirect user to the deferred link
  router.push(result.url);
}

Relay generates a new fingerprint and matches it against stored fingerprints to retrieve the original link.

Key Features

🎯 Accurate Attribution: Uses multi-factor device fingerprinting
👤 Auth Context Support: Pass authenticated user info to hooks for immediate referral attribution
📱 Expo & React Native: Built specifically for mobile apps
🔒 Privacy-Focused: No third-party tracking services required
⚙️ Flexible Storage: Bring your own database (file-based, SQL, NoSQL)
🪝 Customizable Hooks: React to match events with custom logic and access to user context
📊 Built-in Analytics: Track fingerprints and link performance

Quick Start

Get started with Relay in minutes:

pnpm add @korsolutions/relay

See the Installation Guide for detailed setup instructions.

Use Cases

Referral Programs with Auth Context

Track who referred each new user and reward them immediately upon signup using authentication context:

// Client: Process the fingerprint after user signs up
const result = await relayExpoClient.process();

// Server: Use auth context in the onMatchFound hook
const relay = createRelayServer({
  hooks: {
    onMatchFound: async (deferredLink, authCtx) => {
      if (authCtx?.userId) {
        // Extract referral code from the deferred link
        const url = new URL(deferredLink.url);
        const referralCode = url.searchParams.get('ref');

        // Find the referrer and award points
        const referrer = await db.users.findOne({ referralCode });
        if (referrer) {
          await db.referrals.create({
            referrerId: referrer.id,
            referredUserId: authCtx.userId,
            referralCode,
          });
          await rewardReferrer(referrer.id, 100);
        }
      }
    },
  },
});

// Handler passes auth context from session
export const POST = async (request: Request) => {
  const user = await getUserFromSession(request);
  return relay.handler(request, { userId: user?.id ?? null });
};

Marketing Attribution

Attribute app installs to specific marketing campaigns:

// Capture with campaign URL
await relayExpoClient.capture('https://yourapp.com/campaign/summer-sale');

// Process and track conversion
const result = await relayExpoClient.process();
if (result.url?.includes('summer-sale')) {
  trackConversion('summer-sale');
}

Content Deep Linking

Direct new users to specific content after installation:

const result = await relayExpoClient.process();
if (result.url) {
  // Navigate to the specific content
  router.push(result.url);
}

Architecture

Relay consists of two main components:

Client SDK (RelayExpoClient): Runs in your Expo/React Native app
Server SDK (createRelayServer): Handles API requests and data storage

Both components work together to provide seamless attribution tracking.

Next Steps

Installation - Install and configure Relay
Client Setup - Configure the Expo client
Server Setup - Set up the server-side API
API Reference - Detailed API documentation

Introduction