# LinkOwl Setup Guide
# For AI Coding Assistants (VibeCode, Cursor, Rork Max, Bolt, Lovable, Xcode, etc.)

> This document is designed to be pasted into your AI coding tool. It contains everything your AI needs to integrate LinkOwl into your iOS app or website. Just paste it and tell your AI what you're building.

---

## What is LinkOwl?

LinkOwl is a simple attribution tool for app developers and website owners. It tracks which campaigns, influencers, or channels drive your installs/visits and purchases. You create tracking links, share them, and LinkOwl tells you which ones make money.

**Pricing:** Free to use. £0.05 per attributed first purchase, £0.02 per renewal. You're only charged when LinkOwl actually tracks a sale. Charges accumulate and your card is billed when the balance reaches £5.

---

## Step 1: Create Your Account and Project

1. Go to https://linkowl.app/signup
2. Create an account with email and password
3. After logging in, click **"Add App"** (for iOS) or **"Add Website"** (for web)
4. Fill in:
   - **For iOS:** App name, Bundle ID (e.g. `com.yourcompany.yourapp`), App Store URL
   - **For Web:** Project name, Website URL (e.g. `https://yoursite.com`)
5. After creation, you'll see your **API key** (starts with `lo_live_`). Copy it — you'll need it below.
6. You can always find your API key later in **Dashboard → Your App/Website → Settings**

---

## Step 2: Determine Your Platform

Read the user's project to determine which platform they're building for:

- **iOS App (Swift/SwiftUI)** → Go to Section A
- **iOS App (React Native / Expo)** → Go to Section B
- **Website (HTML/JS, Next.js, etc.)** → Go to Section C

---

## Section A: iOS App (Swift / SwiftUI)

### A1. Install the Swift SDK

Add the LinkOwl Swift package to the project:

**Swift Package Manager (SPM):**
- In Xcode: File → Add Package Dependencies
- URL: `https://github.com/linkowl/linkowl-swift`
- Or add to `Package.swift`:

```swift
dependencies: [
    .package(url: "https://github.com/linkowl/linkowl-swift", from: "1.0.0")
]
```

**If using Rork Max or another SwiftUI builder:**
Tell it to add the SPM package `https://github.com/linkowl/linkowl-swift`

### A2. Initialise LinkOwl

In your app's entry point (e.g. `@main` App struct or `AppDelegate`), initialise LinkOwl:

```swift
import LinkOwl

@main
struct YourApp: App {
    init() {
        LinkOwl.configure(apiKey: "YOUR_API_KEY")
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}
```

Replace `YOUR_API_KEY` with the API key from your LinkOwl dashboard.

**What this does:**
- Checks if the user came from a LinkOwl tracking link
- Reports the install to LinkOwl with the attribution data
- Sends only timezone and locale (no personal data)

### A3. Connect RevenueCat (for purchase tracking)

If the app uses **RevenueCat** for in-app purchases:

1. Go to your LinkOwl dashboard → Your App → **Settings**
2. Find the **RevenueCat Webhook** section
3. Copy the **Webhook URL** (it's unique to your app, looks like `https://linkowl.app/api/v1/webhooks/revenuecat/YOUR_APP_ID`)
4. Go to https://app.revenuecat.com → Your Project → **Project Settings → Webhooks**
5. Click **"Add Webhook"**
6. Paste the LinkOwl webhook URL
7. Enable these events: **INITIAL_PURCHASE** and **RENEWAL**
8. Save
9. RevenueCat will show a **shared secret** — copy it
10. Go back to your LinkOwl dashboard → App Settings → **Webhook Secret** field
11. Paste the shared secret and click **Save**
12. You should see a green dot with **"Connected"** status

### A4. Connect Superwall (alternative to RevenueCat)

If the app uses **Superwall** instead of RevenueCat:

1. Go to your LinkOwl dashboard → Your App → **Settings**
2. Copy the **Webhook URL**
3. In Superwall dashboard, add the webhook URL to your webhook settings
4. Copy the signing secret back into LinkOwl settings

### A5. Done — iOS

That's it for iOS. When someone clicks a LinkOwl tracking link → installs your app → makes a purchase, the full chain is tracked automatically.

---

## Section B: iOS App (React Native / Expo)

### B1. Install the React Native SDK

```bash
npm install @linkowlnew/react-native
```

or

```bash
yarn add @linkowlnew/react-native
```

This package is pure JavaScript — no native modules, works with Expo Go out of the box.

### B2. Initialise LinkOwl

In your app's entry point (e.g. `App.tsx` or `App.js`), add:

```typescript
import { LinkOwl } from '@linkowlnew/react-native';

// Call this once when the app starts
LinkOwl.configure('YOUR_API_KEY');
```

Replace `YOUR_API_KEY` with the API key from your LinkOwl dashboard.

**What this does:**
- Checks if the user came from a LinkOwl tracking link (via clipboard or deep link)
- Reports the install to LinkOwl with the attribution data
- Sends only timezone and locale (no personal data)

### B3. Connect RevenueCat or Superwall

Follow the same steps as Section A3 or A4 above — the webhook setup is identical regardless of whether your app is Swift or React Native.

### B4. Done — React Native

That's it. Same attribution chain: click → install → purchase, all tracked.

---

## Section C: Website

### C1. Add the Tracking Script

Add this script tag to your website, just before the closing `</head>` tag:

```html
<script src="https://linkowl.app/lo.js" data-key="YOUR_API_KEY"></script>
```

Replace `YOUR_API_KEY` with the API key from your LinkOwl dashboard.

**What this does:**
- Reads the `lo_ref` parameter from LinkOwl attribution links
- Stores it in a 30-day cookie
- Reports the visit back to your LinkOwl dashboard
- 2KB, zero dependencies, fails silently if anything goes wrong

**If using Next.js:** Add it to your `<Head>` component or `layout.tsx`:
```tsx
<Script src="https://linkowl.app/lo.js" data-key="YOUR_API_KEY" strategy="afterInteractive" />
```

### C2. Connect Stripe (for purchase tracking)

This lets LinkOwl track which visits turn into paying customers.

**In your LinkOwl dashboard:**
1. Go to your website project → **Settings**
2. Find the **Stripe Webhook** section
3. Copy the **Webhook URL** (looks like `https://linkowl.app/api/v1/webhooks/stripe/YOUR_APP_ID`)

**In your Stripe dashboard (https://dashboard.stripe.com):**
1. Go to **Developers → Webhooks**
2. Click **"Add destination"**
3. Select **"Webhook endpoint"** → click **Continue**
4. Select **"Your account"** → click **Continue**
5. Search for and select these two events:
   - `checkout.session.completed`
   - `invoice.paid`
6. Click **Continue**
7. On the destination details page:
   - **Destination name** — anything you like (e.g. your website name)
   - **Endpoint URL** — paste the webhook URL you copied from LinkOwl
   - Leave Description blank
8. Click **"Create destination"**
9. Stripe will show a **signing secret** (starts with `whsec_...`) — copy it

**Back in your LinkOwl dashboard:**
10. Paste the signing secret into the **Webhook Signing Secret** field
11. Click **Save**
12. You should see a green dot with **"Connected · Waiting for first event"**

### C3. Set User Identity (Optional but Recommended)

For better attribution accuracy, call `LinkOwl.setUserId()` when a user signs up or logs in. This links their identity to the attribution click.

```javascript
// After signup or login — use their Stripe customer ID or email
LinkOwl.setUserId("cus_abc123")
// or
LinkOwl.setUserId("user@example.com")
```

This helps LinkOwl match the visit to the Stripe purchase even if cookies are cleared.

### C4. Done — Website

That's it. When someone clicks a LinkOwl tracking link → visits your site → makes a purchase through Stripe, the full chain is tracked.

---

## Step 3: Create Tracking Links

Once your app or website is connected:

1. Go to your LinkOwl dashboard
2. Click into your app/website
3. Click **"+ New Link"**
4. Give it a name (e.g. "TikTok Campaign", "YouTube Review", "Instagram Bio")
5. Set the destination:
   - **iOS:** Your App Store URL
   - **Web:** Your website URL
6. You'll get a tracking link like `https://linkowl.app/l/abc123`
7. Share this link with influencers, in ads, on social media, etc.

Each link tracks clicks, installs/visits, purchases, and revenue separately — so you can see exactly which campaign or influencer drives the most money.

---

## Step 4: Add Payment Method (For Billing)

LinkOwl charges £0.05 per attributed first purchase and £0.02 per renewal. To avoid any interruption:

1. Go to **Dashboard → Billing** (in the sidebar)
2. Click **"Add payment method"**
3. Enter your card details
4. Your card is only charged when your balance reaches £5 (100 attributed purchases)

If your balance is under £5, it simply rolls over. No subscription, no monthly fees.

---

## Troubleshooting

**"Not connected" on webhook status:**
Make sure you've pasted the signing/shared secret into the LinkOwl settings and clicked Save.

**No installs showing up (iOS):**
- Check that `LinkOwl.configure(apiKey:)` is called on app launch
- Make sure the API key matches the one in your dashboard
- Test by clicking a LinkOwl tracking link, then opening the app

**No visits showing up (Web):**
- Check that the script tag is loading (look in browser Network tab for `lo.js`)
- Make sure the API key in the script tag matches your dashboard
- Test by clicking a LinkOwl tracking link — you should see the visit in your dashboard

**No purchases showing up:**
- Check the webhook status in your app/website settings — it should show "Connected"
- In RevenueCat/Stripe, check if the webhook is receiving events (look for delivery attempts)
- Make a test purchase and check if it appears in LinkOwl within a few minutes

---

## Summary

| Platform | SDK | Purchase Tracking |
|----------|-----|-------------------|
| iOS (Swift) | `linkowl-swift` via SPM | RevenueCat or Superwall webhook |
| iOS (React Native) | `@linkowlnew/react-native` via npm | RevenueCat or Superwall webhook |
| Website | `lo.js` script tag | Stripe webhook |

**Support:** support@linkowl.app
**X / Twitter:** https://x.com/samheli0 — DMs open
**Dashboard:** https://linkowl.app/dashboard
**Docs:** https://linkowl.app/docs
**AI Setup Guide:** https://linkowl.app/setup-guide