Detecting the Provider

To determine if a user has StarKey installed, a web application should check for the presence of the starkey object on window. StarKey’s browser extension injects this object into the top-level document of any http:// or https:// page.

The provider is not injected when the document isn’t HTML (a non-html doctype or root element) or when the URL path ends in .xml or .pdf.

Third-party iframes do not receive the provider. StarKey injects a limited bridge into an iframe only when the top-level page is one of its own allow-listed origins, so a dApp embedded in someone else’s page cannot reach the wallet. Run wallet interactions from the top-level document.

For the Supra network specifically, the provider is namespaced at window.starkey.supra, so a dApp should check for that path rather than assuming the top-level starkey object exposes Supra methods directly:

const getProvider = () => {
  if ('starkey' in window) {
    const provider = window.starkey?.supra
 
    if (provider) {
      return provider
    }
  }
 
  window.open('https://starkey.app/', '_blank')
}

If window.starkey.supra is present, the dApp can proceed to establish a connection. If it isn’t, redirect the user to install StarKey, as shown above.

Polling for late injection

The extension injects window.starkey asynchronously after page load, so a single synchronous check can run before it exists. Poll on an interval and give up after a timeout instead:

const checkIsExtensionInstalled = (): void => {
  const intervalId = setInterval(() => {
    if (window?.starkey) {
      clearInterval(intervalId)
      setIsExtensionInstalled(true)
    }
  }, 500)
 
  setTimeout(() => clearInterval(intervalId), 5000)
}

First-time install event

When a user installs the StarKey extension while your dApp tab is already open, StarKey fires a one-time starkey-extension-installed message event on window (separate from provider.on, see Events):

function handleExtensionEvents(event: MessageEvent): void {
  if (event?.data?.name === 'starkey-extension-installed') {
    window.removeEventListener('message', handleExtensionEvents)
    alert('StarKey extension has been installed. Please reload the page to continue.')
  }
}
 
window.addEventListener('message', handleExtensionEvents)

Mobile vs. desktop install prompt

If StarKey isn’t detected, send the user to the right install surface based on device:

• Mobile — deep-link into the StarKey dApp browser: https://starkey.app/dApps?url=<encoded current URL>.
• Desktop — link to the StarKey Chrome extension  in the Chrome Web Store.

Related pages

• Establish a Connection
• Events