External Link Handling

Overview

Native link handling allows you to control whether links open in Safari, in-app browser tabs, or navigate within your app. This is essential for App Store compliance (payment links must open in Safari) and implementing OAuth flows or deep linking functionality.

Prerequisites

1. Install Despia plugin from WeWeb Marketplace

2. Have Despia plugin component on your page (recommended for other native features)

Link Handling Options

Opening Links in Safari (External Browser)

Required for payment processors to comply with App Store rules:

1. In Despia editor, go to In-app link handling

2. Under "Open always in browser", add domains:

   • buy.stripe.com (for Stripe)

   • Your payment processor's domain

3. Only add the root domain (not full URLs)

4. Rebuild your application after changes

Opening Links in In-App Browser

Default behavior for most links:

1. In WeWeb, add navigation workflow

2. Set to External link

3. Toggle "Open in new tab" as needed

4. Links open in app's built-in browser

Deep Linking Back to App

Close in-app browser and return to specific app page:

1. Set up deep link scheme: myapp:// or app link https://myapp.com

2. Use format: myapp://?link=[destination_url] - or your app link like: https://myapp.com/[destination_path]

3. Destination can include query parameters (useful for OAuth tokens)

Implementation Steps

Step 1: Configure Payment Links (Safari)

For Stripe or other payment processors:

1. Add button in WeWeb

2. Create workflow → Navigate to

3. Set External link with payment URL

4. In Despia, whitelist payment domain for Safari

Step 2: Configure In-App Browser Links

For OAuth or external content:

1. Add button in WeWeb

2. Create workflow → Navigate to

3. Set External link with target URL

4. Enable "Open in new tab"

Step 3: Implement Return Deep Links

On external page (OAuth callback, etc.):

1. Add return button/redirect

2. Navigate to: myapp://?link=https://yourapp.com/success or: https://myapp.com/success

3. Include any needed parameters in the link

OAuth Implementation

Complete OAuth Flow

1. Initiate: Open OAuth provider in in-app browser

2. Authorize: User completes authentication

3. Callback: Provider redirects to your callback URL

4. Return: Use deep link to return to app with token:

   Copymyapp://?link=https://app.com/dashboard&token=xyz123
   --- OR ---
   https://myapp.com/dashboard&token=xyz123
   

Custom OAuth Providers

Perfect for:

• Multi-app ecosystems with SSO

• Custom authentication servers

• Third-party providers without native SDKs

Despia Configuration

In-App Link Handling Settings

• Open always in browser: Domains that open in Safari

• Never open in browser: Force in-app (rarely needed)

• Always open in app: Default behavior

Deep Link Scheme

Your app's custom URL scheme (e.g., myapp://) is automatically configured based on your app name.

App Links Scheme

Your apps’ app links and universal links need to be manually configured in WeWeb. Refer to this guide for step-by-step instructions: https://weweb.despia.com/default-guide/global-integrations/applinks

Publishing & Updates

Requires Rebuild

Changes in Despia editor:

• Link handling rules

• Whitelisted domains

• Deep link schemes

Over-the-Air Updates

Changes in WeWeb:

• Button workflows

• Navigation logic

• URL parameters

Common Use Cases

E-commerce

• Payment processing (Stripe, PayPal)

• External checkout flows

• Return to app after purchase

Authentication

• OAuth providers (Google, Facebook, custom)

• SSO implementations

• Multi-app authentication

Content

• Terms of service (Safari)

• Help documentation (in-app)

• External media players

Best Practices

1. Payment Compliance: Always open payment links in Safari

2. User Experience: Minimize app switching

3. Security: Validate tokens and parameters

4. Testing: Test on actual devices, not simulators

5. Fallbacks: Handle cases where deep links fail

Testing Your Implementation

1. Deploy WeWeb changes

2. Rebuild app if Despia settings changed

3. Test payment links open in Safari

4. Test OAuth flow completes properly

5. Verify deep links return to correct page

Troubleshooting

Links not opening in Safari:

• Verify domain is whitelisted in Despia

• Check domain format (no https://, just domain)

• Rebuild app after Despia changes

Deep links not working:

• Check URL format: myapp://?link=...

• Verify app scheme matches

• Test with simple URLs first

OAuth tokens lost:

• Include token in deep link parameters

• Store in secure storage immediately

• Handle token refresh logic