Upgrade by popup

Open the app in a separate window instead of navigating away or embedding it. The current page never unloads. Reach for this when a full-page redirect is too heavy but you don’t want the app inline — and it’s the recommended route for React Native, where it runs in the system auth session (ASWebAuthenticationSession on iOS / Chrome Custom Tabs on Android). See the overview for detection, hosting, and the shared CORS requirements.

On the web, browsers block popups that aren’t opened from a user gesture. Call openUpgradePopup (or the hook’s open) synchronously inside the click handler — don’t await anything before it, or the popup is blocked and you get an UpgradePopupBlockedError.

TypeScript
React
React Native

openUpgradePopup opens the window synchronously and resolves completed when the app reports done (refreshing the session on success). completed rejects with an UpgradePopupClosedError if the user closes the popup first, and the call throws an UpgradePopupBlockedError if the browser blocks it.

import {
  openUpgradePopup,
  UpgradePopupClosedError,
} from '@dynamic-labs-sdk/legacy-embedded-wallet-upgrade';

// On your "Upgrade wallet" button's click handler — no await before this call.
function startUpgrade() {
  const session = openUpgradePopup();

  session.completed
    .then((outcome) => {
      if (outcome.status === 'success') {
        // Session already refreshed. refreshUi is your implementation.
        refreshUi();
      } else {
        offerRetry();
      }
    })
    .catch((error) => {
      if (error instanceof UpgradePopupClosedError) {
        // The user dismissed the popup before finishing.
        offerRetry();
      }
    });

  // If you need to dismiss it yourself (e.g. the user navigates away):
  // session.close();
}

useUpgradePopup wraps the popup lifecycle: call open from a click handler, then drive your UI off result (the outcome once complete, undefined until then) and error (set on a dismissed/blocked popup or open failure). onComplete / onError callbacks are also available if you prefer. The popup is closed for you on unmount.

import { useUpgradePopup } from '@dynamic-labs-sdk/legacy-embedded-wallet-upgrade/react';

function UpgradeButton() {
  const { open, result, error } = useUpgradePopup();

  if (result?.status === 'success') {
    // The session was already refreshed for you.
    return <p>Wallet upgraded.</p>;
  }

  // error covers a dismissed popup (UpgradePopupClosedError), a blocked popup
  // (UpgradePopupBlockedError), and open failures; result.status 'error' covers
  // a failed upgrade.
  const failed = error !== undefined || result?.status === 'error';

  return (
    <>
      <button type="button" onClick={open}>
        Upgrade wallet
      </button>
      {failed && <p>Upgrade failed — try again.</p>}
    </>
  );
}

There is no browser window on React Native, so useUpgradePopup runs the app in the system auth session the SDK already uses for native OAuth. The app returns to your configured deep link, and the outcome is parsed from the callback URL (refreshing the session on success). This requires the same client configuration native social sign-in needs — metadata.nativeLink and coreConfig.openAuthSession must be set. The hook exposes the same result / error values as on web.

import { useUpgradePopup } from '@dynamic-labs-sdk/legacy-embedded-wallet-upgrade/react';

// Requires metadata.nativeLink + coreConfig.openAuthSession on the client.
function UpgradeButton() {
  const { open, result, error } = useUpgradePopup();

  if (result?.status === 'success') {
    // The session was already refreshed for you.
    return <Text>Wallet upgraded.</Text>;
  }

  // error is set when the user dismisses the auth session; result.status
  // 'error' covers a failed upgrade.
  const failed = error !== undefined || result?.status === 'error';

  return (
    <>
      <Button title="Upgrade wallet" onPress={open} />
      {failed && <Text>Upgrade failed — try again.</Text>}
    </>
  );
}

The redirectUrl defaults to metadata.nativeLink. Pass an explicit redirectUrl only if you want to return to a different registered deep link.

Handling errors

Situation	What to do
Popup rejected with `UpgradePopupBlockedError`	The browser blocked the popup — open it synchronously from a click handler, with no `await` before the call.
Popup rejected with `UpgradePopupClosedError`	The user closed the popup / dismissed the auth session before finishing — offer a retry.
Outcome `status` is `error`	The upgrade failed or was cancelled — offer a retry.

Installation & Configuration

Chains & Networks

Authenticate

User & Session Management

Wallets

Flow

Swaps

Funding & Onramp

Events

Building UI

Migrating from React

Upgrade by popup

Handling errors

See also

​Handling errors

​See also

Handling errors

See also