Keep one IllyVoIP SDK phone owner across browser tabs

If several tabs of your application can create an IllyVoIP phone, give one tab ownership before initialization. A same-origin Web Lock can coordinate those tabs. It does not control another browser profile, device, website or a user’s server-side permission.

This guide targets the official Webphone SDK 1.4.2 browser distribution. Start with the installation guide, one managed phone owner and an authenticated backend that authorizes the user’s SIP identity. Keep permanent API keys and SIP passwords out of browser code.

1. Choose a stable ownership scope

Derive a stable opaque lock name from your authenticated application account and permitted SIP identity. Tabs for the same calling identity must derive the same name. Do not put API keys or telephone numbers in it. Keep the backend identity check even when the browser lock succeeds.

If Web Locks is unavailable, keep calling disabled with a clear explanation or use a separately reviewed coordination design. A localStorage flag alone is not an atomic lock. Do not use the steal option to take over a tab that may be handling a call.

2. Hold the lock for the whole owner lifetime

The following helper owns coordination only. create must create an idle SDK with autoConnect and autoRegister false. use owns the user-triggered connection UI and resolves only after its deliberate stop policy permits cleanup. It must not resolve merely because a route rerendered.

export async function withPhoneOwner({ key, create, use, report }) {
  if (!navigator.locks) throw new Error('Tab ownership is unavailable');
  return navigator.locks.request(key, { ifAvailable: true }, async lock => {
    if (!lock) return { acquired: false };
    let phone;
    try {
      phone = await create();
      await use(phone);
    } finally {
      if (phone) {
        try { await phone.destroy(); }
        catch (error) {
          // Keep ownership while cleanup remains uncertain.
          try { report(error); } catch (_) {}
          await new Promise(() => {});
        }
      }
    }
    return { acquired: true };
  });
}

The callback’s unresolved promise keeps the lock held. A second tab using ifAvailable receives no lock and must show a secondary-tab state without creating a phone. A failed destroy deliberately leaves this helper pending; show that failure and require an orderly application recovery, not another automatic registration.

3. Connect through the owning tab’s UI

1. Acquire ownership before creating the SDK.
2. Show a clear Enable phone control in that tab and handle its connect/register promises.
3. In other tabs, show that calling is owned elsewhere and leave customer records usable as appropriate.
4. Keep the owner through active calls, background route changes and the intended session lifetime.

Browser audio policies still apply. Acquiring a lock is not user activation and does not grant microphone permission. Do not start ringing audio or a paid call just to prove that ownership was acquired.

4. Stop without racing another tab

1. Block new call actions before logout or an identity change.
2. Apply the application’s policy for an existing call; do not silently cut it off because a second tab opened.
3. Dispose owner subscriptions and complete SDK cleanup.
4. Release ownership only after cleanup succeeds.
5. Let another tab make a fresh deliberate ownership request rather than assuming an old denied request became an owner.

Closing or crashing a tab releases browser-held resources, but it does not prove the server instantly forgot the earlier registration. A newly eligible tab still needs normal connection and session-conflict handling. Never treat lock acquisition as proof that a previous live call was ended correctly.

5. Verify concurrency before deployment

Use two same-origin test tabs and a mocked phone first. Test simultaneous attempts, delayed initialization, user stop, failed cleanup and a closed owner tab. Confirm the secondary tab never invokes create while another holds the lock. Then test normal login/logout and authorized calling in the target browsers. Keep browser coordination results separate from telephony acceptance.

Related guides

• Add browser calling with the Webphone SDK
• Manage the IllyVoIP WebRTC Phone SDK lifecycle in React
• Troubleshoot the webphone

Reference

Current instructions and technical reference: MDN: Web Locks API, W3C Web Locks specification.

Reviewed 12 October 2026 against the current IllyVoIP controls, implementation and applicable references. Available options depend on account permissions and service state.