JarCastingVYou SDK for Android
The VYou SDK provides two modules, the core module that provides an API to interact directly with the backend and authenticate your users; and the UI module, in which you will have developed the interface to interact with dynamic forms, such as registration or profile. Those modules are structured as follows
VYou-Core
Install
In order to install the VYou-Core SDK in your Android application you'll need to add the following dependency inside your application-level build.gradle file
implementation "io.github.apiumhub:vyou-core:1.0.2
Also, if you don't have mavenCentral() as a repository, you should add it to your project-level build.gradle file:
allprojects {
repositories {
mavenCentral()
//The rest of your repositories
}
}
Setup
You'll need to include to your AndroidManifest the following permissions, to allow the SDK to perform network operations.
<uses-permission android:name="android.permission.INTERNET" />
There are a few parameters that you need to provide to the SDK in order to make it work properly. They must be provided via AndroidManifest's <meta-data>, and are read autommatically by the SDK when needed. Those parameters are the following:
<meta-data
android:name="vyou_client_id"
android:resource="@string/VYOU_CLIENT_ID"
android:value="string" />
<meta-data
android:name="vyou_redirect_uri"
android:resource="@string/VYOU_REDIRECT_URI"
android:value="string" />
<meta-data
android:name="vyou_url"
android:resource="@string/VYOU_URL"
android:value="string" />
<meta-data
android:name="google_client_id"
android:resource="@string/GOOGLE_CLIENT_ID"
android:value="string" />
<meta-data
android:name="facebook_app_id"
android:resource="@string/FACEBOOK_APP_ID"
android:value="string" />
Our proposed approach for including all of this data is adding them via build.gradle such as:
resValue "string", "VYOU_CLIENT_ID", "8XxbGzbBAAbapQ9t*******KDw9h0KBWQYvT2P67T42lAlrZrG7KWg"
resValue "string", "VYOU_REDIRECT_URI", "https://vyou-gallagher.vercel.app/vyou_oauth_callback.html"
resValue "string", "VYOU_URL", "https://test.vyou-app.com:8380"
resValue "string", "GOOGLE_CLIENT_ID", "975381680954-klti62p4c***ti9tikbglf.apps.googleusercontent.com"
resValue "string", "FACEBOOK_APP_ID", "83431****8440"
This allows you to setup those values by environment read them from any external file (such as local.properties) in case you need to.
Once you have all of those values in place, the last thing you need to do is initialize the SDK along with your application. In order to do that, you need to call the following method in your Application class
VYou.initialize(this)
API
Every public method inside the SDK return a VYouResult which basically is a wrapper of the result of an action. This is represented by a sealed class whose possible values are
VYouResult.Successwhich holds avalue: Twith the result of the actionVYouResult.Failurewhich holds anerror: Throwablewith the reason for the failure
The VYou-Core SDK is divided in three main components that allows the developers to interact with the SDK depending on their needs, those are the following
VYouLoginManager
This component allows you to interact with the three possible login platforms that the SDK provides. The API for that is the following
suspend fun signInWithAuth(): VyouResult<VyouSession>
suspend fun signInWithGoogle(): VyouResult<VyouSession>
suspend fun signInWithFacebook(fragment: Fragment): VyouResult<VyouSession>
Those three methods will start a new Activity inside your application, gather the necessary information from the user, perform an API request to the VYou backend and return the proper result inside the VYouSession object.
To be able to interact with the VYouLoginManager, it's mandatory to pass an ActivityResultCaller as a parameter from your application.
fun getLogin(actResultCaller: ActivityResultCaller) = VYouLoginManager(actResultCaller)
The activityResultCaller can be an activity or a fragment, this class can call APIs of type Activity#startActivityForResult without having to manage the request codes, and converting the request/response to an Intent. It's necessary to call this function before the onCreate of your Activity or Fragment. You can do it like this:
private val vyouLogin = VYou.getLogin(this)
Last but not least, if you are using Facebook to authenticate your users, you need to override
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?)
in the Fragment or Activity that is calling the signInWithFacebook(...) method and call
VyouLoginManager.onActivityResult(requestCode, resultCode, data)
inside it.
VYouTenantManager
This manager allows the developer to interact with all of the API that doesn't require the user to be authenticated. Those methods are the one for obtaining the Tenant information and the one for registering a new user in the platform:
suspend fun tenant(): VYouResult<VYouTenant>
suspend fun register(customer: RegisterDto): VYouResult<Unit>
Any of those two methods will perform an API request and return the proper result wrapped inside a VYouResult object.
VYouSession
The last one of the components inside the VYou-Core SDK is the session. This session is accessible statically via the val session: VYouSession? property inside the VYou object. As you might have realized, this is a nullable property which will only hold a value if the user has been previously authenticated in your application. All of this session data is stored inside Android's EncryptedSharedPreferences, so all of this data is properly secured by the OS. The VYouSession class holds the user's credentials (VYouCredentials) which are accessible to the developer in case it's needed. It also holds the necessary methods to interact with a logged-in user, which are the following:
suspend fun signOut(): VYouResult<Unit>
suspend fun tenantProfile(): VYouResult<VYouProfile>
suspend fun editProfile(editProfileDto: EditProfileDto): VYouResult<Unit>
HttpClient
This SDK also provides you with an OkHttpClient with the proper configuration so that you can make authenticated requests with any server that needs it. This client has three interceptors which are responsible for adding the Client-Credentials header which authenticated your application against the VYou servers, the Authorization header, which authenticates your user if it's logged in, and a last one responsible for refreshing the user's token if it's expired or invalid. This client is accessible via a static property val httpClient: OkHttpClient inside the VYou object.
CredentialsStorage
VYou provides a built-in storage for credentials based on EncryptedSharedPreferences provided by the OS. It might be the case that this solution does not fit the security requirements for your application. If that's the case, we provide an API so that you can install your own CredentialsStorage system to replace the one we provide.
In order to do so, we provide an example with an InMemory storage.
class InMemoryCredentialsStorage: CredentialsStorage {
private var credentials: VYouCredentials? = null
override fun save(credentials: VYouCredentials) {
this.credentials = credentials
}
override fun read(): VYouCredentials? = credentials
override fun clear() {
credentials = null
}
}
Notice that you need to implement the CredentialsStorage interface
Once this is done, you need to override the storage inside VYou. In order to do so, as we are using Koin for dependency injection, this is pretty straightforward.
You must create a module that provides your CredentialsStorage implementation and overrides our own, this is declared as follows.
val credentialsModule = module {
single<CredentialsStorage>(override = true) {
InMemoryCredentialsStorage()
}
}
The last thing you have to do is pass a list containing this module when you initialize the SDK
VYou.initialize(this, listOf(credentialsModule))
All of this code is available for you to test inside the sample app we provide.
VYou-UI
Along with the Core SDK, we provide another library that provides built-in forms for registering a user and editing it's profile. Those forms are dynamically built with the information configured in the back office.
Install
In order to install the VYou-UI SDK in your Android application you'll need to add the following dependency inside your application-level build.gradle file
implementation "io.github.apiumhub:vyou-ui:1.0.2
Also, if you don't have mavenCentral() as a repository, you should add it to your project-level build.gradle file:
allprojects {
repositories {
mavenCentral()
//The rest of your repositories
}
}
Important note Notice that VYou-Core is a dependency inside VYou-UI, so if you add VYou-UI to your project, you don't need to add the Core dependency anymore.
Setup
Please refer to the VYou-Core setup, as you'll have to follow all of the steps described on it. Important note To make VYou-UI SDK work you must replace this line
VYou.initialize(this)
with the following
VYouUI.initialize(this)
As in the VYou-Core setup, you will need to call this function before the onCreate of your Activity or Fragment:
private val vyouUi = VYouUI(this)
API
As VYou-UI holds a dependency to VYou-Core, all of it's API will still be available, so please take a look at it if you haven't done so yet. The VYou-UI SDK provides methods to start the register & edit profile flows from your application
suspend fun startRegister(): VYouResult<Unit>
suspend fun startProfile(credentials: VYouCredentials): VYouResult<Unit>
Those two methods will start a new Activity inside your application, and return the result of any of the flows inside a VYouResult In order to launch the edit profile activity, you must provide the user's credentials which are easily accessible through
Vyou.session?.credentials
Styling
In order to style the forms shown to the user, the SDK is integrated with the built-in theme system inside Android, so everything that's configurable by the theme should also work inside the SDK. We provide the following example in the sample application
<resources xmlns:tools="http://schemas.android.com/tools">
<!-- Base application theme. -->
<style name="Theme.VYou" parent="Theme.MaterialComponents.DayNight.DarkActionBar">
<!-- Primary brand color. -->
<item name="colorPrimary">@color/purple_500</item>
<item name="colorPrimaryVariant">@color/purple_700</item>
<item name="colorOnPrimary">@color/white</item>
<!-- Secondary brand color. -->
<item name="colorSecondary">@color/teal_200</item>
<item name="colorSecondaryVariant">@color/teal_700</item>
<item name="colorOnSecondary">@color/black</item>
<!-- Status bar color. -->
<item name="android:statusBarColor" tools:targetApi="l">?attr/colorPrimaryVariant</item>
<!-- Customize your theme here. -->
</style>
</resources>
but everything that's configurable via theme.xml will also change the display inside the SDK.
Sample App
We provide a sample application for developers to see how VYou is integrated inside a real android app.
To be able to login with google, you must register the project in Firebase, add the keystore to the signingConfigs, and the google-services plugin in the build.gradle like this:
signingConfigs {
debug {
storeFile file("ext/debug-keystore.jks")
storePassword '*qfwN*******oPw9DEj'
keyAlias 'debug'
keyPassword '@G*********DYww9b'
}
}
plugins {
id 'com.android.application'
id 'kotlin-android'
id 'kotlin-kapt'
id 'com.google.gms.google-services'
}
Finally you have to add the google-services.json to the sample app project.
Here you can find the Firebase documentation for adding the Google login.
