Usage

Import the package:

import "package:reown_appkit/reown_appkit.dart";

Create your ReownAppKitModal() instance, which is your primary class for opening, closing, disconnecting, etc.

Be sure to update the project ID and metadata with your own.

Don't have a project ID?

Head over to Reown Dashboard and create a new project.

Initialization

In order to initialize ReownAppKitModal() instance you must provide a projectId and a metadata.

// AppKit Modal instance
final _appKitModal = ReownAppKitModal(
  context: context, // required BuildContext
  projectId: '{YOUR_PROJECT_ID}',
  metadata: const PairingMetadata(
    name: 'Example App',
    description: 'Example app description',
    url: 'https://example.com/',
    icons: ['https://example.com/logo.png'],
    redirect: Redirect(
      native: 'exampleapp://',
      universal: 'https://reown.com/exampleapp',
      linkMode: true|false,
    ),
  ),
  enableAnalytics: true,
  siweConfig: SIWEConfig(...),
  featuresConfig: FeaturesConfig(...),
  getBalanceFallback: () async {},
  disconnectOnDispose: true|false,
  customWallets: [
    ReownAppKitModalWalletInfo(
      listing: AppKitModalWalletListing(
        ...
      ),
    ),
  ],
);

// Register here the event callbacks on the service you'd like to use. See `Events` section.

await _appKitModal.init();

Alternatively, ReownAppKitModal() allows you to create an instance by passing a ReownAppKit() object as follows:

// AppKit instance
final appKit = ReownAppKit.createInstance(
  projectId: '{YOUR_PROJECT_ID}',
  metadata: const PairingMetadata(
    name: 'Example App',
    description: 'Example app description',
    url: 'https://example.com/',
    icons: ['https://example.com/logo.png'],
    redirect: Redirect(
      native: 'exampleapp://',
      universal: 'https://reown.com/exampleapp',
      linkMode: true|false,
    ),
  ),
);

// AppKit Modal instance
final _appKitModal = ReownAppKitModal(
  context: context, // required BuildContext
  appKit: appKit,
);

// Register here the event callbacks on the service you'd like to use. See `Events` section.

await _appKitModal.init();

The metadata object should contain your dApp’s name, description, url and icon. Redirect object is optional but highly recommended. See next session why.

Redirect to your dApp

AppKit’s metadata object contains a redirect option that should be used by the wallet to redirect back to your dapp after connection.

redirect: Redirect(
  // your own custom scheme for deep linking
  native: 'exampleapp://',
  // your own universal link for deep linking, required if you are going to use Link Mode
  universal: 'https://reown.com/exampleapp',
  // enable or disable relay-less communication, see `Link Mode` section
  // won't be used if you decide to support/include non-EVM blockchains
  linkMode: true|false,
),

native: value must be a valid URI scheme: https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Schemes#syntax

But in order for the redirect mechanism to work, you would also need to add the following in the iOS and Android native sides:

iOS

1. Locate your Info.plist file under your_project/ios/Runner/ folder.
2. Locate the <key>CFBundleURLTypes</key> section.
3. Add your schema as <dict> entry within the <array> object as follows.

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleTypeRole</key>
    <string>Editor</string>
    <key>CFBundleURLName</key>
    <string>com.example.yourBundleId</string> <!-- Bundle ID of your app -->
    <key>CFBundleURLSchemes</key>
    <array>
      <!-- your own custom scheme -->
      <!-- Should be the same you set on Redirect.native on Flutter side -->
      <!-- Be mind of removing :// for this step -->
      <string>exampleapp</string>
    </array>
  </dict>
</array>

Android

1. Locate your AndroidManifest.xml file under your_project/android/app/src/main/ folder.
2. Locate the <Activity .MainActivity inside the <application /> scope.
3. Add the following intent

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <!-- your own custom scheme -->
    <!-- Should be the same you set on Redirect.native on Flutter side -->
    <!-- Be mind of removing :// for this step -->
    <data android:scheme="exampleapp" />
</intent-filter>

If you encounter any issues with your deep linking navigation, especially after upgrading to Flutter 3.27 or later, we kindly encourage you to disable Flutter built-in deep-linking feature as it’s been set to true by default, introducing a breaking change: https://docs.flutter.dev/release/breaking-changes/deep-links-flag-change

So below your <intent-filter>, you would add this:

<meta-data android:name="flutter_deeplinking_enabled" android:value="false" />

Available Buttons

AppKitModalConnectButton to open the modal and connect to a wallet or through social options

AppKitModalConnectButton(appKit: _appKitModal)

AppKitModalNetworkSelectButton to select an available network

AppKitModalNetworkSelectButton(appKit: _appKitModal)

AppKitModalAccountButton to open account screen once connected

AppKitModalAccountButton(appKitModal: _appKitModal)

AppKitModalAddressButton shows the address on the current selected network

AppKitModalAddressButton(appKitModal: _appKitModal)

AppKitModalBalanceButton shows wallet balance on the current selected network

AppKitModalBalanceButton(appKitModal: _appKitModal)

To connect to a wallet, you can either use AppKitModalConnectButton or AppKitModalNetworkSelectButton.

AppKitModalNetworkSelectButton will allow the user to pre-select a network before connecting while AppKitModalConnectButton will directly show available wallets and social options.

Once connected, AppKitModalConnectButton will serve as a Disconnect button while AppKitModalAccountButton will show basic account data such as balance and address and will be used to open the Account screen.

Quick example:

Column(
  mainAxisAlignment: MainAxisAlignment.center,
  children: [
    AppKitModalNetworkSelectButton(appKit: _appKitModal),
    AppKitModalConnectButton(appKit: _appKitModal),
    Visibility(
      visible: _appKitModal.isConnected,
      child: AppKitModalAccountButton(appKit: _appKitModal),
    )
  ],
),

AppKitModalAccountButton is composed of AppKitModalBalanceButton and AppKitModalAddressButton, and you can use these separately from AppKitModalAccountButton

AppKitModalBalanceButton(appKitModal: _appKitModal, onTap: _appKitModal.openModalView);

AppKitModalAddressButton(appKitModal: _appKitModal, onTap: _appKitModal.openModalView);

Custom Buttons

If you’d like, you can also override AppKit’s buttons by using the custom: property as follows

AppKitModalConnectButton(
  appKit: _appKitModal,
  custom: MyCustomButton(
    onPressed: () {
      _appKitModal.openModalView();
    },
    child: const Text('CONNECT WALLET'),
  ),
),

openModalView() method can accept a “startWidget” argument that you can leverage to open specifics screens of the modal:

// With no options will open default screen depending on the connection status
_appKitModal.openModalView();

// Will open Network Selection screen independently of the connection status
// This option is not needed if you use AppKitModalNetworkSelectButton()
_appKitModal.openModalView(ReownAppKitModalSelectNetworkPage());

// Will open QR Code screen for connection.
// Will work only if not yet connected.
_appKitModal.openModalView(ReownAppKitModalQRCodePage());

// Will open All Wallets screen for connection
// Will work only if not yet connected.
_appKitModal.openModalView(ReownAppKitModalAllWalletsPage());