# Quickstart

This guide walks you through creating your first WarpLink deep link and testing it on a device.

## 1. Create an Account

Sign up at [warplink.app](https://warplink.app). You'll automatically get a free organization with 10,000 monthly clicks.

## 2. Register Your App

In the dashboard, go to **Apps** and click **Register App**. Fill in your platform details:

```json
{
  "name": "My App",
  "ios_bundle_id": "com.example.myapp",
  "ios_team_id": "ABCDE12345",
  "ios_app_store_url": "https://apps.apple.com/app/id123456789"
}
```

```json
{
  "name": "My App",
  "android_package_name": "com.example.myapp",
  "android_sha256_fingerprints": ["AA:BB:CC:..."],
  "android_play_store_url": "https://play.google.com/store/apps/details?id=com.example.myapp"
}
```

```json
{
  "name": "My App",
  "ios_bundle_id": "com.example.myapp",
  "ios_team_id": "ABCDE12345",
  "android_package_name": "com.example.myapp",
  "android_sha256_fingerprints": ["AA:BB:CC:..."]
}
```

## 3. Create Your First Link

Go to **Links** and click **Create Link**, or use the API:

```bash
curl -X POST https://api.warplink.app/v1/links \
  -H "Authorization: Bearer wl_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_url": "https://example.com/promo",
    "ios_url": "myapp://promo",
    "android_url": "myapp://promo",
    "app_id": "YOUR_APP_ID"
  }'
```

You'll get back a short link on your app's subdomain, like `https://yourapp.aplnk.to/abc123`.

`myapp://promo` is an in-app route, so it only opens for someone who already has the app. On iOS and Android, everyone else is sent to `ios_fallback_url` or `android_fallback_url` if the link has one, and to your app's store URL if it does not. Set at least one of those, or a visitor without your app has nowhere to land. On Android, use the `https://play.google.com` store address so installs match. See [Getting more installs matched](https://warplink.app/docs/concepts/attribution#why-an-install-did-not-match).

## 4. Install the SDK

**Use an SDK key here, not an API key.** The SDKs authenticate with an **SDK key**, created in the dashboard under **Keys** > **SDK keys**. It is pre-scoped for link resolution and install attribution. Only an SDK key records installs, so configure the SDK with it. If you have more than one app, choose the app when you create the key: a key tied to one app records installs only for that app.

Add WarpLink via Swift Package Manager:

```
https://github.com/WarpLinkApp/warplink-ios-sdk.git
```

Configure in your `AppDelegate`. One `onLink` callback receives taps and deferred installs:

```swift
import WarpLink

func application(
  _ application: UIApplication,
  didFinishLaunchingWithOptions options: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
  WarpLink.configure(
    apiKey: "wl_live_yoursdkkeyhere000000000000000000",
    options: WarpLinkOptions(onLink: { result in
      if case .success(let link) = result, let link {
        navigate(to: link)
      }
    })
  )
  return true
}
```

Then forward the tapped URL to the SDK (there is no swizzling):

```swift
func application(
  _ application: UIApplication,
  continue userActivity: NSUserActivity,
  restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
) -> Bool {
  WarpLink.continue(userActivity)
}
```

Scene-based apps forward from their scene delegate instead, and setting your delegate class to the drop-in `WarpLinkAppDelegate` or `WarpLinkSceneDelegate` does it for you. See the [iOS SDK guide](https://warplink.app/docs/sdks/ios).

Add to your `build.gradle.kts`:

```kotlin
dependencies {
  implementation("app.warplink:sdk:1.3.0")
}
```

Initialize in your `Application` class. Cold start and the deferred check are wired automatically:

```kotlin
import app.warplink.WarpLink
import app.warplink.WarpLinkOptions

class MyApp : Application() {
  override fun onCreate() {
    super.onCreate()
    WarpLink.configure(
      context = this,
      apiKey = "wl_live_yoursdkkeyhere000000000000000000",
      options = WarpLinkOptions(onLink = { result ->
        result.onSuccess { link -> navigateTo(link) }
      })
    )
  }
}
```

Install the package:

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

Configure in your app entry. One `onLink` callback handles cold start, warm start, and deferred installs:

```typescript
import { WarpLink } from '@warplink/react-native';

WarpLink.configure({
  apiKey: 'wl_live_yoursdkkeyhere000000000000000000',
  onLink: ({ deepLink }) => deepLink && navigateTo(deepLink.destination),
});
```

On iOS, forward the tapped URL from your `AppDelegate` so taps reach the SDK. Add the WarpLink call to the delegate method you already have and keep returning your existing linking result, so React Navigation and Expo Linking still receive the URL:

```swift
// ios/YourApp/AppDelegate.swift
import React
import warplink_react_native

func application(
  _ application: UIApplication,
  continue userActivity: NSUserActivity,
  restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
) -> Bool {
  if userActivity.activityType == NSUserActivityTypeBrowsingWeb,
     let url = userActivity.webpageURL {
    WarpLinkModule.handleIncomingURL(url)
  }
  return RCTLinkingManager.application(
    application, continue: userActivity, restorationHandler: restorationHandler)
}
```

Android needs no host code. The [React Native SDK guide](https://warplink.app/docs/sdks/react-native#ios-appdelegate-hook) covers the Objective-C form, custom URL schemes, and Expo prebuild. If your app has a `SceneDelegate` (`Info.plist` declares `UIApplicationSceneManifest`), the [iOS SceneDelegate hook](https://warplink.app/docs/sdks/react-native#ios-scenedelegate-hook) is also required: iOS stops calling the AppDelegate method above once a scene exists.

Add the package:

```bash
flutter pub add warplink_flutter
```

Configure once from your root widget's `initState`. One `onLink` callback handles cold start, warm start, and deferred installs:

```dart
import 'package:flutter/material.dart';
import 'package:warplink_flutter/warplink_flutter.dart';

class _AppState extends State<App> {
  @override
  void initState() {
    super.initState();
    WarpLink.configure(
      apiKey: 'wl_live_yoursdkkeyhere000000000000000000',
      onLink: (event) {
        if (event is LinkEvent) navigateTo(event.deepLink.destination);
      },
    );
  }
}
```

`navigateTo` waits for your navigator before it pushes a route. The [Flutter SDK guide](https://warplink.app/docs/sdks/flutter) has the full root widget and the `navigatorKey` setup.

No `AppDelegate`, `SceneDelegate`, or `MainActivity` code is needed. On Android, set `minSdk = 26` in `android/app/build.gradle.kts` and keep the `launchMode` your Flutter template sets. The [Flutter SDK guide](https://warplink.app/docs/sdks/flutter) covers both platforms, including Flutter's own link handling.

Add one option so the SDK knows your link hosts from the very first launch: `linkDomains: ["yourapp.aplnk.to"]` at `configure()`, plus any [custom domain](https://warplink.app/docs/concepts/custom-domains) such as `links.yourapp.com`, or the plist / manifest equivalent on native. Full detail in [Use it in your app](https://warplink.app/docs/concepts/custom-domains#use-it-in-your-app).

## 5. Enable Associated Domains (iOS Only)

Universal Links only open your app if iOS can verify your app is allowed to handle them. Before testing, add the `Associated Domains` capability in Xcode (**Signing & Capabilities** > **+ Capability** > **Associated Domains**) with `applinks:yourapp.aplnk.to` (find your app's subdomain in the dashboard: open the app, then **Settings**), and enable Associated Domains on the same App ID at [developer.apple.com](https://developer.apple.com). Skip this step and the link opens Safari instead of your app, with nothing in the redirect to explain why. Full steps: [Configure Associated Domains for Universal Links](https://warplink.app/docs/sdks/ios#configure-associated-domains-for-universal-links).

Android has an equivalent requirement, but no separate developer-portal step: adding the `android:autoVerify="true"` intent filter to `AndroidManifest.xml`, covered in the [Android SDK guide](https://warplink.app/docs/sdks/android), is what triggers verification. React Native and Flutter apps need both: the [React Native](https://warplink.app/docs/sdks/react-native#platform-setup) and [Flutter](https://warplink.app/docs/sdks/flutter#platform-setup) guides cover the iOS capability and the Android intent filter together.

## 6. Test Your Link

1. Open `https://yourapp.aplnk.to/abc123` on a device with your app installed
2. The link should open your app directly via Universal Links (iOS) or App Links (Android)
3. If the app isn't installed, the user is redirected to the app store

## Next Steps

- [Test your integration](https://warplink.app/docs/guides/testing): Check links, installs, and analytics in Test mode before you go live
- [Deep Linking Concepts](https://warplink.app/docs/concepts/deep-linking): Understand how deep links work
- [Deferred Deep Links](https://warplink.app/docs/concepts/deferred-deep-links): Preserve context through installs
- [Referrals](https://warplink.app/docs/guides/referrals): Run an invite or referral program
- [API Reference](https://warplink.app/docs/api): Full endpoint documentation
