Skip to main content

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.

​
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/20 referral program produced 7-10% daily growth, while Dropbox’s free storage rewards drove 3900% growth in 15 months.

​
Step-by-Step Implementation

Create server-side invite pages that work across all platforms: 
// 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. Create a shareable link that includes the referral information: 
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: 
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: 
// 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: 
// 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 };
}

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.
Widget
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: 
// 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
Start with small reward amounts and scale up based on unit economics. Cap total lifetime rewards per user to control costs.

​
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