Guides

Migration from Legacy Authentication

Copy page

If you're upgrading from a previous version that used YVPProvider and callback-based authentication, follow these steps:

Breaking Changes Summary

1. Provider Change: BibleSDKProvider → YouVersionProvider (complete replacement, no backwards compatibility)
2. Authentication Provider: YVPProvider eliminated - auth now integrated into YouVersionProvider
3. Hook Change: useAuthentication() → useYVAuth()
4. SignInButton Props: Simplified scopes and removed success callbacks
5. No Callback Page: OAuth redirects directly to your app (no /auth/callback needed)
6. JWT-based User Info: User information extracted from tokens (no /auth/me API calls)

Step-by-Step Migration

1. Update Your Provider

Before (Legacy SDK):

Code
// Old separate providers approach
import { YVPProvider, BibleSDKProvider } from '@youversion/platform-react-ui'

<YVPProvider config={{ appKey, redirectUri }}>
  <BibleSDKProvider appKey={appKey}>
    {children}
  </BibleSDKProvider>
</YVPProvider>

// OR just Bible content without auth
<BibleSDKProvider appKey={appKey}>
  {children}
</BibleSDKProvider>

After (Current SDK):

Code
import { YouVersionProvider } from '@youversion/platform-react-ui'

// With authentication
<YouVersionProvider
  appKey={appKey}
  includeAuth={true}
  authRedirectUrl={redirectUri}
>
  {children}
</YouVersionProvider>

// Bible content only (no auth)
<YouVersionProvider appKey={appKey}>
  {children}
</YouVersionProvider>

2. Update Authentication Hook Usage

Before:

Code
import { useAuthentication } from "@youversion/platform-react-ui";

const { isAuthenticated, signOut, userInfo } = useAuthentication();

After:

Code
import { useYVAuth } from "@youversion/platform-react-ui";

const { auth, signOut, userInfo } = useYVAuth();
// auth.isAuthenticated, auth.isLoading, auth.error

3. Update SignInButton to YouVersionAuthButton

Before:

Code
<SignInButton
  requiredPermissions={[SignInWithYouVersionPermission.bibles]}
  optionalPermissions={[SignInWithYouVersionPermission.highlights]}
  onSuccess={handleSuccess}
  onAuthError={handleError}
/>

After:

Code
<YouVersionAuthButton
  scopes={["profile", "email"]} // Optional, defaults to []
  onAuthError={handleError}
  mode="auto" // Optional: auto (default), signIn, or signOut
  // No onSuccess needed - state updates automatically
  // redirectUrl is no longer needed — set authRedirectUrl on YouVersionProvider instead
/>

4. Remove Callback Page

• Delete your /auth/callback page/route entirely
• Remove any WebAuthenticationStrategy.handleCallback() logic
• Update your OAuth app settings to redirect to your main app URL

5. Update Environment Variables

Before:

Code
NEXT_PUBLIC_REDIRECT_URI=https://yourapp.com/auth/callback

After:

Code
NEXT_PUBLIC_REDIRECT_URI=https://yourapp.com

Benefits of New Implementation

• ✅ Simpler Setup: No callback page required
• ✅ Enhanced Security: PKCE OAuth flow
• ✅ Better Performance: Direct JWT parsing, no additional API calls
• ✅ Unified Provider: Single provider for all features
• ✅ Automatic State Management: Authentication state updates automatically