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. To begin, you’ll need to head over to the Particle dashboard and retrieve yourprojectId, 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 addingparticle_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.
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:
minSdkVersion, which in most cases will be set to23.manifestPlaceholders["PN_PROJECT_ID"], theprojectIdpreviously retrieved from the Particle dashboard.manifestPlaceholders["PN_PROJECT_CLIENT_KEY"], theclientKeypreviously retrieved from the Particle dashboard.manifestPlaceholders["PN_APP_ID"], theappIdpreviously retrieved from the Particle dashboard.
build.gradle
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
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.
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
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
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 withinit, 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 usingParticleAuthCore.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:
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 throughParticleAuthCore.isConnected (server-side check).
Disconnect
To exit an existing session (logging a user out), callParticleAuthCore.disconnect.
Get User Info
To retrieve an object containing detailed user information, callParticleAuthCore.getUserInfo.
Get Address
To retrieve the address, callEvm.getAddress or Solana.getAddress.
Sign Message (EIP191)
To request an EIP191 signature from a user’s embedded wallet, you can use either theEvm.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 useSolana.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 theEvm.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 ininit, 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, useParticleBase.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.
ParticleBase.setSecurityAccountConfig, where you pass in a SecurityAccountConfig object with two parameters:
0means a prompt is never shown requesting this setting.1means a prompt is shown only upon the first startup.2means a prompt is shown every time.3means 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 withParticleAuthCore.openAccountAndSecurity.
Has Master Password, Payment Password, Security Account
Similarly to theisConnected 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 usingParticleBase.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 usingParticleBase.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:- your account is connected with JWT
- your account does not set payment password
- SecurityAccountConfig.promptSettingWhenSign is 0, you can call
ParticleBase.setSecurityAccountConfigto 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 theEvmService.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 callEvmService.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, callEvmService.getPrice.
Basic RPC Method
You can call any basic EVM RPC method throughEvmService.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, callSolanaService.getPrice.
Get Transactions by address
To retrieve transactions executed by a specific a address, callSolanaService.getTransactionsByAddress.
Get Token by Token Address
To obtain the balance of a specific token at a given address, callSolanaService.getTokenByTokenAddresses
Basic RPC Method
Any basic Solana RPC method can be called throughSolanaService.rpc.
