JavaScript SDK options

The JavaScript version of MetaMask SDK takes the following options.

checkInstallationImmediately

Syntax

checkInstallationImmediately: <boolean>

Example

checkInstallationImmediately: true

Enables or disables immediately checking if MetaMask is installed on the user's browser. If true, the SDK checks for installation upon page load and sends a connection request, prompting the user to install MetaMask if it's not already installed. If false, the SDK waits for the connect method to be called to check for installation.

The default is false.

checkInstallationOnAllCalls

Syntax

checkInstallationOnAllCalls: <boolean>

Example

checkInstallationOnAllCalls: true

Enables or disables checking if MetaMask is installed on the user's browser before each RPC request. The default is false.

communicationLayerPreference

Syntax

communicationLayerPreference: <type>

Example

communicationLayerPreference: SOCKET

The preferred communication layer to use. The default and only option is SOCKET for Socket.IO.

communicationServerUrl

Syntax

communicationServerUrl: <string>

Example

communicationServerUrl: "https://metamask-sdk-socket.metafi.codefi.network/"

The URL of the communication server to use. This option is mainly used for debugging and testing the SDK.

dappMetadata

Syntax

dappMetadata: {
  name: <string>,
  url: <string>,
  base64Icon: <string>,
}

Example

dappMetadata: {
  name: "My Dapp",
  url: "https://mydapp.com",
  base64Icon: "data:image/png;base64,...",
}

Metadata about the dapp using the SDK. The metadata options are:

• name - Name of the dapp
• url - URL of the dapp
• base64Icon - A base64-encoded icon

important

Setting dappMetaData creates a clear and trustworthy user experience when connecting your dapp to MetaMask Mobile. MetaMask Mobile displays this metadata in the connection modal to help users identify and verify the connection request.

defaultReadOnlyChainId

Syntax

defaultReadOnlyChainId: <number or hexadecimal string>

Example

defaultReadOnlyChainId: "0x1"

Enables sending read-only RPC requests to this chain ID before the user connects to MetaMask. The value is automatically updated to the chain ID used in MetaMask once connected.

enableDebug

Syntax

enableDebug: <boolean>

Example

enableDebug: false

Enables or disables sending anonymous analytics to MetaMask to help improve the SDK. The default is true.

extensionOnly

Syntax

extensionOnly: <boolean>

Example

extensionOnly: true

Enables or disables automatically using the MetaMask browser extension if it's detected. The default is true.

infuraAPIKey

Syntax

infuraAPIKey: <string>

Example

infuraAPIKey: process.env.INFURA_API_KEY

The Infura API key to use for RPC requests. Configure this option to make read-only RPC requests from your dapp.

important

Use Infura allowlists to protect against other people submitting requests to your API key. You can restrict interactions to specific addresses, origins, user agents, and request methods. We recommend using all allowlist options to maximize the security of your API key and dapp.

modals

Syntax

modals: <object>

Example

modals: {
  onPendingModalDisconnect: () => {
    // Custom logic for pending modal disconnect.
  },
  install: (params) => {
    // Custom install modal logic.
    const { link, debug, installer, terminate, connectWithExtension } = params;
    return {
      mount: (link) => { /* Custom mount logic */ },
      unmount: (shouldTerminate) => { /* Custom unmount logic */ },
    };
  },
  otp: ({ debug, onDisconnect }) => {
    // Custom OTP modal logic.
    return {
      mount: () => { /* Custom mount logic */ },
      updateOTPValue: (otpValue) => { /* Custom OTP value update logic */ },
      unmount: () => { /* Custom unmount logic */ },
    };
  },
}

An object that allows you to customize the logic and UI of the displayed modals. This is useful if your dapp requires a custom way to handle connection and reconnection scenarios.

openDeeplink

Syntax

openDeeplink: <function>

Example

openDeeplink: (link: string) => {
  if (canOpenLink) {
    Linking.openURL(link);
  }
}

A function that is called to open a deeplink to the MetaMask Mobile app.

preferDesktop

Syntax

preferDesktop: <boolean>

Example

preferDesktop: true

When set to true, the MetaMask browser extension is displayed as the default option in the SDK connection modal. When set to false, MetaMask Mobile is displayed as the default option. The default is false.

readonlyRPCMap

Syntax

readonlyRPCMap: <map>

Example

readonlyRPCMap: {
  "0x539": "http://localhost:8545",
}

A map of RPC URLs to use for read-only RPC requests.

shouldShimWeb3

Syntax

shouldShimWeb3: <boolean>

Example

shouldShimWeb3: false

Enables or disables shimming the window.web3 object with the Ethereum provider returned by the SDK (useful for compatibility with older browsers). The default is true.

timer

Example

timer: BackgroundTimer

Used by React Native dapps to keep the dapp alive while using react-native-background-timer.

transports

Syntax

transports: <array of strings>

Example

transports: ["websocket", "polling"]

Sets the preference on Socket.IO transports.

ui

Syntax

ui: {
  installer: <function>,
  confirm: <function>,
}

Options for customizing the SDK UI.

useDeeplink

Syntax

useDeeplink: <boolean>

Example

useDeeplink: true

Enables or disables using deeplinks to connect with MetaMask Mobile. If false, the SDK uses universal links instead. The default is false.

wakeLockType

Syntax

wakeLockType: <type>

Example

wakeLockType: Temporary

The type of wake lock to use when the SDK is running in the background. Options are Disabled, Temporary, and UntilResponse.