> ## Documentation Index
> Fetch the complete documentation index at: https://docs.world.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Invites & Viral Loops

## Why It Works

Referral programs are proven growth drivers because they leverage trust. People are 4x more likely to try something recommended by a friend versus discovering it through ads. PayPal's $20/$20 referral program produced 7-10% daily growth, while Dropbox's free storage rewards drove 3900% growth in 15 months.

## Step-by-Step Implementation

### 1. Set Up Universal Links

Create server-side invite pages that work across all platforms:

```typescript theme={null}
// pages/invite.tsx
export default function InvitePage({ code }: { code: string }) {
	useEffect(() => {
		// Redirect to mini app
		window.location.href = `https://world.org/mini-app?app_id=${YOUR_APP_ID}&path=/invite?code=${code}`
	}, [code])

	return <div>Redirecting to mini app...</div>
}
```

Universal-link format

`https://world.org/mini-app?app_id={app_id}&path={path}`

Deep-link (opens World App directly if installed)

`worldapp://mini-app?app_id={app_id}&path={path}`

To force opening in the device browser instead of the native webview, append `open_out_of_window=true` to the URL (works for both universal and deep links).

Note: path should be URL encoded.

### 2. Generate Share Links

Create a shareable link that includes the referral information:

```typescript theme={null}
function generateInviteLink(userId: string): string {
  const baseUrl = "https://world.org/mini-app";
  const appId = "your_app_id";
  const path = encodeURIComponent(`/invite?code=${userId}`);

  return `${baseUrl}?app_id=${appId}&path=${path}`;
}
```

### 3. Implement Share Functionality

Add share buttons at key moments in your user journey:

```typescript theme={null}
import { MiniKit } from "@worldcoin/minikit-js";

async function shareInvite() {
  const inviteLink = generateInviteLink(currentUser.id);

  try {
    await MiniKit.share({
      title: "Join me on [Your App Name]!",
      text: `I'm using this amazing mini app. Join me and we both get rewards! 🎁`,
      url: inviteLink,
    });

    // Track the share event
    trackEvent("invite_link_created", {
      user_id: currentUser.id,
      share_method: "native",
    });
  } catch (error) {
    console.error("Share failed:", error);
  }
}
```

### 4. Handle Incoming Referrals

Process referral codes when new users sign up:

```typescript theme={null}
// On app initialization
function handleReferral() {
  const urlParams = new URLSearchParams(window.location.search);
  const refCode = urlParams.get("ref");

  if (refCode && !currentUser.referredBy) {
    // Credit the referrer
    fetch("/api/process-referral", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        newUserId: currentUser.id,
        referrerCode: refCode,
      }),
    });
  }
}
```

### 5. Reward System

Implement two-sided rewards that benefit both parties:

```typescript theme={null}
// api/process-referral.ts
export async function processReferral(data: {
  newUserId: string;
  referrerCode: string;
}) {
  const referrer = await getUserByCode(data.referrerCode);
  if (!referrer) {
    return { success: false, reason: "invalid_referrer" };
  }

  // Credit both users
  await Promise.all([
    creditUser(referrer.id, {
      type: "referral_bonus",
      amount: 100,
      reason: "Friend joined via your invite",
    }),
    creditUser(data.newUserId, {
      type: "signup_bonus",
      amount: 50,
      reason: "Welcome bonus for joining via invite",
    }),
  ]);

  return { success: true };
}
```

### 6. Support Deferred Deep Links (Android)

```
https://play.google.com/store/apps/details?id=com.worldcoin&referrer=app_id%3D{app_id}%26path%3D{path}
```

World App prompts the install and then automatically forwards the user to your specified path.

### Optimising Social-Share Previews

World app universal links will forward the og:image from your integration url.

Eg. `world.org/mini-app?app_id=1234&path=/invite?code=abcd` will forward the og:image from `[your-miniapp-url]/invite?code=abcd`.

### Inside World App Discovery

* **Quick Actions**: Mini apps can hand off context to one another. Split distinct flows into focused apps that trigger each other with Quick Actions.

* **Widget**: Your mini app can live on the phone's home screen. Prompt the user to add the mini app as a widget in the home screen.

<div className="flex justify-center">
  <img src="https://mintcdn.com/tfh/vNgKkjbn9HQ46Vw7/images/docs/mini-apps/virality/widget.jpg?fit=max&auto=format&n=vNgKkjbn9HQ46Vw7&q=85&s=a218caf7c3c56916ace928e9d83fe564" alt="Widget" className="m-auto block" width="260" style={{ maxWidth: "260px", height: "auto" }} data-path="images/docs/mini-apps/virality/widget.jpg" />
</div>

Widget on iOS

## Design Best Practices

### Placement Strategy

* **After first value delivery**: When user completes their first meaningful action
* **Post-achievement**: Right after earning a badge, completing a level, or winning
* **Onboarding finale**: As the last step of user setup

### Copy That Converts

* **Personal benefit first**: "Get 100 coins for each friend who joins"
* **Mutual benefit**: "You both get rewards when they sign up"
* **Social proof**: "Join 10,000+ users already earning rewards"

### Visual Design

* Use prominent, action-oriented buttons ("Invite Friends", "Share & Earn")
* Show potential rewards clearly with icons or progress bars
* Include preview of what the shared content looks like

## Metrics to Track

Monitor these key events to measure your viral loop performance:

```typescript theme={null}
// Essential tracking events
const events = {
  invite_link_created: { user_id, share_method },
  invite_link_clicked: { ref_code, source },
  signup_source_invite: { ref_code, new_user_id },
  referral_reward_granted: { referrer_id, new_user_id, reward_amount },
};
```

### Key Metrics Dashboard

* **Invite Conversion Rate**: (Signups from invites) / (Total invite links clicked)
* **K-Factor**: (New users from invites) / (Total active users)
* **Viral Cycle Time**: Average time from invite sent to new user activated
* **Reward Cost per Acquisition**: Total rewards paid / New users acquired

## Quick A/B Test Ideas

Test these variables to optimize your viral loop:

1. **Reward Amount**: Test 50 vs 100 vs 200 coin rewards
2. **Timing**: Share prompt after first win vs after onboarding
3. **Copy**: Personal benefit vs mutual benefit messaging
4. **Incentive Type**: Coins vs premium features vs exclusive content

<Warning>
  Start with small reward amounts and scale up based on unit economics. Cap
  total lifetime rewards per user to control costs.
</Warning>

## Next Steps

1. Implement universal links for your invite flow
2. Add share buttons after key user achievements
3. Set up two-sided rewards with World ID verification
4. Track invite metrics and run small A/B tests
5. Scale successful invite mechanics across more touchpoints