Getting Started

Requirements

The ReachFive SDK supports Android SDK from API Level 19 (Android version 4.4 KitKat).

To initialize the ReachFive client, you need a Domain URL and a Client ID.

For more information, refer to Domain and client configuration.

For security reasons, you have to whitelist all available domains where the ReachFive SDK will be used.

This has to be done in the Allowed Origins (CORS) field of your ReachFive console, in the Settings menu.

The ReachFive client detects the user locale from the browser, and you can override the local at initialization by providing a language. Supported languages are: en, es, fr, it, nl, de.

Installation

ReachFive SDKs are published to JCenter as separate modules. Add JCenter as a repository location in your project’s top-level build.gradle file, as shown below:

allprojects {
    repositories {
        jcenter()
    }
}

Below are installation instructions for each module.

SDK Core

Core contains all the main tools and interfaces, and the methods related to standard authentication with an identifier and a password.

Add the following line to your app/build.gradle, replacing x.y.z with the latest SDK version:

dependencies {
    implementation "com.reach5.identity:sdk-core:x.y.z"
}

The following permissions are required to communicate with the ReachFive servers. Add them to the AndroidManifest.xml file.

<manifest>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.USE_CREDENTIALS" />
</manifest>

SDK WebView

This module uses a WebView to authenticate users, it enables all providers that are supported by ReachFive.

providers config

Add the following line to your app/build.gradle, replacing x.y.z with the latest version:

dependencies {
  implementation "com.reach5.identity:sdk-webview:x.y.z"
}

You need to add this activity into the AndroidManifest.xml file:

<activity
    android:name="com.reach5.identity.sdk.webview.ReachFiveLoginActivity"
    android:screenOrientation="portrait" />

For mobile contexts, you must whitelist reachfive-${clientId}://callback, using your Reachfive identity client ID.

This URL scheme is the default callback URL and is used to request a token when implementing the SDK Webview.

You also need to add the URL scheme in AndroidManifest.xml file:

<intent-filter android:scheme="https">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />

    <data
        android:host="callback"
        android:scheme="reachfive-${clientId}"
        android:pathPattern=".*"
        tools:ignore="AppLinkUrlError" />
</intent-filter>

Facebook native provider

This module uses the Facebook native SDK to provide a better user experience.

Add the following lines to your app/build.gradle, replacing x.y.z with the latest version:

dependencies {
    implementation "com.reach5.identity:sdk-facebook:x.y.z"
    implementation "com.facebook.android:facebook-login:4.37.0"
}

Refer to the Facebook Connect guide to create your Facebook application.

If you’re using the latest version of the Facebook API, please remove the user_gender scope from the ReachFive client configuration to prevent any issues.

Add the line below into your string.xml resource file with your Facebook application ID:

<resources>
    <string name="facebook_app_id">FACEBOOK_APPLICATION_ID</string>
</resources>

Then add these lines into the AndroidManifest.xml file:

<manifest>
    <meta-data
      android:name="com.facebook.sdk.ApplicationId"
      android:value="@string/facebook_app_id" />
    <activity
      android:name="com.facebook.FacebookActivity"
      android:configChanges="keyboard|keyboardHidden|screenLayout|screenSize|orientation"
      android:label="@string/app_name" />
</manifest>

Google native provider

This module uses the Google native SDK to provide a better user experience.

First, include Google’s Maven repository in your top-level build.gradle file:

allprojects {
    repositories {
        google()
    }
}

To enable the service, add the line below at the bottom of your app/build.gradle file so that no dependency collisions are introduced:

apply plugin: 'com.google.gms.google-services'

Add the following line to your app/build.gradle, replacing x.y.z with the latest version:

dependencies {
    implementation "com.reach5.identity:sdk-google:x.y.z"
}

Refer to the Google Connect guide to create your Google application.

Once the application is created, you need an ID client OAuth specific to the Android apps. You can create it by selecting Android, filling in an application name, package name and a SHA-1 signature digest that you can retrieve with the command line below:

keytool -exportcert -keystore path-to-debug-or-production-keystore -list -v

More information about the keytool utility in the Authenticating Your Client guide.

You also need to use Google’s Firebase services. To do so, create a new Firebase project. Enter the package’s name, the application’s name, and the SHA-1 signature. Download the google-services.json file and put it at the root of your Android project. You can find more information in Add Firebase to your Android project and Adding the JSON File.

Initialization

import android.content.Intent
import android.os.Bundle
import android.util.Log
import android.view.Menu
import android.view.MenuItem
import android.widget.Toast
import androidx.appcompat.app.AppCompatActivity
import com.reach5.identity.sdk.core.ReachFive
import com.reach5.identity.sdk.core.SdkConfig
import com.reach5.identity.sdk.core.models.AuthToken
import com.reach5.identity.sdk.core.models.ProfileSignupRequest
import com.reach5.identity.sdk.facebook.FacebookProvider
import com.reach5.identity.sdk.google.GoogleProvider
import com.reach5.identity.sdk.webview.WebViewProvider
import io.github.cdimascio.dotenv.dotenv
import kotlinx.android.synthetic.main.activity_main.*

class MainActivity : AppCompatActivity() {
    // The ReachFive client
    private lateinit var client: ReachFive

    val DOMAIN    = "Your ReachFive domain"
    val CLIENT_ID = "Your ReachFive client ID"
    val SCHEME    = "Your ReachFive scheme"

    override fun onCreate(savedInstanceState: Bundle?) {

        // The configuration parameters needed by the ReachFive client
        val sdkConfig = SdkConfig(domain = DOMAIN, clientId = CLIENT_ID, scheme = SCHEME)

        // The list of the social providers needed by your application
        val providersCreators = listOf(GoogleProvider(), FacebookProvider(), WebViewProvider())

        client = ReachFive(
            sdkConfig = sdkConfig,
            providersCreators = providersCreators,
            // Your Android activity
            activity = this
        )

        // Initialize the ReachFive client
        client.initialize({ providers ->
            // On success, do something with the retrieved list of providers registered for this ReachFive client
            // ...
        }, {
            // On failure, log the error message returned by the ReachFive client
            Log.d("Reach5_MainActivity", "ReachFive init ${it.message}")
        })
    }
}

Below are all the functions accessible via the Android SDK.

In all the code examples below, the ReachFive client is instantiated and stored in a variable named client.