Fix browser popup blocking by adding popup-safe connection methods

[Copilot]

Problem

The connect() method in IdentityKitWeb performs an async operation before calling window.open(), which can cause browsers to block the popup due to broken user activation chain:

async connect(): Promise<void> {
  const idFragment = this.generateIdFragment();
  
  // This await operation breaks the user activation chain
  const { url } = await this.deepLinkManager.buildAddKeyUrl({ 
    cadopDomain: this.cadopDomain,
    idFragment,
  });
  
  window.open(url, "_blank"); // ❌ May be blocked by browser
}

Modern browsers require window.open() to be called in direct response to user actions without intervening async operations.

Solution

Added two new methods to IdentityKitWeb class that separate URL building from window opening:

• buildConnectUrl(): Pre-builds the connection URL (can be called ahead of time)
• openConnectUrl(url): Opens the URL immediately (call in direct response to user action)

Usage with React Hook

import { useIdentityKit } from '@nuwa-ai/identity-kit-web';

function ConnectButton() {
  const { state, buildConnectUrl, openConnectUrl } = useIdentityKit();
  const [connectUrl, setConnectUrl] = useState(null);

  // Pre-build URL when component mounts
  useEffect(() => {
    if (!state.isConnected && !connectUrl) {
      buildConnectUrl().then(setConnectUrl);
    }
  }, [state.isConnected, connectUrl, buildConnectUrl]);

  // Handle click - no async operations, popup won't be blocked
  const handleConnect = () => {
    if (connectUrl) {
      openConnectUrl(connectUrl);
      setConnectUrl(null); // Clear for next use
    }
  };

  return (
    <button onClick={handleConnect} disabled={!connectUrl}>
      Sign-in with DID
    </button>
  );
}

Usage with SDK Directly

const sdk = await IdentityKitWeb.init();

// Pre-build URL
const connectUrl = await sdk.buildConnectUrl();

// Later, in user action handler
document.getElementById('connect-btn').addEventListener('click', () => {
  sdk.openConnectUrl(connectUrl); // ✅ Won't be blocked
});

Changes Made

1. Core SDK Methods:

   • Added buildConnectUrl() method to IdentityKitWeb class
   • Added openConnectUrl() method to IdentityKitWeb class

2. React Hook Integration:

   • Updated IdentityKitHook interface to include new methods
   • Implemented new methods in useIdentityKit hook

3. Documentation & Examples:

   • Updated README with popup-safe usage patterns
   • Created comprehensive examples showing different approaches
   • Added interactive demo showing the difference between methods

4. Testing:

   • Added test suite covering new functionality
   • Verified backward compatibility is maintained

Benefits

• ✅ Prevents popup blocking - No async operations between user action and window.open()
• ✅ Backward compatible - Original connect() method still works
• ✅ Flexible patterns - Multiple ways to implement based on needs
• ✅ Better UX - Users won't encounter blocked popups

Demo

The demo shows both the legacy approach (which may be blocked) and the new popup-safe approach working correctly.

Fixes #224.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[cloudflare-workers-and-pages]

Deploying id-nuwa with    Cloudflare Pages

Latest commit:	b127660
Status:	✅  Deploy successful!
Preview URL:	https://1908071e.id-nuwa.pages.dev
Branch Preview URL:	https://copilot-fix-224.id-nuwa.pages.dev

View logs

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
nuwa-docs	❌ Failed (Inspect)			Jul 7, 2025 8:11am

[cloudflare-workers-and-pages]

Deploying nuwa-login-demo with    Cloudflare Pages

Latest commit:	1dc43a8
Status:	✅  Deploy successful!
Preview URL:	https://9b09da9a.nuwa-login-demo.pages.dev
Branch Preview URL:	https://copilot-fix-224.nuwa-login-demo.pages.dev

View logs

[Mine77]

no need to expose the openConnectUrl method. let client get the url and handle the pop-up trigger accordingly for browser compatibilities.