Skip to main content

Particle Auth for Flutter

The Particle Auth Flutter SDK enables full-stack integration of Particle Auth into applications built on Flutter. This includes everything from the initial configuration of Particle’s Wallet-as-a-Service to specific interactions. In this case, Flutter can be leveraged in either Android or iOS environments, both to the same degree. This is done primarily through Dart.
Platform-specific configuration instructions, alongside examples of utilization, can be found below.

Getting Started

Interaction with the Particle Auth Flutter SDK follows a standard approach consistent with other Particle Auth SDKs, though notable differences exist within the configuration process.
The configuration process for this SDK varies significantly depending on whether you’re using Flutter for Android or iOS.
To begin, you’ll need to head over to the Particle dashboard and retrieve your projectId, clientKey, and appId.
Find a full rundown in the Dashboard Guide

Adding the Particle Auth Flutter SDK to your application

Additionally, regardless of platform, you’ll need to begin by adding particle_auth_core to your Flutter application; this is a requirement before moving onto platform-specific configuration.
Terminal

Android configuration

Prerequisites

  • minSdkVersion 23 or higher.
  • compileSdkVersion, targetSdkVersion 34 or higher.
  • JavaVersion 17.
  • Jetpack (AndroidX).
  • Android Gradle Plugin Version : 8.5.1 or higher.
  • Gradle Version : 8.9 or higher.
If you’re building an Android application with Flutter, follow the steps below to configure Particle Auth. To begin, you’ll need to go ahead and open your build.gradle file, often found at the following file path: ${project name}/android/app/build.gradle Within your build.gradle file, you’ll need to add four new lines to ensure Particle Auth runs appropriately:
  1. minSdkVersion, which in most cases will be set to 23.
  2. manifestPlaceholders["PN_PROJECT_ID"], the projectId previously retrieved from the Particle dashboard.
  3. manifestPlaceholders["PN_PROJECT_CLIENT_KEY"], the clientKey previously retrieved from the Particle dashboard.
  4. manifestPlaceholders["PN_APP_ID"], the appId previously retrieved from the Particle dashboard.
build.gradle
Staying within your build.gradle file, you’ll need to ensure that you’re using version 17 of Java in both compileOptions and kotlinOptions, alongside enabling dataBinding.
build.gradle
Finally, for dependency management, within build.gradle you’ll need to ensure that the repositories object in both buildscript and allprojects has maven { setUrl("https://jitpack.io") } present, such as is shown below.
build.gradle

iOS configuration

If you’re building an iOS application with Flutter, this also entails a unique and iOS-specific configuration process. Before beginning, ensure your project meets the following prerequisites:
  • Xcode 15.0 or later.
  • iOS 14 or later.
With these requirements set, you’ll need to open an exported iOS project and find apps/{project name}.xcworkspace. At the root of your Xcode project, create a new file, ParticleNetwork-Info.plist. Ensure this is marked under Target Membership. Now, with a fresh ParticleNetwork-Info.plist file, go ahead and fill it in with the following:
ParticleNetwork-Info.plist
Similar to the Android configuration, you’ll need to fill in PROJECT_UUID (projectId), PROJECT_CLIENT_KEY, and PROJECT_APP_UUID (appId) with the corresponding values retrieved from the Particle dashboard. To enable Face ID for your app, add a usage description to your Info.plist file by including the following code:
Info.plist
Finally, you’ll need to edit your Podfile to ensure particle_auth_core is properly imported. Head over to the linked guide to complete this, if you haven’t already.

Another important note before continuing.

Our SDK is a static library (XCFramework). When using the Particle Auth Flutter SDK, you’ll need to specify that you’re using a static framework through the following:


Examples of utilization

Initialization

Before using the full extent of the SDK, you’ll need to initialize it with init, passing in the specific chain to which you intend to primarily onboard within Particle’s Wallet-as-a-Service. This is represented as an object containing chain info (often derived from ChainInfo.{Chain}).

Connect

After installing, configuring, and initializing Particle Auth, initiate the login process by using ParticleAuthCore.connect. This triggers a social login prompt, and upon successful authentication, a user account is created, unlocking the full SDK functionality. ParticleAuthCore.connect takes the following parameters:
You can use your existing user base (account system) or a custom authentication method with Particle Connect through JWT. Click here to learn how to configure JWT.

Is Connected

There may be scenarios where it is important to know whether a current session (a user) is logged in with Particle Auth. This is achieved through ParticleAuthCore.isConnected (server-side check).

Disconnect

To exit an existing session (logging a user out), call ParticleAuthCore.disconnect.

Get User Info

To retrieve an object containing detailed user information, call ParticleAuthCore.getUserInfo.

Get Address

To retrieve the address, call Evm.getAddress or Solana.getAddress.

Sign Message (EIP191)

To request an EIP191 signature from a user’s embedded wallet, you can use either the Evm.personalSign or Evm.personalSignUnique method. If you need the same message to return a unique signature each time, use the Evm.personalSignUnique method. Otherwise, the Evm.personalSign method is generally recommended. On Solana, you can call Solana.signMessage, you can pass in a UTF-8/readable string.

Sign Transaction

This is a Solana-specific method for signing a transaction without sending it. Similar to message signing, this will prompt a signature in-UI with details about the transaction. Programmatically, the proposed transaction should be formatted as a (converted to a) base58 string. Passing in an object directly will not work in this case.

Sign All Transactions

Following the method above, you can use Solana.signAllTransactions to propose a collection of Solana transactions for signature, rather than just a single transaction.

Sign and Send Transaction

For more generalized transaction execution, Evm.sendTransaction and sendTransactionandSolana.signAndSendTransaction` will be the primary methods used in virtually every scenario. This will propose a signature (on both EVM and Solana) and then immediately push it to the network once confirmed.

Sign Typed Data V4 (EIP712)

To request an EIP712 signature from a user’s embedded wallet, you can use the Evm.signTypedData or Evm.signTypedDataUnique method. If you need the same message to return a unique signature each time, use the Evm.signTypedDataUnique method. Otherwise, the Evm.signTypedData method is generally recommended.

Set Chain Info

To change the chain after it’s initially defined in init, you can use ParticleBase.setChainInfo for a synchronous update or ParticleAuthCore.switchChain for an asynchronous update, both typically using ChainInfo.{Chain}.

Get Chain Info

To retrieve the currently selected (primary) chain in an active session, use ParticleBase.getChainInfo. This returns a ChainInfo object containing:
  • name: The chain’s name (e.g., Ethereum).
  • id: The ID of the chain (e.g., 11155111).
  • network: The specific network associated with the chain ID (e.g., Sepolia).

Set Security Account Config

Another important component of integrating the Particle Auth SDK (Wallet-as-a-Service) is the (optional) security account requirements enforced upon application users. For all Particle accounts, various security options are available, including:
  • Master Password: A non-recoverable password required upon login.
  • Payment Password: A PIN required for transaction signatures.
With the SDK, you can determine how often a user is prompted to configure their security settings. This control is facilitated by ParticleBase.setSecurityAccountConfig, where you pass in a SecurityAccountConfig object with two parameters:
  • 0 means a prompt is never shown requesting this setting.
  • 1 means a prompt is shown only upon the first startup.
  • 2 means a prompt is shown every time.
  • 3 means force set payment password before sign.

Open Account and Security Page

Following the above, if you’d like to force the opening of account/security settings (in-UI), you can do so with ParticleAuthCore.openAccountAndSecurity.

Has Master Password, Payment Password, Security Account

Similarly to the isConnected function covered prior, there are various scenarios in which knowing whether or not a user has specific security settings enabled may be useful. In the case of the Particle Auth Flutter SDK, this can happen in one of two ways: With the built-in ParticleAuthCore.hasMasterPassword, ParticleAuthCore.hasPaymentPassword, and ParticleAuthCore.changeMasterPassword methods.

Set Appearance

You can forcibly set a specific appearance within the UI using ParticleBase.setAppearance. By default, it will follow the current system setting.

Set and Get Language

You can forcibly set a specific language to be used within the UI using ParticleBase.setLanguage, with the retrieval of the currently active language facilitated by ParticleBase.getLanguage. By default, this is set to English.

Blind Sign Enable

Silently sign messages/transactions, this switch will work if the following conditions are met:
  1. your account is connected with JWT
  2. your account does not set payment password
  3. SecurityAccountConfig.promptSettingWhenSign is 0, you can call ParticleBase.setSecurityAccountConfig to update its value.

Filter Unsupported Countries (Phone Authentication)

If necessary, you can restrict specific countries from authenticating via phone number; upon entering a phone number originating from a country specified here, the login modal will block the user.

EvmService utilization examples

In addition to ParticleAuthCore for authentication and interaction with Particle’s Wallet-as-a-Service, the Flutter SDK also includes a class, EvmService, for general interaction with EVM chains.

Write Contract

EvmService.writeContract allows you to execute a write contract call defined by a specific method and set of parameters. This requires a corresponding ABI, contract address, and requester public address.

Read Contract

EvmService.readContract allows you to execute a read-only contract call defined by a specific method and set of parameters. This requires a corresponding ABI, contract address, and requester public address.

Create Transaction

EvmService.createTransaction facilitates the construction of a transaction object derived from the standard from, to (receiver in this example), amount (value), and data fields. This transaction, once constructed with EvmService.createTransaction, can be passed for in-UI proposal with ParticleAuthCore.sendTransaction.

Estimate Gas

Given a standard transaction structure (a detached set of values as shown below), you can estimate the gas consumption for a specified transaction using the EvmService.ethEstimateGas method. This acts as a wrapper for eth_estimateGas to simulate and retrieve the estimated gas required.

Get Suggested Gas Fees

To retrieve categorized gas price suggestions (3 categories scaling from low to high) based upon current network conditions, you can call EvmService.suggestedGasFees.

Get Tokens and NFTs

EvmService also extends to Data API methods such as getTokensAndNFTs, which returns a highly detailed JSON list of ERC20 tokens and ERC721 NFTs belonging to a specified address. This is accessible through EvmService.getTokensAndNFTs, passing in the public address to retrieve the tokens and NFTs. Also, you can retrieve tokens from getTokens or NFTs from getNFTs

Get Transactions by Address

Similar to the former method, EvmService.getTransactionsByAddress enables the retrieval of a detailed JSON response containing a complete list of transactions involving a specified address.

Get Price

To retrieve the price of specific tokens, call EvmService.getPrice.

Basic RPC Method

You can call any basic EVM RPC method through EvmService.rpc

SolanaService utilization examples

In addition to ParticleAuth for authentication and interaction with Particle’s Wallet-as-a-Service, the Flutter SDK also includes a class, SolanaService, for general interaction with Solana chains.

Get Tokens and NFTs

SolanaService also extends to Data API methods such as getTokensAndNFTs, which returns a highly detailed JSON list of SPL tokens and NFTs belonging to a specified address. This is accessible through SolanaService.getTokensAndNFTs, passing in the public address to retrieve the tokens and NFTs of.

Serialize Transactions

SolanaService.serializeSolTransaction facilitates the construction of a SOL transaction object, SolanaService.serializeSplTokenTransaction facilitates the construction of a Spl-token transaction object, SolanaService.serializeWSolTokenTransaction facilitates the construction of a unwrap WSOL transaction object. These transactions, once constructed, can be passed for in-UI proposal with Solana.signAndSendTransaction.

Get Price

To retrieve the price of specific tokens, call SolanaService.getPrice.

Get Transactions by address

To retrieve transactions executed by a specific a address, call SolanaService.getTransactionsByAddress.

Get Token by Token Address

To obtain the balance of a specific token at a given address, call SolanaService.getTokenByTokenAddresses

Basic RPC Method

Any basic Solana RPC method can be called through SolanaService.rpc.