TapTargetView

repository·master·Indexed 26 days ago

https://github.com/keepsafe/taptargetview

An Android library for implementing feature discovery tap targets following Google's Material Design guidelines. It allows developers to highlight specific UI elements, create sequences of targets using TapTargetSequence, and target specific views or toolbar menu items. Supports minimum SDK 14 and provides community bindings for React Native, NativeScript, and Xamarin.

Tokens
2.7K
Snippets
6
Records
10
Agent score
90%

What's inside TapTargetView

  1. Configure GPG and Sonatype credentials for releasing

    master

    To release TapTargetView to Maven Central, you must configure your GPG signing key and Sonatype credentials in your local ~/.gradle/gradle.properties file.

    GPG Configuration:

    signing.keyId=<key ID of your GPG signing key>
    signing.password=<your key's passphrase>
    signing.secretKeyRingFile=/path/to/your/secring.gpg

    Sonatype Configuration: First, generate a User Token from the Sonatype OSS Nexus profile settings. Then, add the following to ~/.gradle/gradle.properties:

    mavenCentralUsername=<nexus username>
    mavenCentralPassword=<nexus password>
    SONATYPE_STAGING_PROFILE=com.getkeepsafe
    signing.keyId=<key ID of your GPG signing key>
    signing.password=<your key's passphrase>
    signing.secretKeyRingFile=/path/to/your/secring.gpg
    
    mavenCentralUsername=<nexus username>
    mavenCentralPassword=<nexus password>
    SONATYPE_STAGING_PROFILE=com.getkeepsafe
  2. Install TapTargetView via MavenCentral

    master

    Add MavenCentral to your repositories and include the TapTargetView dependency in your build.gradle file. The minimum supported SDK is 14.

       repositories { 
            mavenCentral()
       }
       
       dependencies {
             implementation 'com.getkeepsafe.taptargetview:taptargetview:x.x.x'
       }
  3. Configure Git for signed commits and tags

    master

    Ensure your local Git configuration uses the same GPG key used for signing binaries. This allows GitHub to verify your commits and tags.

    Run the following commands within the TapTargetView repository:

    git config user.email "your@email.com"
    git config user.signingKey "your-key-id"
  4. Publish a new version to Maven Central

    master

    Follow these steps to prepare and publish a new release:

    1. Prepare Files: Update the VERSION property in gradle.properties and update the changelog with the new version and date. Add a new ## [Unreleased] header for the subsequent release.
    2. Verify: Run ./gradlew clean check to ensure all tests pass.
    3. Commit & Tag: Create a signed commit and a signed tag:
      git commit -S -m "Release version X.Y.Z"
      git tag -s -a X.Y.Z
    4. **Publish**: Execute the publication task:
       ```bash
    ./gradlew :taptargetview:publishAndReleaseToMavenCentral --no-configuration-cache
    1. Push: Once the publication is complete and visible in Maven Central, push your tags to GitHub:
      git push --tags origin master
  5. Show a single TapTarget

    master

    Use TapTargetView.showFor(Activity, TapTarget, TapTargetView.Listener) to display a single feature discovery target. You can target a specific view using TapTarget.forView(View, String, String) or a custom area using TapTarget.forBounds(Rect, String, String).

    Colors can be specified using either @ColorRes or @ColorInt. Methods with the Int suffix expect a @ColorInt.

    TapTargetView.showFor(this,                 // `this` is an Activity
        TapTarget.forView(findViewById(R.id.target), "This is a target", "We have the best targets, believe me")
            // All options below are optional
            .outerCircleColor(R.color.red)      // Specify a color for the outer circle
    	.outerCircleAlpha(0.96f)            // Specify the alpha amount for the outer circle
            .targetCircleColor(R.color.white)   // Specify a color for the target circle
            .titleTextSize(20)                  // Specify the size (in sp) of the title text
            .titleTextColor(R.color.white)      // Specify the color of the title text
            .descriptionTextSize(10)            // Specify the size (in sp) of the description text
            .descriptionTextColor(R.color.red)  // Specify the color of the description text
            .textColor(R.color.blue)            // Specify a color for both the title and description text
            .textTypeface(Typeface.SANS_SERIF)  // Specify a typeface for the text
            .dimColor(R.color.black)           // If set, will dim behind the view with 30% opacity of the given color
            .drawShadow(true)                   // Whether to draw a drop shadow or not
            .cancelable(false)                  // Whether tapping outside the outer circle dismisses the view
            .tintTarget(true)                   // Whether to tint the target view's color
            .transparentTarget(false)          // Specify whether the target is transparent (displays the content underneath)
            .icon(Drawable)                     // Specify a custom drawable to draw as the target
            .targetRadius(60),                  // Specify the target radius (in dp)
        new TapTargetView.Listener() {          // The listener can listen for regular clicks, long clicks or cancels
            @Override
            public void onTargetClick(TapTargetView view) {
                super.onTargetClick(view);      // This call is optional
                doSomething();
            }
        });
  6. Create a sequence of TapTargets

    master

    Use TapTargetSequence to guide users through multiple targets in order. Define the targets using .targets(...), attach a TapTargetSequence.Listener to handle lifecycle events, and call .start() to begin the sequence.

    new TapTargetSequence(this)
        .targets(
            TapTarget.forView(findViewById(R.id.never), "Gonna"),
            TapTarget.forView(findViewById(R.id.give), "You", "Up")
                    .dimColor(android.R.color.never)
                    .outerCircleColor(R.color.gonna)
                    .targetCircleColor(R.color.let)
                    .textColor(android.R.color.you),
            TapTarget.forBounds(rickTarget, "Down", ":^)")
                    .cancelable(false)
                    .icon(rick))
        .listener(new TapTargetSequence.Listener() {
            // This listener will tell us when interesting(tm) events happen in regards
            // to the sequence
            @Override
            public void onSequenceFinish() {
                // Yay
            }
            
            @Override
            public void onSequenceStep(TapTarget lastTarget, boolean targetClicked) {
                // Perform action for the current target
            }
    
            @Override
            public void onSequenceCanceled(TapTarget lastTarget) {
                // Boo
            }
        });
    
    // Note: You must call .start() to begin the sequence
  7. Create a TapTarget for the Toolbar Navigation or Overflow view

    master

    If you want to highlight the navigation icon (e.g., the hamburger menu or back button) or the overflow menu (the three-dot menu) instead of a specific menu item, use the constructor that accepts a findNavView boolean.

    • If findNavView is true, the target will be the navigation icon/view.
    • If findNavView is false, the target will be the overflow menu view.