Android (Kotlin)

Interacting with Particle Auth on Android using Kotlin

Particle Auth for Android

The Particle Auth Android SDK is the flagship mechanism for integrating Particle's Wallet-as-a-Service within Android applications. This SDK, for most applications, acts as the sole facilitator of integration on Android, built for simplicity. As with the other Particle Auth SDKs, it requires only a few lines of code.

Unlike the Unity SDK and Web SDK, the Android SDK deviates in installation and configuration; these specific intricacies and setup processes are detailed below.


Getting Started

Utilizing the Particle Auth Android SDK is quite straightforward, although it requires a few prerequisite version minimums to get started and ensure compatibility.

Prerequisites

  • minSdkVersion 23 or higher.
  • minSdkVersion 23 or higher; compileSdkVersion, targetSdkVersion 33 or higher.
  • JavaVersion 11.
  • Jetpack (AndroidX).

Configuration

Before you begin using the Particle Auth Android SDK, you'll need a few required values that are universal across all Particle Auth SDKs. These values are projectId, clientKey, and appId. All three can be retrieved by heading over to the Particle dashboard and doing the following:

  1. Sign up/log in to the Particle dashboard.

  1. Create a new project or enter an existing one.

  1. Create a new Android application, or skip this step if you already have one.

  1. Retrieve the project ID (projectId), the client key (clientKey), and the application ID (appId).

‎‎

‎‎

‎‎

Installation

With a project and application created on the Particle Dashboard, you can move on to installing and initializing ParticleNetwork. For the former, you must begin by declaring the Particle Auth SDK in your Gradle file.

repositories {
  google()
  mavenCentral()
  maven { setUrl("https://jitpack.io") }
  //...
}

dependencies {
  implementation("network.particle:auth-service:${latest_version}")
  
  // Alternatively, to use Auth Core
  //implementation("network.particle:auth-core:${latest_version}")
  //implementation("network.particle:mpc-core:${latest_version}")
  
  // Find the latest version of the SDK:
  // https://search.maven.org/search?q=g:network.particle
}

📘

For release updates, subscribe to the GitHub repository.

Additionally, you'll need to go ahead and declare specific configurations, such as the insertion of aforementioned values projectId, clientKey, and appId within the relevant AndroidManifest.xml file.

An example of such configuration is attached below- placeholders such as pn_project_id would need to be filled in.

<application>
  
  <activity
    android:name="com.particle.network.controller.WebActivity"
    android:exported="true"
    android:launchMode="singleTask"
    android:configChanges="orientation|keyboardHidden|screenSize"
    android:theme="@style/ThemeAuthWeb">

    <intent-filter>
      <data android:scheme="pn${pn_app_id}" />

      <action android:name="android.intent.action.VIEW" />

      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
    </intent-filter>

  </activity>
  
  <meta-data
    android:name="particle.network.project_id"
    android:value="${pn_project_id}" />
  
  <meta-data
    android:name="particle.network.project_client_key"
    android:value="${pn_project_client_key}" />
  
  <meta-data
    android:name="particle.network.app_id"
    android:value="${pn_app_id}" />
  
</application>

Examples of utilization

Initialize the SDK

Upon application startup, ParticleNetwork will need to be initialized to function properly. This can be done by calling the init method on ParticleNetwork and passing in the primary chain you intend to use within your application

import com.particle.network.ChainId
import com.particle.network.ChainName
import com.particle.network.Env
import com.particle.network.ParticleNetwork

class App : Application() {

  override fun onCreate() {
    super.onCreate()
    
    // Initialize Particle Auth SDK for Ethereum
    ParticleNetwork.init(this, Env.DEV, EthereumChain(EthereumChainId.Mainnet))
    
    // If you're using Solana, initialization looks like this
    ParticleNetwork.init(this, Env.DEV, SolanaChain(SolanaChainId.Mainnet))
  }
}

Switch Chain

After initializing ParticleNetwork with a specific initial chain, you can switch the primary chain being used by calling setChainInfo on ParticleNetwork. setChainInfo should primarily take the chain in which you'd like to switch to, such as EthereumChain(EthereumChainId.Mainnet), along with callback handling (optionally).

val chainInfo = EthereumChain(EthereumChainId.Mainnet)
ParticleNetwork.setChainInfo(
  chainInfo,
  object : ChainChangeCallBack {
    override fun success() {
      ToastUtils.showLong("currChain:${ParticleNetwork.chainInfo.chainName}") 
    }

    override fun failure() {
      ToastUtils.showLong("failure:${ParticleNetwork.chainInfo.chainName}")
    }
  })

Login

ParticleNetwork.login throws the standard login popup, which changes depending on the associated configurations such as loginType (adjacent to the Web SDK's preferredAuthType), supportAuthTypeValues, and so on. This login popup acts as the primary mechanism facilitating account creation and, for existing users, account login.

Specifically, ParticleNetwork.login takes the following parameters:

  • loginType, the social login method preferred. This supports either 'jwt,' 'email,' 'phone,' 'google,' 'apple,' or 'facebook'.
  • account, if the above is either 'phone,' 'email,' or 'jwt,'account can optionally be set to a specified expected email or phone number. If you're using 'jwt,'account is required and must be set to the relevant JWT.
  • supportAuthType, the list of authentication types you'd like to be available through the resulting login popup interface. By default, this will only display the login type chosen through loginType, although you can add additional methods to the UI, such as 'google,' by passing them into supportAuthType.
  • loginFormMode, whether or not the login UI will be in "form mode," essentially a simplified and cut-down version of the default "full mode" UI.
  • prompt, the prompt to be displayed following social login, such as a request to set a master password, payment password, etc. This is null by default.

ParticleNetwork.login(
  loginType = LoginType.PHONE,
  account = "", // Optional
  supportAuthTypeValues = SupportAuthType.FACEBOOK.value, // Optional
  loginFormMode = false,  // Optional
  prompt = null, // Optional
  loginCallback = object : WebServiceCallback<LoginOutput> {
    override fun success(output: LoginOutput) {
      // Handle success
    }
    override fun failure(errMsg: WebServiceError) {
      // Handle failure
    }
  })

After the login is successful, detailed user information can be retrieved by calling ParticleNetwork.getUserInfo().

Logout

ParticleNetwork.logout will log a user out of their current session and return them to the previous state before login.

ParticleNetwork.logout(object : WebServiceCallback<WebOutput> {
  override fun success(output: WebOutput) {
    // Handle success
  }

  override fun failure(errMsg: WebServiceError) {
    // Handle error
  }
})

Fast Logout

Functioning in parallel with the previous, ParticleNetwork.fastLogout will log a user out while hiding any browser-based loading, resulting in a faster, more immediate logout procedure.

ParticleNetwork.fastLogout(object : FastLogoutCallBack {
  override fun success() {
    // Handle success
  }

  override fun failure() {
    // Handle error
  } 
})

Is User Logged In

ParticleNetwork.isLogin returns a Boolean based upon the account status of a given session (whether or not a user is logged in with Particle.

ParticleNetwork.isLogin()

Signatures

Once ParticleNetwork has been initialized and a user has successfully logged in, signatures can be proposed for confirmation through a popup; this can be facilitated via a number of different methods:

  • signAndSendTransaction: Requests a signature for a given transaction and, upon receiving it, sends the transaction and returns the signature.
  • signTransaction: Solana-specific; requests a signature for a given transaction. Upon receiving a signature, it gets immediately returned. A transaction is not automatically sent.
  • signMessage: Requests a signature for a basic message. On EVM chains, this can be passed as a hex-encoded string prefixed by '0x'. For Solana, this can be passed directly as a string.
  • signTypedData: EVM-specific, requests a signature for structured (typed) data- eth_signTypedData. For more information on signTypedData, see the Web (JavaScript/TypeScript) page.
ParticleNetwork.signAndSendTransaction(transaction, object : WebServiceCallback<SignOutput>{
  override fun success(output: SignOutput) {
    // Handle success
  }

  override fun failure(errMsg: WebServiceError) {
    // Handle failure
  }
})
// Expects a base58 string, Solana-specific
ParticleNetwork.signTransaction(transaction, object : WebServiceCallback<SignOutput>{
  override fun success(output: SignOutput) {
    // Handle success
  }

  override fun failure(errMsg: WebServiceError) {
    // Handle failure
  }  
})

// Plural version of the above
val allTransactions = listOf(tx1, tx2)
ParticleNetwork.signAllTransactions(
  activity,
  allTransactions,
  object : WebServiceCallback<SignOutput> {
    override fun success(output: SignOutput) {
      // Handle success
    }
    override fun failure(errMsg: WebServiceError) {
      // Handle error
    }
  })
ParticleNetwork.signMessage(message, object : WebServiceCallback<SignOutput>{
  override fun success(output: SignOutput) {
    // Handle success
  }

  override fun failure(errMsg: WebServiceError) {
    // Handle failure
  }
})
// Expects hex string prefixed with '0x'
ParticleNetwork.signTypedData(message, version, object : WebServiceCallback<SignOutput>{
  override fun success(output: SignOutput) {
    // Handle success
  }

  override fun failure(errMsg: WebServiceError) {
    // Handle error
  }
})

Set Display Wallet

If you'd like to display the full wallet whenever a signature is requested, you can pass true within ParticleNetwork.setDisplayWallet. By default, this is set to false.

ParticleNetwork.setDisplayWallet(true)

Open Web Wallet

If you'd like to open an instance of the Wallet UI (Particle Wallet, a unified mechanism of interacting with accounts generated by ParticleNetwork.login), then you can do so by calling ParticleNetwork.openWebWallet and passing in various chosen configurations.

For specific details regarding custom style configurations, see the Web Wallet reference.

val customStyleJson = """
  {
    "supportAddToken": false,
    "supportChains": [{
        "id": 1,
        "name": "Ethereum"
      },
      {
        "id": 5,
        "name": "Ethereum"
      }
    ]
  }
"""

ParticleNetwork.openWebWallet(customStyleJson)

Open Account and Security

Additionally, if you'd like to, force the "Account and Security" options to be opened on-screen (from which you can control master passwords, payment passwords, additional accounts, and so on), on the frontend, then you can call ParticleNetwork.openAccountAndSecurity.

ParticleNetwork.openAccountAndSecurity() 

Set Security Account Config

Within the security settings, specific popups can be set to display upon confirmation or wallet UI entrance. These popups include promptSettingWhenSign, which refers to payment (signature) passwords, and promptMasterPasswordSettingWhenLogin, which refers to a login-based master password.

By default, promptSettingWhenSign is set to 1, which will show the prompt upon the first signature a given account conducts. If it's set to 0, it will never be shown; if it's set to 2, it will be shown upon every signature confirmation.

This same logic applies to promptMasterPasswordSettingWhenLogin, although by default it's set to 0.

ParticleNetwork.setSecurityAccountConfig(
  SecurityAccountConfig(
      promptSettingWhenSign = 1,
      promptMasterPasswordSettingWhenLogin = 2
  )
)

Language Setting

ParticleNetwork.setAppliedLanguage will forcibly set the language of the text displayed within UI popups initiated by the SDK- this can be either 'en-US', 'ja-JP', 'ko-KR', 'zh-CN', or 'zh-TW'. Additionally, you can call ParticleNetwork.getAppliedLanguage to retrieve the currently active language setting.

// Supports LanguageEnum.EN、LanguageEnum.JA、LanguageEnum.KO、LanguageEnum.ZH_CN、LanguageEnum.ZH_TW
ParticleNetwork.setAppliedLanguage(LanguageEnum.EN)

ParticleNetwork.getAppliedLanguage()