OAuth 2.0 (Complex)

How it works

Despia acts as a bridge between your web app and native authentication. The OAuth implementation differs between Android and iOS due to platform-specific requirements.

Android Setup

Android devices can use the standard browser OAuth flow with no special handling required.

Android's App Links system allows the external browser to redirect directly back into your app after authentication. Simply configure your assetlinks.json file to enable this seamless flow:

1. Use standard browser redirect for OAuth (window.location.href = oauthUrl)

2. Configure your App Links in the assetlinks.json file hosted at https://yourapp.com/.well-known/assetlinks.json

3. Register your standard callback URL (e.g., https://yourapp.com/oauth/callback) with your OAuth provider

That's it—no deeplink schemes or special callback pages needed for Android.

iOS Setup

iOS requires a special flow using Safari View Controller.

Apple does not support App Links the same way Android does. Additionally, Apple's UX guidelines require OAuth flows to use the Safari View Controller (an in-app browser tab) rather than redirecting to Safari—violating this causes App Store rejection.

To exit the Safari View Controller and return to your main app webview, you must use your app's custom URL scheme deeplink.

Find your app's deeplink scheme in your Despia project under Publish settings, located near the Bundle ID. Your deeplink scheme will look like: com.yourcompany.yourapp:// or a custom scheme like yourappname://

Installation

Install the Despia package from NPM:

Copynpm install despia-native

Usage

1. Import the SDK

Copyimport despia from 'despia-native';

2. Define Your App Deeplink Scheme

Copy// Find this in your Despia project under Publish settings, near Bundle ID
const APP_DEEPLINK_SCHEME = 'myapp://';
const APP_BASE_URL = 'https://yourapp.com';

3. Detect iOS Despia Environment

Before initiating OAuth, check if the user is on an iOS device within the Despia app:

Copyfunction isDespiaiOS() {
  const ua = navigator.userAgent.toLowerCase();
  return ua.includes('despia') && (ua.includes('iphone') || ua.includes('ipad'));
}

4. Initiate OAuth Flow

Call the despia() function with a Safari View Controller URL only for iOS devices:

Copyfunction startOAuth() {
  const oauthUrl = `https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=${encodeURIComponent(APP_BASE_URL + '/oauth/callback/ios')}&response_type=code&scope=email profile`;
  
  if (isDespiaiOS()) {
    // iOS: Use Safari View Controller
    despia(`safariviewcontroller://?url=${oauthUrl}`);
  } else {
    // Android/Web: Use standard browser redirect
    window.location.href = oauthUrl.replace('/oauth/callback/ios', '/oauth/callback');
  }
}

iOS OAuth Flow Architecture

The iOS OAuth flow requires two callback pages working together:

Copy┌─────────────────────────────────────────────────────────────────────────┐
│  1. User taps "Sign In"                                                 │
│     ↓                                                                   │
│  2. despia("safariviewcontroller://?url=https://oauth-provider.com")    │
│     ↓                                                                   │
│  3. Safari View Controller opens (in-app browser tab)                   │
│     ↓                                                                   │
│  4. User authenticates with OAuth provider                              │
│     ↓                                                                   │
│  5. Provider redirects to /oauth/callback/ios (still in Safari VC)      │
│     ↓                                                                   │
│  6. Callback page exchanges code for access token via backend           │
│     ↓                                                                   │
│  7. Page triggers deeplink: {app-scheme}://?link=https://app.com/...    │
│     ↓                                                                   │
│  8. Safari View Controller closes, main webview opens callback URL      │
│     ↓                                                                   │
│  9. Main webview callback sets auth cookie, user is logged in           │
└─────────────────────────────────────────────────────────────────────────┘

Callback Pages Setup

iOS Callback Page (/oauth/callback/ios)

This helper page runs inside the Safari View Controller. It exchanges the authorization code for an access token, then triggers a deeplink to exit back to the main app:

Copy<!-- /oauth/callback/ios -->
<html>
<body>
  <div class="spinner">Completing sign in...</div>
  <script>
    // Find this in your Despia project under Publish settings, near Bundle ID
    const APP_DEEPLINK_SCHEME = 'com.yourcompany.yourapp://';
    const APP_BASE_URL = 'https://yourapp.com';
    
    async function handleCallback() {
      // Get authorization code from URL
      const params = new URLSearchParams(window.location.search);
      const code = params.get('code');
      
      // Exchange code for access token via your backend
      const response = await fetch('/api/auth/exchange', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ code })
      });
      
      const { access_token } = await response.json();
      
      // Exit Safari View Controller and open main webview callback
      window.location.href = `${APP_DEEPLINK_SCHEME}?link=${APP_BASE_URL}/oauth/callback?access_token=${access_token}`;
    }
    
    handleCallback();
  </script>
</body>
</html>

Main Callback Page (/oauth/callback)

This page runs in the main app webview after the Safari View Controller closes. It sets the authentication cookie and completes the login:

Copy// /oauth/callback
function completeLogin() {
  const params = new URLSearchParams(window.location.search);
  const accessToken = params.get('access_token');
  
  if (accessToken) {
    // Set authentication cookie or store token
    document.cookie = `auth_token=${accessToken}; path=/; secure; samesite=strict`;
    
    // Redirect to authenticated area
    window.location.href = '/dashboard';
  }
}

completeLogin();

OAuth Provider Configuration

You must register two redirect URIs with your OAuth provider:

URL Parameters

Safari View Controller URLs use this format:

Deeplink return URLs use this format:

Platform Support

Important Notes

• Apple UX Guidelines: Using Safari directly instead of Safari View Controller will cause App Store rejection. Always use safariviewcontroller:// for iOS OAuth.

• User Agent Detection: Only trigger the iOS flow when the user agent contains both "despia" AND ("iphone" OR "ipad").

• Deeplink Scheme: Find your app's deeplink scheme in your Despia project under Publish settings, located near the Bundle ID.

• Whitelist Redirect URIs: Remember to whitelist the iOS-specific callback URL with every OAuth provider you integrate.

Resources

• NPM Package: https://www.npmjs.com/package/despia-native

• View full NPM documentation for additional configuration options

Integration

This SDK is optimized for prompt-based AI builders, enabling quick integration of native OAuth features via minimal JavaScript into your generated apps.