Unity (C#) - Connect

​

Particle Connect for Unity

Particle Connect acts as a central wallet connection mechanism within games built on Unity.

With it, you can onboard users into a functional account through social logins (via Particle Auth) or typical Web3 wallets (via WalletConnect, Solana’s wallet-adapter, or private key imports). This creates a Web2-adjacent login experience while retaining unified compatibility with existing popular Web3 wallets.

Particle Connect has a dedicated Unity SDK for integration; the configuration process and examples of utilization are outlined below.

​

Repository

Before diving in, all of the Particle Network Unity SDKs (for Particle Auth and Particle Connect) are publicly available and viewable through the official repository. Feel free to look at the underlying architecture and demos showcasing end-to-end implementation to gain an initial understanding of working with Particle Connect on Unity.

​

Getting Started

​

Prerequisites

Your Unity project must meet several requirements to avoid compatibility issues. These requirements will be, in some capacity, dependent on the platform that you’ve decided to use. They are as follows:

• Unity 2022.3.43f1 or higher.
• If you’re using iOS:
  • Xcode 15.0 or higher.
  • CocoaPods 1.14.3 or higher.
  • iOS 14 or higher.
• If you’re using Android:
  • 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.

​

Setting up the Particle dashboard

Once you’ve ensured that your project meets the above prerequisites, you’ll also need three key values from the Particle dashboard: your projectId, clientKey, and appId.

These connect your Unity project directly with the Particle dashboard, enabling customization, analytics, tracking, etc.

​

Configuration

With these values in hand, you can move on to initial configuration and dependency management, which will vary in complexity depending on the platform used. To begin, for both iOS and Android, you’ll need to download and install the Particle Unity package, which will include the necessary files for both Particle Connect and Particle Auth.

Head over to the GitHub repository, and download the latest release (.unitypackage), then import this into your project.

​

iOS configuration

If you’re building a Unity game on iOS, you must follow a specific configuration process to ensure that Particle Connect functions. The first step within this process is to set up a scheme URL within the Unity editor.

1. Head into the iOS Player Settings menu (Edit -> Project Settings -> Player Settings -> iOS).
2. From here, select Other, then scroll down to Configuration.
3. Open the Supported URL schemes section, and within the Element 0 field, paste in your projectId with a prefix of pn.
   1. For example, if your projectId (from the Particle dashboard) is something like 63bfa427-cf5f-4742-9ff1-e8f5a1b9828f, then the scheme URL, in this case, would be pn63bfa427-cf5f-4742-9ff1-e8f5a1b9828f

You’ll also need to configure your Podfile if you haven’t already. To do so, go to the root of your project directory and run pod init; this will generate a Podfile.

Open this Podfile, and insert the specific pods (services) you’d like to use within your project. In this case, ParticleConnect and CommonConnect will generally suffice, but additional services can be added if needed.

Additionally, you’ll need to paste in the code snippet below for installation handling:

pod 'ParticleConnect'
pod 'CommonConnect'

// Paste this
post_install do |installer|
installer.pods_project.targets.each do |target|
  target.build_configurations.each do |config|
  config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
    end
  end
 end

You can also copy the example Podfile.

With your Podfile set, you’ll need to run pod install and open your .xcworkspace file, as shown below:

pod install --repo-update

open {your project}.xcworkspace

Finally, for iOS, you’ll need to formally use the projectId, clientKey, and appId previously retrieved. To do this, head to the root of your Xcode project and create a file called ParticleNetwork-Info.plist. Within this file, paste the following text (then replace the placeholders):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>PROJECT_UUID</key>
	<string>YOUR_PROJECT_UUID</string>
	<key>PROJECT_CLIENT_KEY</key>
	<string>YOUR_PROJECT_CLIENT_KEY</string>
	<key>PROJECT_APP_UUID</key>
	<string>YOUR_PROJECT_APP_UUID</string>
</dict>
</plist>

​

Android configuration

If you’re building your Unity game for Android, you’ll just need to configure two files before you’re ready to go. The first of these two files can be found at Assets/Plugins/Android/launcherTemplate.gradle within your project. Here, you’ll need to ensure you have the necessary dependencies included.

Specifically, you’ll need the following dependencies at a minimum:

• network.particle:auth-serviceif you’re planning on using Particle Auth directly.
• network.particle:connect, required for Particle Connect.
• network.particle:unity-bridge, required universally.
• Additional dependencies, optional:
  • network.particle:chains, collection of chainInfo objects.
  • network.particle:connect-solana-adapter, Solana-specific custom wallet adapter to be used within Particle Connect.
  • network.particle:connect-phantom-adapter, Wallet adapter for Phantom to be used within Particle Connect.
  • network.particle:connect-evm-adapter, EVM-specific custom wallet adapter to be used within Particle Connect.
  • network.particle:connect-auth-adapter, Particle Auth adapter for Particle Connect (social logins).
  • network.particle:connect-wallet-connect-adapter, WalletConnect adapter for Particle Connect. The full list of network.particle packages can be found here.

dependencies {
    implementation project(':unityLibrary')
    implementation "network.particle:auth-service:${sdkVersion}"
    implementation "network.particle:unity-bridge:${sdkVersion}"
  	implementation "network.particle:connect:${sdkVersion}"
  	// Other dependencies
}

Finally, for Android, you’ll need to place your projectId, clientKey, and appId within gradleTemplate.properties, which can be found at Assets/Plugins/Android/gradleTemplate.properties.

particle.network.project_client_key=Your Client Key
particle.network.project_id=Your Project ID
particle.network.app_id=Your App ID

​

Initialization

Now that you’ve managed the relevant dependencies and configured your Unity environment, you’ll need to initialize ParticleNetwork and ParticleConnectInteraction (derived from Network.Particle.Scripts.Core) before moving on. This is required for Particle Connect to function.

ParticleNetwork can be initialized by simply calling Init and passing in a chainInfo object (*). ParticleConnectInteraction.Init will require both a chainInfo object and a DAppMetaData parameter (in this example, represented as metadata) containing a WalletConnect project ID retrieved from the WalletConnect dashboard, alongside the name of your project, the icon (preferably 512x512), the website URL, and a project description.

Additionally, with WalletConnect as the underlying infrastructure for Web3 wallets within Particle Connect, you’ll also have the opportunity to include configuration for multiple different chains on WalletConnect by calling ParticleConnectInteraction.SetWalletConnectV2SupportChainInfos and passing in an array of chainInfo objects.

An example of the above process can be found below.

var metadata = new DAppMetaData(TestConfig.walletConnectProjectId,"Particle Connect",
            "https://connect.particle.network/icons/512.png",
            "https://connect.particle.network",
            "Particle Unity Demo");

ParticleNetwork.Init(ChainInfo.Ethereum);
ParticleConnectInteraction.Init(ChainInfo.Ethereum, metadata);

Additionally, if you’d like to define multiple chains to be available through WalletConnect, you’ll need to create an array of ChainInfo objects (chainInfos in this example) and use it within ParticleConnectInteraction.SetWalletConnectV2SupportChainInfos. E.g.:

List<ChainInfo> chainInfos = new List<ChainInfo>
                { ChainInfo.Ethereum, ChainInfo.EthereumSepolia, ChainInfo.EthereumSepolia };
ParticleConnectInteraction.SetWalletConnectV2SupportChainInfos(chainInfos.ToArray());

​

Examples of Utilization

​

Set Chain Info

If you want to set the primary chain after initializing with .Init and before a user is connected, you can call ParticleNetwork.SetChainInfo, passing in the appropriate chainInfo object for the desired chain.

If your application supports only EVM chains, ParticleNetwork.SetChainInfo is sufficient and can be called anytime. However, if you support both EVM and Solana chains, use ParticleAuthCore.Instance.SwitchChain when switching between EVM and Solana chains. For example:

ParticleNetwork.SetChainInfo(ChainInfo.Ethereum);

// Alternatively, if you are using WalletType.authCore
await ParticleAuthCore.Instance.SwitchChain(ChainInfo.Ethereum);

​

Connect Wallet

Within implementations of Particle Connect, Connect drives connection with a wallet in the Particle Connect stack, (social login or otherwise.) This is done through ParticleConnect.Instance.Connect, then passing in a relevant WalletType object, derived from Network.Particle.Scripts.Model

WalletType is an enum containing the following choices:

• AuthCore, Particle Auth Core, an alternative to Particle Auth (Particle).
• EvmPrivateKey, custom EVM wallet imports/exports.
• SolanaPrivateKey, custom Solana wallet imports/exports.
• MetaMask.
• Rainbow.
• Trust.
• ImToken.
• Bitget.
• WalletConnect.
• Zerion.
• Math.
• Inch1.
• Zengo.
• Alpha.
• OKX.
• TokenPocket, not supported by iOS.
• Phantom, intended for Solana.

If you’re using AuthCore, you’ll also need to pass in a ConnectConfig object containing:

E.g.:

// Use social logins
var supportLoginTypes = new List<SupportLoginType> { SupportLoginType.APPLE, SupportLoginType.EMAIL, SupportLoginType.PHONE, SupportLoginType.GOOGLE};
var loginPageConfig = new LoginPageConfig("Particle Unity Example",
                "An example description", "https://connect.particle.network/icons/512.png");
ConnectConfig config = new ConnectConfig(LoginType.Email, "user@example.come", null, supportLoginTypes, SocialLoginPrompt.SelectAccount, loginPageConfig);
await ParticleConnect.Instance.Connect(WalletType.Particle, config);

// Use MetaMask or other supported wallet
await ParticleConnect.Instance.Connect(WalletType.MetaMask);

​

Disconnect Wallet

To disconnect an active session identified by a specific address, you can call ParticleConnect.Instance.Disconnect, passing in the particular wallet type (WalletType object) and associated address that you’d like to disconnect from your application, as is shown below.

await ParticleConnect.Instance.Disconnect(this._walletType, publicAddress);

​

Is Connected

Another critical method is IsConnected, returning a Boolean indicating whether or not a user (or, in this case, an address and WalletType) is currently connected to your application. This can be called through ParticleConnectInteraction.IsConnected. E.g.:

ParticleConnectInteraction.IsConnected(this._walletType, publicAddress);

​

Sign and Send Transaction

ParticleConnect.Instance.SignAndSendTransaction is the primary mechanism for EVM and Solana to send (or, in this case, suggest) transactions. Upon calling, the WalletType (the adapter in question) will return a confirmation popup requesting a signature from the user before sending the transaction directly to the network. SignAndSendTransaction takes three parameters:

• WalletType is the type of wallet being used.
• address is the public address being used.
• transaction, a stringified representation of a transaction object.

E.g.:

await ParticleConnect.Instance.SignAndSendTransaction(this._walletType, publicAddress, transaction);

​

Sign Transaction

ParticleConnect.Instance.SignTransaction is a Solana-specific method for signing a transaction without pushing it to the network. This will behave similarly to SignAndSendTransaction, although it will only function on either the Phantom or SolanaPrivateKey wallet types and will purely return a signature.

The plural of this method is ParticleConnect.Instance.SignAllTransactions, which takes a list of transactions rather than just one to be prompted for signature.

await ParticleConnect.Instance.SignTransaction(this._walletType, publicAddress, transaction);

// Alternatively
await ParticleConnect.Instance.SignAllTransactions(this._walletType, publicAddress, transactions);

​

Sign Message

A simple message (UTF-8 string) can be signed on both EVM & Solana through ParticleConnect.Instance.SignMessage, passing in the WalletType, address (publicAddress in this example), and the message in question. message should be a general string to be signed. E.g.:

var message = "GM, Particle!";
await ParticleConnect.Instance.SignMessage(this._walletType, publicAddress, message);

​

Sign Typed Data

As an alternative to SignMessage, for EVM chains, you can request that a user signs typed (structured) data rather than purely a raw string. To do this, you can use adapter.signTypedData (equivalent to eth_signTypedData, represented as either TypedDataV4, TypedDataV2, or TypedDataV1). This takes the following parameters:

• address is the user address to target for signature initiation.
• data, the typed data to be signed; see the Web (JavaScript/TypeScript) page for additional guidance.

E.g.:

var txtAsset = Resources.Load<TextAsset>("TypedDataV4");
string typedData = txtAsset.text;

await ParticleConnect.Instance.SignTypedData(this._walletType, publicAddress, typedData);

​

Import Wallet

If you’re using theEvmPrivateKey or SolanaPrivateKey wallet types, you can import wallets through either a seed phrase or private key. These methods will associate an account instance derived from these keys, allowing utilization within your application.

These can be achieved through ImportWalletFromPrivateKey for importing a private key, or ImportWalletFromMnemonic for importing a mnemonic (seed phrase). These methods require the WalletType (either EvmPrivateKey or SolanaPrivateKey) and the private key/seed phrase to be imported.

Additionally, you can export one of these wallets with ParticleConnect.Instance.ExportWalletPrivateKey, passing in the address (of the EvmPrivateKey or SolanaPrivateKey imported/generated wallet) that you’d like to export.

await ParticleConnect.Instance.ImportWalletFromPrivateKey(this._walletType, privateKey);

await ParticleConnect.Instance.ImportWalletFromMnemonic(this._walletType, mnemonic);

// Exportation
await ParticleConnect.Instance.ExportWalletPrivateKey(this._walletType, publicAddress);

​

Dive Deeper

ParticleConnect includes ParticleAuthCore. When logged in with a Particle account, you can access additional functions such as getUserInfo, openAccountAndSecurity, hasMasterPassword, hasPaymentPassword, and changeMasterPassword. For more information, refer to the Auth SDK reference.