TapTargetView for Android Tutorial

TapTargetView with an ImageView

In this section, you will learn how you can use TapTargetView to show a highlight circle on an ImageView.

Open up SettingsActivity and add the following code at the bottom of the onCreate() function.

TapTargetView.showFor(this, TapTarget.forView(ivAppIcon, getString(R.string.label_icon),
    "This is the icon that is currently being used for ${tvAppName.text}").
    tintTarget(false).cancelable(false), object : TapTargetView.Listener() {
  override fun onTargetClick(view: TapTargetView) {
    super.onTargetClick(view)
    view.dismiss(true)
  }
})

Here you show the highlight circle on ivAppIcon, and you can dismiss the highlight circle once you tap on it.

Build and run the app and go to the Settings screen to see the result.

TapTargetSequence on Multiple items

In this section, you will learn how to use a new class from the TapTargetView library, called TapTargetSequence. You can use this class when you want to show the highlight circle on many views one-by-one in a sequential fashion.

Open up FoodDetailActivity and add the following codes at the bottom of onCreate().

// 1
TapTargetSequence(this)
    // 2
    .targets(
        TapTarget.forView(btnShare, getString(R.string.label_share_food),
            getString(R.string.description_share_food))
            .cancelable(false).transparentTarget(true).targetRadius(70),
        TapTarget.forView(btnStore, getString(R.string.label_buy_food),
            getString(R.string.description_buy_food)).cancelable(false).
            transparentTarget(true).targetRadius(70),
        TapTarget.forToolbarNavigationIcon(toolbar, getString(R.string.label_back_arrow),
        getString(R.string.description_back_arrow)).cancelable(false)
            .tintTarget(true))
    // 3
    .listener(object : TapTargetSequence.Listener {
      override fun onSequenceStep(lastTarget: TapTarget?, targetClicked: Boolean) {
       }
      // 4
      override fun onSequenceFinish() {
        Toast.makeText(this@FoodDetailActivity, getString(R.string.msg_tutorial_complete),
            Toast.LENGTH_LONG).show()
      }
      // 5
      override fun onSequenceCanceled(lastTarget: TapTarget) {
      }
    })
    // 6
    .start()

Here’s a step-by-step breakdown:

1. TapTargetSequence(this): Here you define a TapTargetSequence by passing Context as an argument.
2. targets(): Here is where you include the views that you want the highlight circle to appear on them. You will pass the view name, title, and description.
3. onSequenceStep: You can perform a certain action once you complete a sequence such as showing a Toast message.
4. onSequenceFinish: Once you complete all the steps in the sequence you can show a Toast message indicating that the sequence is complete.
5. onSequenceCanceled: Called when you try to cancel a sequence such as tapping on an empty area to dismiss the highlight circle.
6. start(): This is the final part that you need to call for the highlight circle sequence to appear on the screen. Otherwise the sequence won’t appear.

Build and run the app and go to a detail screen to see the result.

Preventing Multiple Highlights

It seems that the highlight circle sequence appears every time you navigate to the FoodDetailActivity screen, how can you prevent that from happening?

One solution is to use a persistence mechanism like SharedPreferences to save whether or not the highlighting has been seen.

Create a new Kotlin file in the base app package and name it StatusUtils. Add the following code inside the file:

object StatusUtils {
  // 1
  fun storeTutorialStatus(context: Context, show: Boolean) {
    val preferences = context.getSharedPreferences("showTutorial", Context.MODE_PRIVATE)
    val editor = preferences.edit()
    editor.putBoolean("show", show)
    editor.apply()
  }

  // 2
  fun getTutorialStatus(context: Context): Boolean {
    val preferences = context.getSharedPreferences("showTutorial", Context.MODE_PRIVATE)
    return preferences.getBoolean("show", true)
  }
}

Here’s a step-by-step breakdown of the code in the new file:

1. storeTutorialStatus(): This function takes two parameters: a Context and a Boolean. You use this function to store the status of the highlight circle sequence inside SharedPreferences.
2. getTutorialStatus(): This function takes a Context as an argument, and you use this function to determine whether to show or hide the highlight circle sequence based on the boolean value that you stored using storeTutorialStatus().

Open up FoodDetailActivity.kt file and change TapTargetSequence to include the two functions from StatusUtils:

if (StatusUtils.getTutorialStatus(this)) {
  TapTargetSequence(this)
      .targets(
          TapTarget.forView(btnShare, getString(R.string.label_share_food),
              getString(R.string.description_share_food))
              .cancelable(false).transparentTarget(true).targetRadius(70),
          TapTarget.forView(btnStore, getString(R.string.label_buy_food),
              getString(R.string.description_buy_food)).cancelable(false).transparentTarget(true).targetRadius(70),
          TapTarget.forToolbarNavigationIcon(toolbar, getString(R.string.label_back_arrow),
              getString(R.string.description_back_arrow)).cancelable(false)
              .tintTarget(true)).listener(object : TapTargetSequence.Listener {
        override fun onSequenceStep(lastTarget: TapTarget?, targetClicked: Boolean) {
        }

        override fun onSequenceFinish() {
          Toast.makeText(this@FoodDetailActivity, getString(R.string.msg_tutorial_complete),
              Toast.LENGTH_LONG).show()
          StatusUtils.storeTutorialStatus(this@FoodDetailActivity, false)
        }

        override fun onSequenceCanceled(lastTarget: TapTarget) {
        }
      }).start()
}

Here you first check the status of the highlight circle sequence. If the status is true the sequence will start, and you then store the status of the sequence as false once it reaches onSequenceFinish().

If the status in SharedPreferences is false, you will not see the highlight circle sequence anymore when you navigate to the FoodDetailActivity screen.

Build and run the app to see the result. The first time you navigate to a detail screen, you will see the highlight sequence. Subsequent visits will not show the highlight sequence.

You can use a similar technique with SharedPreferences to determine whether or not to show the other highlights in the app once your user has seen them one or more times.

Where To Go From Here?

You can download the completed sample project using the download button at the top or bottom of the tutorial.

Be sure to check out TapTargetView GitHub documentation to find out all the things you can do to customize highlight circles to better match your app requirements.

We hope you enjoyed this tutorial on TapTargetView, and if you have any questions or comments, please join the forum discussion below!