Step 1. Configure the development environment

In this step, you set up your environment to create Android applications using the freely-available Android Studio IDE.

You then create a new application project and configure it to use the Ping SDK for Android.

Prerequisites

Android Studio: Download and install Android Studio, which is available for many popular operating systems.
An Android emulator or physical device: To try the quick start application as you develop it, you need an Android device. To add a virtual, emulated Android device to Android Studio, refer to Create and manage virtual devices, on the Android Developers website.

Create a new project

In Android Studio, select File > New > New Project.
On the New Project screen, select Empty Views Activity, and then click Next.
On the next screen:
- In the Name field, enter Ping SDK for Android Quick Start.
- In the Package name field, enter com.example.quickstart.
- In the Save location field, enter the location in which to create the project.
- In the Language drop-down, select Java.
- In the Minimum SDK drop-down, select API 23: Android 6.0 (Marshmallow).
- Click Finish.
  
  Android Studio creates a simple application that you can now configure to use the Ping SDK for Android.

Configure compile options

The Ping SDK for Android requires at least Java 8 (v1.8).

Configure compile options in your project to use this version of Java, or later:

In the Android view of your project, right-click app, and then click Open module settings.
In the Project Structure dialog, navigate to Modules > app > Properties.
In the Source Compatibility and Target compatibility drop-downs, select the version of Java to use for the project:

Figure 1. Selecting the Java version for a project in Android Studio
Click OK.

Add build dependencies

To use the Ping SDK for Android, add the relevant dependencies to your project:

In the Project tree view of your Android Studio project, open the Gradle Scripts/build.gradle file for the module.

In the dependencies section, add the following:

implementation 'org.forgerock:forgerock-auth:4.6.0'

Example of the dependencies section after editing:

dependencies {
    implementation 'org.forgerock:forgerock-auth:4.6.0'
    ...
    implementation 'androidx.appcompat:appcompat:1.6.1'
    implementation 'com.google.android.material:material:1.8.0'
    implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
}

(Optional) Enable optional clear traffic and location support

If you are not using the PingOne Advanced Identity Cloud but rather a local PingAM server that does not use the HTTPS protocol, you can edit your project manifest file to allow cleartext connections.

You should only configure this property during development against a local PingAM server.

Do not configure this property in your production applications.

Open the project manifest file.

For example, app > manifests > AndroidManifest.xml.
Add an android:usesCleartextTraffic="true" attribute to the <application> element.

(Optional) Enable location permissions

If you intend for your application to use any of the Android location services; for example, the SDK’s location matching or geofencing features, add one of the relevant properties to the project manifest file

Open the project’s manifest file.

For example, app > manifests > AndroidManifest.xml.
Add the relevant properties as a child of the <manifest> element:
1. Coarse location access
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
2. Fine location access (requires both permissions)
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
  For information about which permission to use, see Location permissions in the Google Developer Documentation.

Example completed manifest file

The following shows an example AndroidManifest.xml file with support for cleartext traffic and fine location access enabled:

AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <application
        android:allowBackup="true"
        android:dataExtractionRules="@xml/data_extraction_rules"
        android:fullBackupContent="@xml/backup_rules"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.ForgeRockSDKForAndroidQuickStart"
        tools:targetApi="31"
        android:usesCleartextTraffic="true">
        <activity
            android:name=".MainActivity"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

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

            <meta-data
                android:name="android.app.lib_name"
                android:value="" />
        </activity>
    </application>

    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

</manifest>

Check point

In Android Studio, select Run > Run 'app'.

Android Studio builds the application and runs it in the default emulator.

As you have not yet added any UI, the app displays only "Hello World!".

You have now configured your Android app development environment, created a new project, and configured it with the required dependencies and build options.

In the next step, you configure your application with the settings it needs to connect to your PingOne Advanced Identity Cloud or PingAM instance.

Ping SDKs