DEV Community: Younes Charfaoui

Learn how to display and manage notifications in Android

Younes Charfaoui — Wed, 03 Nov 2021 18:08:11 +0000

Oftentimes, in Android applications, notifications are used to communicate with users about application updates and reminders. In this way, they tend to be really helpful when users are outside your app’s UI and allow for quick interactions like deleting an email or responding to a message.

In this blog post, we’ll cover how to display notifications, customize them with parameters and styles, manage them, add actions, and more.

This article presumes that you have some experience in building Android apps in Kotlin.

Project setup

To start, open up Android Studio and create a new project, or just open an existing project to add notification features to it.

No special dependencies are needed to work with notifications, just the core SDK.

Notification channels

Notification channels are a way to group notifications that our application sends into manageable groups.

From Android 8.0 (API level 26) and on, notifications need to be attributed to a channel, and for each channel, you can set the visual and acoustic behaviors that apply to all notifications in that specific channel.

With this, users have more flexibility in changing these settings and deciding whether a notification channel from your app should be intrusive, visible, and so on.

From a developer perspective, before displaying a notification you should create a channel first. Start by getting a reference to the NotificationManager. Following this, you’ll have to ensure that you’re running on an Android 8.0 device or higher—for that, you’ll have to make the required checks, and if needed, create the channel and add it.

Here’s a code snippet that creates a channel, customizes its behaviour, and adds it with NotificationManager:

companion object {
        private const val NOTIFICATION_ID = 112
        private const val PRIMARY_CHANNEL_ID = "primary_notification_channel"
}

private lateinit var notificationManager: NotificationManager

private fun createNotificationChannel() {
        notificationManager = getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager

        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            val channel = NotificationChannel(
                PRIMARY_CHANNEL_ID,
                "Messages",
                NotificationManager.IMPORTANCE_HIGH
            )

            channel.enableLights(true)
            channel.lightColor = Color.RED
            channel.enableVibration(true)
            channel.description = "Messages Notification"
            notificationManager.createNotificationChannel(channel)
        }
    }

Display your first notification

To display a notification, you need to build it first, as the notification is something that holds a lot of parameters. The way to do so is through the NotificationCompat.Builder.

This builder will need a context and a channel in which the notification will be associated. Using this builder, you’ll set the different parameters of the notification.

For the purposes of this tutorial, we’ll start with something relatively simple, like a title, text, and a basic icon.

After you finish building the notification, to display it you can use either the NotificationManager or with NotificationManagerCompat to make the code more efficient, concise, and cleaner.

Both require a notification object (the one we created) and a notification ID that identifies this notification. This way we can get a reference to it if we want to update or cancel it.

Here’s a code block that creates a notification and displays it:

// creating the notification and its parameters.
val builder = NotificationCompat.Builder(this, PRIMARY_CHANNEL_ID).apply {
                setSmallIcon(R.drawable.ic_android)
                setContentTitle("Notification Article")
                setContentText("Learn How To Manage And Display Notifications in Android")
                setPriority(NotificationCompat.PRIORITY_DEFAULT)
            }

// displaying the notification with NotificationManagerCompat.
with(NotificationManagerCompat.from(this)) {
     notify(NOTIFICATION_ID, builder.build())
}

/* or you can use the notification manager object.
notificationManager.notify(NOTIFICATION_ID, notification.build())
*/

Notification Parameters

When building a notification, you can use several public methods of the Builder object to customize the notification. Here are a few:

setContentTitle: Set the text that will appear as the title (first row) of the notification.
setContentText: Set the text that will appear in the second row of the notification.
setAutoCance: Bypassing a boolean to this method, you’re indicating whether you want the notification to be automatically canceled when the user taps it in the notification panel.
setLargeIcon: A bitmap to display on the right side of the notification.
setPriority: This method is used to set the priority of the notification, which is an indication of how important notification is for the user’s attention.
setTimeoutAfter: Set the time after which this notification should be canceled, if it isn’t already.
setSmallIcon: Set the icon that will be displayed in the notification.
setStyle: This method allows you to add a rich notification style (such as inbox style).
addActions: This method allows you to add an action to the notification using text, an optional icon that’s typically displayed by the system as a button with custom text icon, and a PendingIntent (we’ll talk about this shortly).
setContentIntent: Use this method to supply a PendingIntent, sent when the notification is clicked.
setDeleteIntent: Supply a PendingIntent to be sent when the user clears the notification from the notification panel.

Here’s an image that describes some of the visual components of the notification:

Update and cancel notifications

Sometimes when an event occurs, the notification needs to be changed or updated, and under some circumstances, it needs to be canceled — the Android framework offers simple functionalities for these circumstances:

Canceling a notification: Call the NotificationManager's cancel() method and pass the notification ID that you used when displaying it. You can also call the cancelAll() method to cancel all the notifications that are produced by your application.

Here’s a code snippet showing how to cancel a notification:

private fun cancelNotification() {
        notificationManager.cancel(NOTIFICATION_ID)
}

Update Notification: Updating notifications is the same as displaying them. You need just to create another notification with the builder object, then ask the NotificationManager to display it for you using the same notification ID. This way, the NotificationManager will know to update the notification with the new one.

Pending intents

Sometimes you want an action to be performed after a user taps a notification—like displaying an activity or starting a background service, or just sending an intent to a broadcast receiver.

All of these actions require an intent. And that’s a problem—we can’t use intents here.

If you want to launch an activity from your app, it isn’t a problem at all. When calling startActivity() with the intent from your app, your app has the permission to do so.

The problem occurs when the launcher (system component) tries to launch your activity without the required permissions. For that reason, we need another kind of intent that your app can give to another—this is called a pending intent.

A PendingIntent is kind of token that you give to other applications (e.g NotificationManager), which allows the foreign application to use your application's permissions to perform something.

So if you give the foreign application an intent, it will execute your intent with its own permissions. But if you give the foreign application a PendingIntent, that application will execute your intent using your application's permission.

You can create a PendingIntent using static methods like getActivity() and getService(), depending on the component you want to launch. And within these methods, you should define an intent like you would in normal situations. You can also add flags and parameters—this way, the PendingIntent acts as a wrapper for your intent to be used by a foreign application.

We’ll create a PendingIntent to launch the MainActivity after tapping the notification. Here’s the code to do so:

val intent = Intent(this, MainActivity::class.java).apply {
            flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TASK
        }

val pendingIntent: PendingIntent = PendingIntent.getActivity(this, 0, intent, 0)

val builder = NotificationCompat.Builder(this, PRIMARY_CHANNEL_ID).apply {
    setSmallIcon(R.drawable.ic_android)
    setContentIntent(pendingIntent)
    setContentTitle("Notification Article")
    setContentText("Learn How To Manage And Display Notifications in Android")
    setAutoCancel(true)
    setPriority(NotificationCompat.PRIORITY_DEFAULT)
}


with(NotificationManagerCompat.from(this)) {
    notify(NOTIFICATION_ID, builder.build())
}

Customize with action

You can do many other things after you know how to trigger actions from notifications using PendingIntent.

One of these things is adding buttons or actions in the notification for launching a process after a user taps it—or example, say you want to delete an email after the user taps the delete action in the notification.

For this, you need two main things: a PendingIntent that launches the process (either in a background service or through a broadcast receiver), and then to pass this intent to the notification builder through the addAction() methods that take an icon and a string title.

Here is a code snippet to demonstrate that:

val deleteIntent = Intent(this, DeleteBroadcastReceiver::class.java).apply {
                action = ACTION_DELETE
                putExtra(EXTRA_EMAIL_ID, EMAIL_ID)
}

val deletePendingIntent: PendingIntent =  PendingIntent.getBroadcast(this, 0, deleteIntent, 0)

val builder = NotificationCompat.Builder(this, PRIMARY_CHANNEL_ID).apply {
                setSmallIcon(R.drawable.ic_android)
                setContentTitle("Notification Article")
                setContentText("Learn How To Manage And Display Notifications in Android")
                setPriority(NotificationCompat.PRIORITY_DEFAULT)
                setContentIntent(pendingIntent)
                addAction(R.drawable.ic_delete, "Delete", deletePendingIntent)
              }

Expandable notifications

If you’re trying to display text that’s too big to fit in a normal-sized notification (like emails) or to show a big image that the user wants to see before entering the app, you can make your notification expandable.

The way to achieve this is through adding styles to the notification, mainly a BigTextStyle or BigPictureStyle. These are predefined styles with predefined behaviours to handle the expandability of your notifications, depending on what you’re trying to display.

Adding these styles is done through the setStyle method, which allows you to indicate to the builder object on which you want a specific style.

With BigTextStyle, you can add the text you want to display like in the following snippet:

var notification = NotificationCompat.Builder(context, CHANNEL_ID)
        .setSmallIcon(R.drawable.new_mail)
        .setContentTitle(emailObject.getSenderName())
        .setContentText(emailObject.getSubject())
        .setLargeIcon(emailObject.getSenderAvatar())
        .setStyle(NotificationCompat.BigTextStyle()
                .bigText(emailObject.getSubjectAndSnippet()))
        .build()

For BigPictureStyle, you also need to specify the style again and the image you want to expand, as shown in the following line of codes:

var notification = NotificationCompat.Builder(context, CHANNEL_ID)
        .setSmallIcon(R.drawable.new_post)
        .setContentTitle(imageTitle)
        .setContentText(imageDescription)
        .setLargeIcon(myBitmap)
        .setStyle(NotificationCompat.BigPictureStyle()
                .bigPicture(myBitmap)
                .bigLargeIcon(null))
        .build()

Other Notification Styles

Besides the aforementioned styles, there are other styles you can use in your notifications to make for a better user experience. Here are a few of them:

Notification.InboxStyle: Notification style for generating large-format notifications that include a list of strings.
Notification.MediaStyle: Notification style for media playback notifications.
Notification.MessagingStyle: Style for generating large-format notifications that include multiple back-and-forth messages of varying types between any number of people.

Resources

A good article explaining the use of different notification styles.
The main guide from the developer documentation.

Here are some specific documentation pages to check out:

Conclusion

I hope you enjoyed learning how to create dynamic notifications: how to display them, how to add styles, and more importantly, how to manage them effectively.

There is much more to learn about notifications, such as creating a group of notifications or creating a custom notification design like many apps do, among others. Now that you’ve acquired a basic understanding, I’d encourage you to check out these more advanced concepts.

Demystifying Principal Component Analysis: Handling the Curse of Dimensionality

Younes Charfaoui — Tue, 02 Nov 2021 13:33:54 +0000

Generally, in machine learning problems, we often encounter too many variables and features in a given dataset on which the machine learning algorithm is trained.

The higher the number of features in a dataset, the harder it gets to visualize and to interpret the results of model training and the model’s performance. Moreover, when dealing with such a massive dataset in terms of features, the computational costs should be considered.

It would be great if there was a method to eliminate or exclude some features or dimensions to obtain a smaller feature space.

This is where dimensionality reduction techniques come into play. As we will see in this article what is this concept, and the details of a powerful algorithm called Principal Component Analysis that reduce the dimensionality of the dataset.

That way, you get a better understanding of these types of problems and how you can solve them.

Dimensionality Reduction

Dimensionality reduction is a set of machine learning techniques for reducing the number of features by obtaining a set of principal variables. This process can be carried out using several methods that simplify the modeling of complex problems, eliminate redundancy, and reduce the possibility of overfitting.

Some many techniques and algorithms can reduce the dimensionality of data, such as feature selection processes, which applies both statistical measures and search methods to obtain a smaller feature space.

There are also linear methods ( — like PCA), principal curves, kernel methods, local dimensionality reduction, nonlinear auto-associators, vector quantization methods, and multidimensional scaling methods.

We also deep learning solutions that are classified as unsupervised learning — this subset has its neural network architecture that we call autoencoders.

Today, we’re going to talk about one of the foundational algorithms in dimensionality reduction — principal component analysis.

Advantages of Dimensionality Reduction

Whenever there are massive datasets, dimensionality reduction is what comes to mind for machine learning engineers and AI developers. It helps them perform data visualization and complex data analysis processes. Here are some other advantages of using these techniques:

Reduces both space and time complexity required for machine learning algorithms.
Improves the interpretation of machine learning model parameters.
It makes it easier to visualize data when reduced to very low dimensions, such as 2D or 3D.
Avoids the curse of dimensionality.

Example

Say we’re doing a simple classification problem that relies on both humidity and rainfall. In such a case, these features may overlap. But oftentimes these highly-correlated features can be collapsed into just one feature, which helps shrink the overall feature space.

Principal Component Analysis

Principal component analysis (PCA) is an algorithm that uses a statistical procedure to convert a set of observations of possibly correlated variables into a set of values of linearly uncorrelated variables called principal components.

This is one of the primary methods for performing dimensionality reduction — this reduction ensures that the new dimension maintains the original variance in the data as best it can.

That way we can visualize high-dimensional data in 2D or 3D, or use it in a machine learning algorithm for faster training and inference.

PCA steps

PCA works with the following steps:

Standardize (or normalize) the data: By default, this is the machine learning engineer’s responsibility.
Calculate the covariance matrix from this standardized data (with dimension d).
Obtain the Eigenvectors and Eigenvalues from the newly-calculated covariance matrix.
Sort the Eigenvalues in descending order, and choose the 𝑘 Eigenvectors that correspond to the 𝑘 largest Eigenvalues — where 𝑘 is the number of dimensions in the new feature subspace (𝑘≤𝑑).
Construct the projection matrix 𝑊 from the 𝑘 selected Eigenvectors.
Transform the original dataset 𝑋 by simple multiplication in 𝑊 to obtain a 𝑘-dimensional feature subspace 𝑌.

Next, we dive deeper into the details of each step to more fully understand the concepts.

PCA in-depth

Here, we’ll be refreshing some foundational Linear Algebra and Statistics concepts in this section, alongside the details of the previous steps. The math is important here because it’s the core of the principal component analysis algorithm.

Data Standardization

Standardizing (or normalizing) the data before applying PCA is critical — this is because PCA will give more importance to those features having higher variances than to those features with extremely low variances during the identification of the best principle components to retain.

Say that you have a dataset with features that have different units — for example, one feature is in kilometers and another is in centimeters, and both have the same change in value. PCA will understand that the KM feature is reflecting minor changes, while the other is reflecting bigger changes.

In this case, standardization is required to tackle these issues; otherwise, PCA will give a higher preference to the centimeter variable.

Covariance Matrix

Variance in statistics means the measure of the variability or spread in a set of data. Mathematically, it’s the average squared deviation from the mean score.

Covariance is a measure of the amount or the degree to which corresponding elements from two sets of ordered data move in the same direction.

A covariance matrix generalizes the notion of variance to multiple dimensions (or multiple features). It describes the covariance for each pair of features values (or Random Variables).

A covariance matrix can be calculated as follows:

What a covariance matrix does for PCA is simply describe the relationship between the variables so the algorithm knows how to reduce their dimensionality without losing a lot of information.

Computing Eigenvectors and Eigenvalues

The eigenvector of a matrix (linear transformation) is a nonzero vector that changes at most by a scalar factor when that linear transformation is applied to it, whereas the eigenvalue is the factor by which the Eigenvector is scaled.

These concepts are at the core of PCA. We’re going to calculate those elements for our covariance matrix from the previous step. The Eigenvectors (or principal components) determine the directions of the new feature space, and the Eigenvalues determine their magnitude.

In other words, the Eigenvalues explain the variance of the data along the new feature axes.

The Eigenvalue and Eigenvector of a matrix can be calculated as follows:

— Where 𝜆 is the Eigenvalue and 𝑋 is the Eigenvector.

To solve the previous equation, we need a zero determinant:

With that, we find the required Eigenvalues and Eigenvectors.

Sort Eigenvalues

The typical goal of PCA is to reduce the dimensionality of the original features space by projecting it onto a smaller subspace — in other words, where the Eigenvectors will form the axes.

To decide which Eigenvectors can be dropped without losing too much information for the construction of lower-dimensional subspace, we need to inspect their corresponding Eigenvalues:

The Eigenvectors with the lowest Eigenvalues carry the least information about the distribution of the data — those are the ones that can be dropped.
The Eigenvectors with the high Eigenvalues carry more information about the distribution of the data — those are the ones that need to be preserved.

To do so, a common approach is to rank or sort the Eigenvalues from highest to lowest, and then choose the top k Eigenvectors.

Projection matrix

This is the easiest part: the construction of the projection matrix that will be used to transform the dataset into the new feature subspace.

The way to construct this matrix is to concatenate the top k Eigenvectors from the previous step.

Transform the original dataset

We’ve finally arrived at the last step. Here, we’ll use the projection matrix 𝑊 from the previous step to transform our samples into the new subspace.

We can achieve that using simple matrix multiplication, via the equation 𝑌=𝑋×𝑊, where 𝑌 is the matrix of our transformed samples, and X is our original matrix dataset.

Coding

Now that we’ve covered the steps and the math behind PCA, we’ll now look at the two ways to implement PCA — first by coding it ourselves, and second through the use of an external library.

Hard coding

To implement the algorithm ourselves, we need the NumPy functions. Then, using the aforementioned steps, we get the principal component analysis.

Here’s an implementation:

import numpy as np

def pca(number_compontents, data):
    if not 0 <= number_compontents <= data.shape[1]:
        raise ValueError('The number of features are less than the number of components')

    # calculate the covariance matrix
    cov_matrix = np.cov(data.T)

    # calculate the eigen things
    eig_vals , eig_vecs = np.linalg.eigh(cov_matrix)

    # making eigen values and eigen vectors as pairs
    eig_pairs = [(np.abs(eig_vals[i]) , eig_vecs[:,i]) for i in range(len(eig_vals))]

    # Sorting All of Them
    eig_pairs.sort(key = lambda x : x[0] , reverse= True)

    # Getting the selected vector in a form of matrix
    final = [eig_pairs[i][1].reshape(data.shape[1],1) for i in range(number_compontents)]

    # Creating the Projection Matrix, multiplying by -identity is an addons
    projection_matrix = np.hstack((final))

    # transforming the data
    Y = data.dot(projection_matrix)

    return Y

# Give the dataset and the number of components
new = pca(number_compontents = 2 , x_train)

plt.scatter(new[:,0], new[:,1], c = y_train,s = 100, alpha = 0.5)
plt.xlabel('Principal Component 1')
plt.ylabel('Principal Component 2')
plt.show()

Using an external library

Even if you can implement PCA yourself, you’ll probably end up like all other machine learning engineers and data scientists — using libraries to accomplish dimensionality reduction.

Here is a code sample that uses scikit-learn:

# Getting The PCA From sklearn library
from sklearn.decomposition import PCA

# create the object with your desired dimensions.
pca = PCA(n_components = 2)

# project the data in the new dimension space.
new = pca.fit_transform(x_train)

# Ploting The Data For Sklearn Result
plt.scatter(new[:,0], new[:,1], c = y_train,s = 100, alpha = 0.5)
plt.xlabel('Principal Component 1')
plt.ylabel('Principal Component 2')
plt.show()

Resources

There are more examples and lessons out there that will help you start using PCA and dimensionality reduction in general. Here are a few I particularly like:

This answer describes PCA in an easy-to-understand non-technical way.
Introduction to LDA, another dimensionality reduction method.
PCA in sklearn: documentation.
Another way to calculate principal components using the SVD algorithm.

Conclusion

In this blog post, we saw that the curse of dimensionality can constitute a serious obstacle to the efficiency of the machine learning models — Having too many overlapping data dimensions.

As a solution, we explored the PCA algorithm that helps you reduce the dimensionality of data so the machine learning algorithms can operate in a faster and more effective way.

I hope I succeeded in conveying the concept and the details of the PCA to you. Understanding how these algorithms and other machine learning algorithms work is pretty delightful because it helps you debug problems in your data — and eventually to build better models.

Securing Network and Inter-App Communications on Android

Younes Charfaoui — Mon, 25 Oct 2021 06:29:39 +0000

Nowadays, one issue that flies under the radar for Android developers is app security. Although the Android OS possesses a layer of security that’s sufficient most of the time, it can be enhanced by adding an extra layer of security using some advanced mechanisms and features.

Today’s article is going to cover some of these best practices and mechanisms to better secure your apps.

We begin by showing the way to secure network communications by using network security configuration files and certificate authority customization. We’ll then shed some light on inter-app communications, where we can secure incoming and outgoing intents, applications components like Content Provider, and more.

This article presumes you have some experience in building Android apps with Kotlin, and also some general knowledge about interacting with other apps and doing network communication. Finally, the reader should have some experience with security principles like HTTPS, Certificate Authorities, and so on.

Network Communications

Most Android devices connect to the internet through wifi, which is oftentimes accessed publicly. This can expose devices and applications to a variety of attacks that affect user information. To confront this, we should secure our network’s communication in order for the user’s sensitive information to be transmitted securely.

One important thing to do is to connect to secure endpoints—by that, I mean HTTPS or non-cleartext traffic domains.

Now we’ll explore the network security configuration that will prevent us from connecting to unsecured connections.

Network Security Configuration

With Android 7.0 Nougat, the platform introduced the Network Security Configuration file, which helps you customize the security configuration in a declarative based scripting style using XML without modifying the app code. It offers a lot of flexibility for developers with features like:

Prevent connecting to cleartext traffic (non-secure HTTP)
Customize connection configuration by the domain name.
Testing connection purposes with debug overrides
Advanced security features like certificate pinning

To start using the Network Security Configuration file, you first need to create an XML file inside the res/xml folder. You can name it whatever you want. Next, set your application to use the file you just created as configuration in-network calls. This is achieved by setting a tag in the manifest file to point to our configuration file:

<?xml version="1.0" encoding="utf-8"?>
<manifest ... >
    <application 
         android:networkSecurityConfig="@xml/config"
         ...>
        ...
    </application>
</manifest>

In the config file, you can set different tags for different purposes. In the root tag called network-security-config, you can add the following tags:

base-config: This tag is used for the default configuration of all the connections unless it’s not overridden by the domain-config tag.

You can set within it a parameter called clearTextTrafficPermitted to indicate whether you want to allow clear text traffic (unsecured HTTP) or not by setting it to true or false.

This tag can also contain trust-anchors tags, you can use this tag to indicate that your app may want to trust a custom set of Certificate Authorities instead of the platform default (we will talk more about this later in Custom Trusted Certificate Authorities section).

domain-config: This sort of configuration is used for connecting to specific destinations. It can contain multiple domain tags, by which you indicate the destination.
debug-overrides: These overrides happen when android:debuggable is set to true—usually it’s the non-release build’s apk generated for testing purposes. This tag can contain multiple trust-anchors. This is significantly safer than using conditional code.

Here is an example that shows all the tags in one file:

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <!-- Don't allow clear text traffic for all domains unless is not in the domain-config -->
    <base-config cleartextTrafficPermitted="false" />

    <!-- Special configuration to some domains -->
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">localhost</domain>
        <trust-anchors>
            <!-- Trust a debug certificate in addition to the system certificates -->
            <certificates src="system" />
            <certificates src="@raw/debug_certificate" />
        </trust-anchors>
    </domain-config>

    <!-- Special configuration if the app is in a debuggable mode -->
    <debug-overrides>
        <trust-anchors>
            <certificates src="@raw/my_ca"/>
        </trust-anchors>
    </debug-overrides>

</network-security-config>

Custom Trusted Certificate Authorities

Under some circumstances, you might want to trust certificate authorities (CAs) other than the platform default, or you might want to customize the set of trusted CAs by your app.

This could be the case if you want to trust additional CAs that aren’t included in the system or connect to a host with self-signed certificates (like in a private company)—or even just to limit the set of CAs that your app trusts.

You can achieve all of that using the trust-anchors tag in the network security configuration file in one of the config tags (domain, base or debug). Here’s an example:

<domain-config>
        <domain includeSubdomains="true">localhost</domain>
        <trust-anchors>
            <certificates src="@raw/my_certificate" />
        </trust-anchors>
</domain-config>

This means that for the localhost domain we are telling the Android OS to enables the certificate file named my_certificate stored in the res/raw directory. The file should be in PEM or DER format and needs to be in res/raw. you can allow more certificates by adding certificates a tag. Here’s another example that shows how to allow both system-based and other CAs:

<base-config>
        <trust-anchors>
            <certificates src="@raw/othercas"/>
            <certificates src="system"/>
        </trust-anchors>
</base-config>

Certificate Pinning

The Network Security Configuration file supports more advanced features like certificate pinning. This is an additional layer of security that can be used when a CA issues a fraudulent certificate, which will make your app vulnerable to a man-in-the-middle (MiTM) attack. To prevent such a problem, you need to use certificate pinning (check the resource section for more information).

To use this feature in your app, you need to specify the set of public key hashes for the certificates that are to be trusted. Then, during the HTTPS handshake, we see if the certificate chain contains at least one of the pinned public key hashes that we specified earlier. For that we use two tags:

pin-set includes the certificate to be pinned. It can be specified in both domain and base configuration tags, and can contain one or more pin tag. Additionally, they can have an expiration date set after the point at which pinning can expire, so the app keeps working even if the user doesn’t update it for a long time.
pin tag is specified in the pin-set tag that holds the public key SHA-256 for the certificate to be pinned.

An example of that:

<domain-config>
        <domain includeSubdomains="true">website.net</domain>
        <pin-set expiration="2020-04-16">
            <pin digest="SHA256">public_key_primary</pin>
            <pin digest="SHA-256">public_key_backup</pin>
        </pin-set>
</domain-config>

One thing to add is that you should include an additional pin (a backup one) in case the primary certificate gets compromised or expires. You should also set an expiration date for the pins to support old apps.

Inter-App Communication

Inter-app communication is the communication that allows your Android app to interact with other applications. This sort of communication takes into account the security of intents and the app components.

1- Securing Outgoing Intents

In Android applications, sometimes we launch intents to other applications in the device. These intents can be explicit or implicit—the explicit ones are handled via your code, but the implicit ones are handled by other applications. And for that, the outgoing intents have to be secured in some manner

The issue here is that the user may set an app as the default for some actions, which can cause a problem when these actions involve sensitive user information. In these cases, the user is no longer given an option to choose a trusted app with this sensitive information.

To solve this, we’ll use something called an app chooser, which basically starts whenever you want to launch an implicit intent. An app chooser dialog pops up even if the user has previously set a default app. Here is a code sample:

val intent = Intent(Intent.ACTION_SEND)
val activityList = packageManager.queryIntentActivities(intent, PackageManager.MATCH_ALL)
when {
    activityList.size > 1 -> {
        val chooser = Intent.createChooser(intent, "Choose an App")
        startActivity(chooser)
    }
    intent.resolveActivity(packageManager) != null -> startActivity(intent)
    else -> Toast.makeText(this, "No App to launch with", Toast.LENGTH_LONG).show()
}

2- Securing Incoming Intents

Say you don’t want to expose your activity or your content provider (or any component) to other applications, and you want to allow only the apps you control or own.

For that, you can use signature-based permission that lets only your apps that are signed with the same signing key share data among them. The cool thing is that this type of permission doesn’t require user confirmation and are granted at install time.

The way to do that is to define permission in the manifest file:

<permission android:name=”packageName.HelloWorldPermission”
            android:protectionLevel=”signature” />

And then apply this permission to the component you want to make private to the apps you own:

<provider android:name=”android.support.v4.content.FileProvider”
          ...
          android:permission=”packageName.HelloWorldPermission”/>

3- Securing components

Finally, if you want to prevent access from any other application to your components, you can use the mechanism provided by the Android OS.

We generally use it to prevent access to the content provider that holds sensitive application data (you can also apply it to activities and other components).

You simply specify android:exported="false" in the manifest inside the component you want to disallow access to. Bear in mind that the android:exported tag is set to true by default.

Here is an implementation sample:

<provider android:name="StudentsProvider"        
          android:authorities="com.example.StudentsProvider"                            
          ....     
          android:exported="false"/>

Resources

The official Android documentation provides a lot of rules and best practices that can help improve your application. Here are the best practices you need to follow.

You can take a look at this checklist that includes a set of criteria that ensure the security of user information.

For more information about the certificate pinning check out this article.

And finally, here’s the documentation for the Network Security Configuration, which covers all the available features and principles.

Conclusion

I hope you enjoyed this look at various techniques and methods for securing your Android apps. Android provides a security layer by default that you can build on top of in order to gain more security and ensure user safety. Whether you’re developing an Android application for billions of users, or for a select few, the security of your customers should be your first priority in order to prevent the loss or exposure of sensitive user data.

Phone Number Verification via SMS in Android Using Firebase

Younes Charfaoui — Fri, 22 Oct 2021 20:18:51 +0000

Validating identity is incredibly important in mobile development, and assuring new user signups are real human beings is critical. Developers need reliable ways to confirm the identities of their users to prevent security issues.

Developers can implement verification systems using phone numbers in two main ways: either by calling or by sending an SMS containing a code that the user must input.

But implementing such a system from scratch can be tedious and time-consuming, given that there are a lot of components that need to be established. Luckily, Firebase phone authentication offers such a system for Android and iOS, along with free quota for SMS verification messages (10,000 free per month).

In this article, we’ll implement SMS phone verification in Android using this tool from Firebase.

This article presumes that you have some experience in building Android apps in Kotlin.

Project Setup

First, we need to set up a Firebase project. If you’re new to Firebase here’s a quick tutorial to show you how to set up a project and link it with your application. So start by going to the console and creating a new project. After that, under the develop section, choose authentication, and then from the main screen, choose Sign-in Methods to enable the phone sign-in provider.

You’ll also need to install a dependency to use Firebase authentication services:

implementation ‘com.google.firebase:firebase-auth:19.0.0’

Initialzation

Now go to your desired activity where you want phone verification to happen. Here, we start by initializing the instance with some parameters:

var auth = FirebaseAuth.getInstance() auth.setLanguageCode(Locale.getDefault().language)

We need to create an instance of FirebaseAuth and initialize it with the FirebaseAuth.getInstance() method. You can set the language of the SMS text that will be sent with the setLanuageCode() method.

We’ll also need two more global variables that will help us save the validation token and then resend token—the former will be used when the user enters the code within the SMS to be validated by the Firebase backend, and the latter is an optional one we’ll use when we want to resend the same SMS if the user doesn’t receive any message (due to various problems). Here are those variables:

private var storedVerificationId: String? = null 
private lateinit var resendToken: PhoneAuthProvider.ForceResendingToken

Send SMS

To send the SMS, we call a method called verifyPhoneNumber() from the instance of the PhoneAuthProvider, which takes several parameters. The most important one is the phone number. The first step is to set up a mechanism to retrieve a user’s phone number. When you have this parameter, here’s the code to send an SMS:

PhoneAuthProvider.getInstance().verifyPhoneNumber(phoneNumber, 60, TimeUnit.SECONDS, this, phoneCallbacks)

In the above code, you can see multiple parameters are passed to the verifyPhoneNumber() methods:

The 60 is a timeout parameter, which is the maximum amount of time you’re willing to wait for SMS auto-retrieval to be completed by the library.
Then the Unit in which our timeout is expressed (in this case, seconds).
this represents the activity to which the callbacks are scoped.
The final parameter is the callbacks, which are discussed next, in which we’re going to create a variable called phoneCallbacks to be passed in the verifyPhoneNumber() method.

Callbacks

After that verifyPhoneNumber() is called, we need to handle the result of this request. For this, we need to create an instance of an abstract class calledOnVerificationStateChangedCallbacks, implement its methods, and then pass this instance to the previous method verifyPhoneNumber().

In Kotlin (as in many other languages), you can’t inherit multiple classes, but you can implement many interfaces. Since we can’t extend this abstract class in our activity (because it’s already inherited by the AppCompactActivity), we can refactor our code to make it look cleaner.

To do this, we can create a separate class called PhoneCallbacks in which we also create an interface, and extend the previous abstract class using the newly created interface:

import com.google.firebase.FirebaseException
import com.google.firebase.auth.PhoneAuthCredential
import com.google.firebase.auth.PhoneAuthProvider

class PhoneCallbacks(private val listener : PhoneCallbacksListener) : PhoneAuthProvider.OnVerificationStateChangedCallbacks() {

    interface PhoneCallbacksListener {
        fun onVerificationCompleted(credential: PhoneAuthCredential?)
        fun onVerificationFailed(exception: FirebaseException?)
        fun onCodeSent(
            verificationId: String?,
            token: PhoneAuthProvider.ForceResendingToken?
        )
    }

    override fun onVerificationCompleted(phoneAuthCredential: PhoneAuthCredential?) {
        listener.onVerificationCompleted(phoneAuthCredential)
    }

    override fun onVerificationFailed(exception: FirebaseException?) {
        listener.onVerificationFailed(exception)
    }

    override fun onCodeSent(verificationId: String?, token: PhoneAuthProvider.ForceResendingToken?) {
        listener.onCodeSent(verificationId,token)
    }
}

With that, we create an instance of the PhoneCallbacks class in our desired activity, and let this activity implement the PhoneCallbacksListener:
val phoneCallbacks = PhoneCallbacks(this)

The PhoneCallbacksListener interface contains 3 methods:

onCodeSent triggers when the SMS is sent to the user's phone, it will include a verification ID and the resend token that needs to be saved. So in this stage, we should save both of them in the global variables that we made earlier.
onVerficationCompleted will be triggered when an SMS is auto-retrieved or the phone number has been instantly verified. This basically means that the result of the verification is here, and we need just to check if it was successful or not and then proceed normally.
onVerficationFaild is triggered when an error occurs during phone number verification. This can happen for multiple reasons (internet connection issues, mobile network issues, Firebase issues, and many more). This method will be helpful for debugging if a problem occurs.

Here’s an implementation sample —we’ll return to the signInWithPhoneAuthCredntial() method shortly.

override fun onVerificationCompleted(credential: PhoneAuthCredential?) {
        if (credential != null && storedVerificationId != null)
            signInWithPhoneAuthCredential(credential)
        else {
            Toast.makeText(
                this,
                "Something went wrong, please try later.",
                Toast.LENGTH_LONG).show()
            finish()
        }
    }


override fun onVerificationFailed(exception: FirebaseException?) {
        Toast.makeText(
            this, "Something went wrong, try again later please.",
            Toast.LENGTH_LONG).show()
        finish()
}

override fun onCodeSent(
        verificationId: String?,
        token: PhoneAuthProvider.ForceResendingToken?
    ) {
        storedVerificationId = verificationId!!
        resendToken = token!!
    }

Verify the Code

In the OnVerificationCompleted method implemented in the activity, we need to make an action after the verification (successful or unsuccessful). To make the code cleaner we can define a method called signInWithPhoneAuthCredntial() that takes the PhoneAuthCredential parameter and completes the required verification.

Based on that check you can either redirect the user or do whatever you’d like if it was successful. Otherwise you can ask the user to re-enter the code or something similar. Here’s an implementation sample of this code verification process:

private fun signInWithPhoneAuthCredential(credential: PhoneAuthCredential) {
        auth.signInWithCredential(credential)
            .addOnCompleteListener(this) {
                if (it.isSuccessful) {
                  // Successful mean that the phone is verified, so do whatever you want here.
                } else {
                    Toast.makeText(
                        this,
                        "Something went wrong, try again later please.",
                        Toast.LENGTH_LONG).show()
                }
            }
    }

Resend Feature

Under some circumstances, the SMS might not be sent, so it’s essential that we have a way to resend the SMS. Some apps create an option called resend disable it at the beginning. 30 seconds or so after sending the first SMS, they enable it so the user can request a new code if they didn’t get the first SMS.

To make such a feature in our app, you need to set up a well-designed user interface to make it easier for the user to resend the SMS (I made simple resend button), When the user taps this resend button, we call again the verifyPhoneNumber() method with all the previous parameters (phone number, timeout, etc..). But this time we use the resend token, which is stored in resentToken variable that we mentioned in the initialization step. Here’s the code snippet:

PhoneAuthProvider.getInstance()
 .verifyPhoneNumber(phoneNumber, 60, TimeUnit.SECONDS, this, phoneCallbacks, resendToken)

Other Resources

To learn more about Firebase phone authentication, check out the official docs. For more on the PhoneAuthProvider class, you can also head over to those docs here.

Finally, I want to mention again that Firebase phone verification allows just 10,000 SMS per month—otherwise, you have to pay if you exceed this quota.

I hope you enjoyed this article. Keep in mind that there are other services like Facebook that also provide phone verification that can be used in multiple ways. So experiment it and see what fits your solution and platform the best.

Make your Android apps talk with Text-To-Speech

Younes Charfaoui — Fri, 22 Oct 2021 20:18:25 +0000

In a previous article, I described how to utilize speech recognition in Android. This consisted of capturing user speech, processing it, and implementing it.

But what if that process is reversed, and you want to take a text input and output speech? This type of system is, so-called, text-to-speech (TTS). TTS software, in general, creates a computer-generated voice that’s also considered as an assistive technology tool.

This technology has already been adopted widely in real-world applications like Assistants (Google and Siri) for interacting with the user commands. By applying this feature, you can rapidly increase the accessibility of your application for those with visual impairments and reading struggles. For example, this feature could especially help those with learning disabilities or those with difficulty reading large amounts of text due to dyslexia.

In today’s article, we’ll clarify the way to integrate this technology into Android applications using only the core SDK, so your applications can start speaking.

This article presumes that you have some experience in building Android apps in Kotlin.

Project Setup

To implement TTS technology, open up a new Android Studio project—no need for permissions or other library dependencies.

Text-To-Speech (TTS)

To start, we’ll work with a class called TextToSpeech. We also need the text to be spoken, so this one should be in string format. The first task is to create an instance of this class. Here’s how we initialize a global variable for this instance:

val textToSpeech = TextToSpeech(this, this)

The first “this” in the constructor is the context of the activity I’m in; the second “this” will be the initialization listeners of type TextToSpeech.OnInitListener, which will tell us about the TextToSpeech initialization result. For that, we need to let our activity implement the previous interface, and then we override the method called onInit(). Here’s a code sample:

override fun onInit(status: Int) {
      // check the results in status variable.
      if (status == TextToSpeech.SUCCESS) {
          // setting the language to the default phone language.
          val ttsLang = textToSpeech.setLanguage(Locale.getDefault())
          // check if the language is supportable.
          if (ttsLang == TextToSpeech.LANG_MISSING_DATA || ttsLang == TextToSpeech.LANG_NOT_SUPPORTED) {
              Toast.makeText(this, "We can't support your language", Toast.LENGTH_LONG).show()
          }
      } else {
          Toast.makeText(this, "TTS Initialization failed!", Toast.LENGTH_SHORT).show()
      }
}

As the code snippet above shows, if the status is TextToSpeech.SUCCESS, that means we’re ready to move forward. Next, we need to set up the language in which we want to speak—bear in mind that this isn’t always guaranteed, so we need to do an extra check to see if the language we’d like to use is supported and if there are sufficient data packages (voices) available.

At this point, we can say something with the TTS Engine via the speak() method. This will take 3 parameters: the “something”, which is what we want the phone to say in string format, a queuing strategy (we will talk more about this next), and finally the utteranceid, which can be used to identify the request to the TTS so we can use them in callbacks later on.

The speak() method will return the results of queuing the speak operation. Note that this method is asynchronous, and as the docs say The synthesis might not have finished (or even started!) at the time when this method returns. Thus, we can’t rely on the result of this method as a speech state, but we can use callbacks (as shown in the Add Callbacks section below) to detect errors.

Here’s a code snippet illustrates this:

private fun saySomething(something: String, queueMode: Int = TextToSpeech.QUEUE_ADD) {
      val speechStatus = textToSpeech.speak(something, queueMode, null, "ID")
      if (speechStatus == TextToSpeech.ERROR) {
          Toast.makeText(this, "Cant use the Text to speech.", Toast.LENGTH_LONG).show()
      }
}

Queuing Strategy

The queueMode parameter passed with the speak method is used to handle multiple requests by the TTS. It can be in 2 states: QUEUE_ADD or QUEUE_FLUSH.

The QUEUE_ADD state is a queue mode where the new entry is added at the end of the playback queue, while QUEUE_FLUSH is also a queue mode where all entries in the playback queue (media to be played and text to be synthesized) are dropped and replaced by the new entry.

For example, let’s say that we call the speak method 3 times with Strings of “Hello”, “Hi” and “How are you”. With queueMode being set to QUEUE_ADD, this means that the TTS Engine will speak the three different strings in order, The QUEUE_FLUSH mode, on the other hand, will indicate to the TTS Engine to only speak the last String (“How are you”).

Add Callbacks

For advanced flexibility with the TTS Engine, you can add callbacks to understand the state of the TTS Engine. For example, you can find out if the Engine is finished talking or when/if it starts, and so on.

This kind of information can be very useful when you want to do something based on its state. For instance, I built an Android application where I wanted to show an ad banner just after saying an expression. In this case, these callbacks were very helpful in doing this. Here’s some sample code that shows how to accomplish that by implementing an interface called UtteranceProgressListener via the setOnUtteranceProgressListener() method. The overridden methods are self-expressive, as shown:

textToSpeech.setOnUtteranceProgressListener(object : UtteranceProgressListener() {

    override fun onDone(utteranceId: String?) {
      //do whatever you want when TTS finish speaking.
    }

    override fun onError(utteranceId: String?) {
      //do whatever you want if TTS makes an error.
    }

    override fun onStart(utteranceId: String?) {
      //do whatever you want when TTS start speaking.
    }
})

As you can see in the methods, the utteranceId is passed, by which we can identify which speech is being processed. Thus, we can take action upon it.

Stopping the TTS Engine

You can also interrupt the TTS Engine at various points in time. Say the user hit the cancel button or something similar—here, you can stop it by using the stop() method. This way, we discard the current utterance and those in the queue as well.

Also, don’t forget to release the resources used by the TTS engine when you don’t need them. As a rule of thumb, when the activity destroyed or stopped, we should use the shutdown() method.

Resources & References

One of the best resources to learn how to use android API’s is the official documentation—check out the TextToSpeech class for more helpful methods.

Other tutorials are available on TutorialsPoint and JavaPapers, which showcase end-to-end TTS projects with Java code.

I hope you enjoyed reading this article and it contributed to your knowledge and interest in TextToSpeech. Android now talks, and so can your apps. Implementing such a feature can make your app contemporary, straightforward, and user-friendly, since most of the users expect such intelligent behaviors from today’s apps, especially for those with disabilities.

Discover the core Android API for Speech Recognition.

Younes Charfaoui — Mon, 18 Oct 2021 16:07:42 +0000

Android devices are ubiquitous and contain a lot of technologies that may help to build a rich experience for your users, one of these technologies is Speech Recognition, a lot of applications work with the user speech to provide new features like responding to commands, translating a phrase from language to language instead of typing it, and an innumerable list of other things. In this article, we will shed light on this technology and try to clarify how you can integrate it into your android applications to provide a great experience for your users.

This article assumes that you have some experience building Android apps with Kotlin Programming Language.

There are two main methods you can implement Speech To Text (STT) in Android Applications, the first one is throughout Google Dialog arising in each time you want to take user speech, whereas the second is without this dialog but it requires more code to accomplish the speech recognition.

Project Setup

The first thing to do is to add the required permissions in the AndroidManifest file in order to access this functionality, these permissions are the RECORD_AUDIO and the INTERNET, RECORD_AUDIO permission is a critical one, which means that you will need to ask for it in the runtime (Android Marshmallow API 23 and Higher) but just for the No Google Dialog method since Google Dialog method will handle it for you.

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.RECORD_AUDIO"/>

Google Dialog

To adopt this type of STT the first thing to do is to check whether you can use Speech Recognition in the current phone or not, we can verify it with these lines of codes:

if (!SpeechRecognizer.isRecognitionAvailable(this)) {
    Toast.makeText(
        this,
        R.string.no_recognition_available,
        Toast.LENGTH_LONG
    ).show()
}

Now we can start the speech recognition, we will launch an intent with some parameters, this one will be received and processed by the SpeechRecongnizer and its results (The user speech) will be provided in the onActvitiyResults overridden method, here is the way to launch the intent:

private fun askSpeechInput() {
    val intent = Intent(RecognizerIntent.ACTION_RECOGNIZE_SPEECH)
    intent.putExtra(RecognizerIntent.EXTRA_LANGUAGE_MODEL, RecognizerIntent.LANGUAGE_MODEL_FREE_FORM)
    intent.putExtra(RecognizerIntent.EXTRA_LANGUAGE,Locale.getDefault())
    intent.putExtra(RecognizerIntent.EXTRA_PROMPT, "Hi speak something");
    startActivityForResult(intent, REQ_CODE_SPEECH_INPUT);
}

As I said, the results will be provided in onActivityResult:

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    if (requestCode == REQUEST_SPEECH_RECOGNIZER && resultCode == Activity.RESULT_OK) {
        val results = data?.getStringArrayListExtra(RecognizerIntent.EXTRA_RESULTS)
        Log.d("TAG-R", results?.toString()) 
    }
}

The output is an array of Strings, which is the sentences that the user may say, for example, “Hello world” could be interpreted in different ways like [“hello world” and “hello word”], for that the resulting array will hold the two previous interpretations and maybe others as well, you can limit the size of the result with a parameter in the intent named EXTRA_MAX_RESULTS. It’s pretty easy to use Google Dialog for getting user speech, but sometimes we want to customize our interface to not display this dialog, to achieve this we have to resort to the following way.

Without Dialog

In this part, we will do the same thing but without Google dialog, to achieve this we need first to create an object called SpeechRecognizer:

val speechRecognizer = SpeechRecognizer.createSpeechRecognizer(this

After that, we will need to set up callbacks for this SpeechRecognizer object to tell us about its state, for example when the recognition starts, when it ends, the results and so on. I will let my activity implements the RecognitionListener with its callbacks methods, then I will set the SpeechRecognizer RecognitionListener to this activity which implements these callbacks:

speechRecognizer.setRecognitionListener(this)

And here is the overridden methods:

override fun onReadyForSpeech(params: Bundle?) {
    Log.d(TAG, "onReadyForSpeech")
}

override fun onRmsChanged(rmsdB: Float) {
    Log.d(TAG, "onRmsChanged")
}

override fun onBufferReceived(buffer: ByteArray?) {
    Log.d(TAG, "onBufferReceived")

}

override fun onPartialResults(partialResults: Bundle?) {
    Log.d(TAG, "onPartialResults")
}

override fun onEvent(eventType: Int, params: Bundle?) {
    Log.d(TAG, "onEvent $eventType")
}

override fun onBeginningOfSpeech() {
    Log.d(TAG, "onBeginningOfSpeech")
}

override fun onEndOfSpeech() {
    Log.d(TAG, "onEndOfSpeech")
}

override fun onError(error: Int) {
    Log.d(TAG, "onError $error")
}

override fun onResults(results: Bundle?) {
    Log.d(TAG, "onReadyForSpeech")
    val result = results?.getStringArrayList("results_recognition")
}

And thus you can do the same thing you have done with google dialog, but now you get your results from onResults, the names of these callbacks are self-expressive except onRMSChanged, which tell you the value of the sounds recording at the instance in float representation.

This leads us to the final step, which is to turn on the recognizer so as to recognize and receive the user’s speech, to do that we need to call the method startRecognize(), whereas to stop it we call the method stopRecognize(), in fact, it will stop immediately, but in some cases say that you wanted it to stop when it reached a certain condition, you have the way to do it.

Optional View

When the SpeechRecongizer starts recognizing the user’s speech, it will not be visible to the user and for that we have the onRMSChanged which you can use to make some animation or something similar and I found a View on github called SpeechRecognitionView that does just that like the Google Assistant, you can customize the bars’s color, their lengths, the number and many more, it is worth checking out.
You can also check the official documentation of SpeechRecognizer for further detail.

With that, we have reached the end of this article, I hope it got you interested in speech recognition even for a little, in fact, why to stop here, you can implement it in a more complex system using machine learning techniques, Natural Language Processing, and other more sophisticated methods.

Build Intro Sliders For Android in Easy Steps

Younes Charfaoui — Mon, 18 Oct 2021 16:02:27 +0000

Intro sliders are a very good way to introduce your application’s features for the new users. In this post, we will learn how to code a simple intro slider using a library called AppIntro that will do almost everything for you without boilerplate code.

Project Setup

Create an Android Studio project with an empty activity, then add then maven repository and a Gradle dependency for the library.
In the build.gradle project file, add this maven repository:

allprojects {
     repositories {
          ...
      maven { url 'https://jitpack.io' }
     }
}

and in the build.gradle app file and one of the following implementation:

dependencies {
     // AndroidX Capable version
     implementation 'com.github.AppIntro:AppIntro:5.1.0'

     // *** OR ***

     // Support Library compatibility version 
     implementation 'com.github.AppIntro:AppIntro:4.2.3'
}

This article presumes that you have some experience in building Android apps in Kotlin.

Create Intro Screens

Intro Screen are created in this step, First, get back to the newly created activity, and make it inherit from one of these two classes: AppIntro or AppIntro2, both have a unique style, here is what they look like:

I have chosen AppIntro2, so we will add the following line of code:

class WelcomeActivity : AppIntro2() {
    ...
}

In the OnCreate() method, you should delete the setContentView() method, because the layout will be generated automatically for us.

The is activity will handle a lot of things, such as the transitions from slide to slide, showing dots and buttons for next, skip and done, and many more.

Our job now is to provide it with the slides, we do have a lot of Option to do that:

Create fragments for your slides and add them with the addSlide() method.
Create a SliderPage object that has some attributes of the Slide like the Image drawable, title, description, and background color. After that, create a fragment from this object using the newInstance() factory method from the AppIntro2Fragment, and finally, use the addSlide() method to add this fragment.
Just like the previous method, but with the builder pattern to create the SliderPage object.

I ended up using the third method to create the slides, I added a method called showIntroSlides() to build the slides, here is how it looks:

private fun showIntroSlides() {

    val pageOne = SliderPagerBuilder()
        .title(getString(R.string.slide_one_top_text))
        .description(getString(R.string.slide_one_down_text))
        .imageDrawable(R.drawable.logo)
        .bgColor(getColor(R.color.slide_one))
        .build()

    val pageTwo = SliderPagerBuilder()
        .title(getString(R.string.slide_two_top_text))
        .description(getString(R.string.slide_two_down_text))
        .imageDrawable(R.drawable.notebook_with_logo)
        .bgColor(getColor(R.color.slide_two))
        .build()

    val pageThree = SliderPagerBuilder()
        .title(getString(R.string.slide_three_top_text))
        .description(getString(R.string.slide_three_down_text))
        .imageDrawable(R.drawable.bow_classic_brown)
        .bgColor(getColor(R.color.slide_three))
        .build()

    val pageFour = SliderPagerBuilder()
        .title(getString(R.string.slide_four_top_text))
        .description(getString(R.string.slide_four_down_text))
        .imageDrawable(R.drawable.taget_and_arrow)
        .bgColor(getColor(R.color.slide_four))
        .build()

    addSlide(AppIntro2Fragment.newInstance(pageOne))
    addSlide(AppIntro2Fragment.newInstance(pageTwo))
    addSlide(AppIntro2Fragment.newInstance(pageThree))
    addSlide(AppIntro2Fragment.newInstance(pageFour))
}

Now, we have created four pages, each one has a title and description from the strings files, alongside with an image drawable and background color.

Optional Overrides

onSkipPressed(): This method will be called when the user taps the Skip button, here we can move to the next activity.
onDonePressed(): This method will be called when the user taps the Done button after viewing all the slides, here we can also move to the next activity.
onSlideChanged(): When the user navigates between the slides, this method will be called.

Here is what it looks like after implementing the code:

private fun goToMain() {
    startActivity(Intent(this, MainActivity::class.java))
}

override fun onSkipPressed(currentFragment: Fragment?) {
    super.onSkipPressed(currentFragment)
    goToMain()
}

override fun onDonePressed(currentFragment: Fragment?) {
    super.onDonePressed(currentFragment)
    goToMain()
}

The Results

So far, we have implemented all the pieces, we are ready to display the intro, just call the created methods showIntroSlides() from OnCreate() and let the magic happen.

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    showIntroSlides()
}

Here are the results I got after running the application:

First Run Only

Until now, you should have the slides appear whenever the app starts, and this is maybe not the ideal behavior, instead, we need to show this slide one time only, when the user installs the app for the first time.

To add this feature, we need to know if it is the first time the user launches the app or not, we can achieve that by saving a flag variable, to be false in the first time launch and true after that.

For that we use SharedPrefrences, we can implement a helper class called PreferenceManager that will take care of saving this flag and modify it as we need. Here is a sample implementation:

class PreferencesManager(context: Context) {

    private val preferences: SharedPreferences
    private val editor: SharedPreferences.Editor

    init {
        preferences = context.getSharedPreferences(
                        PREFERENCE_NAME, 
                        PRIVATE_MODE)
        editor = preferences.edit()
    }

    fun isFirstRun() = preferences.getBoolean(FIRST_TIME, true)

    fun setFirstRun() {
        editor.putBoolean(FIRST_TIME, false).commit()
        editor.commit()
    }

    companion object {
        private const val PRIVATE_MODE = 0
        private const val PREFERENCE_NAME = "configuration"
        private const val FIRST_TIME = "isFirstRun"
    }
}

The two important methods in this class are:

setFirstRun() : this set method will make this preference false and save it in the SharedPreference.
isFirstRun() : this method returns a boolean indicating if it is the first time or not, and for the starting point, we will get the default value true.

Let us modify our activity onCreate() method and showIntroSlides():

private lateinit var manager: PreferencesManager

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    manager = PreferencesManager(this)

    if (manager.isFirstRun()) {
        showIntroSlides()
    } else {
        goToMain()
    }
}

private fun showIntroSlides() {
    manager.setFirstRun()
    ...
}

Now, if it is the first run we will show the IntroSlides, otherwise it will go to the main activity.

Additional Features

Besides showing slides and handling navigation, the AppIntro library comes with additional features, here are some of them:

Animation

AppIntro comes with some pager animations, just put one of the following lines in the showIntroSlides() method and you are done.

setFadeAnimation()
setZoomAnimation()
setFlowAnimation()
setSlideOverAnimation()
setDepthAnimation()

Runtime Permissions

AppIntro simplifies the new permissions model of Android 6.0 and above to a single line of code! just call theaskForPermissions() methods with an array of string’s permission and the slide number to show the permission in, here is an example:

askForPermissions(arrayOf(Manifest.permission.CAMERA), 2)

Translating

AppIntro supports a lot of languages, but if the words Next, Done or Skip are not in your language, you can change them by adding these strings to your strings.xml file:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools">
    <string name="app_intro_skip_button">
         [Translation for SKIP]
    </string>
    <string name="app_intro_next_button">
         [Translation for NEXT]
    </string>
    <string name="app_intro_back_button">
         [Translation for BACK]
    </string>
    <string name="app_intro_done_button">
         [Translation for DONE]
    </string>
    <string name="app_intro_image_content_description">    
         [Translation for "graphics"]
    </string>
</resources>

Conclusion

Finally, here are the two Gists files for WelcomeActivity and PreferenceManager.

I hope you enjoyed this article, and it helps you start using the AppIntro Library.