Repository files navigation

AppIntro is an Android Library that helps you build acool carousel intro for your App. AppIntro has support forrequesting permissions and helps you create a great onboarding experience in just a couple of minutes.

• Getting Started 👣
  • Adding a dependency
  • Basic usage
  • Java users
• Migrating 🚗
• Features 🧰
• Creating Slides 👩‍🎨
  • AppIntroFragment
  • AppIntroCustomLayoutFragment
• Configure 🎨
  • Slide Transformer
    • Custom Slide Transformer
  • Color Transition
  • Multiple Windows Layout
  • Indicators
  • Vibration
  • Wizard Mode
  • Immersive Mode
  • System Back button
  • System UI (Status Bar and Navigation Bar)
  • Bottom Bar Margin
• Permission 🔒
  • Slide Policy
• Example App 💡
• Translating 🌍
• Snapshots 📦
• Contributing 🤝
• Acknowledgments 🌸
  • Maintainers
  • Libraries
• License 📄
• Apps using AppIntro 📱

AppIntro is distributed throughJitPack.

To use it you need to add the following gradle dependency to yourbuild.gradle file of the module where you want to use AppIntro (NOT the root file).

repositories {    maven { url"https://jitpack.io" }}

dependencies {// AndroidX Capable version    implementation'com.github.AppIntro:AppIntro:6.3.1'// *** OR ***// Latest version compatible with the old Support Library    implementation'com.github.AppIntro:AppIntro:4.2.3'}

Please note that since AppIntro 5.x, the library supportsAndroid X. If you haven't migrated yet, you probably want to use a previous version of the library that uses theold Support Library packages (or tryJetifier Reverse mode).

To use AppIntro, you simply have to create a newActivity that extends AppIntro like the following:

classMyCustomAppIntro :AppIntro() {overridefunonCreate(savedInstanceState:Bundle?) {super.onCreate(savedInstanceState)// Make sure you don't call setContentView!// Call addSlide passing your Fragments.// You can use AppIntroFragment to use a pre-built fragment        addSlide(AppIntroFragment.createInstance(                title="Welcome...",                description="This is the first slide of the example"        ))        addSlide(AppIntroFragment.createInstance(                title="...Let's get started!",                description="This is the last slide, I won't annoy you more :)"        ))    }overridefunonSkipPressed(currentFragment:Fragment?) {super.onSkipPressed(currentFragment)// Decide what to do when the user clicks on "Skip"        finish()    }overridefunonDonePressed(currentFragment:Fragment?) {super.onDonePressed(currentFragment)// Decide what to do when the user clicks on "Done"        finish()    }}

Please note that youmust NOT call setContentView. TheAppIntro superclass is taking care of it for you.

Also confirm that you're overridingonCreate witha single parameter (Bundle) and you're not using another override (likeonCreate(Bundle, PersistableBundle)) instead.

Finally, declare the activity in your Manifest like so:

<activityandroid:name="com.example.MyCustomAppIntro"android:label="My Custom AppIntro" />

We suggest to don't declareMyCustomAppIntro as your first Activity unless you want the intro to launch every time your app starts. Ideally you should show the AppIntro activity only once to the user, and you should hide it once completed (you can use a flag in theSharedPreferences).

You can find many examples in java language in theexamples directory

If you're migratingfrom AppIntro v5.x to v6.x, please expect multiple breaking changes. You can find documentation on how to update your code on this othermigration guide.

Don't forget to check thechangelog to have a look at all the changes in the latest version of AppIntro.

• API >= 14 compatible.
• 100% Kotlin Library.
• AndroidX Compatible.
• Support forruntime permissions.
• Dependent only on AndroidX AppCompat/Annotations, ConstraintLayout and Kotlin JDK.
• Full RTL support.

The entry point to add a new slide is theaddSlide(fragment: Fragment) function on theAppIntro class.You can easily use it to add a newFragment to the carousel.

The library comes with several util classes to help you create your Slide with just a couple lines:

You can use theAppIntroFragment if you just want to customize title, description, image and colors.That's the suggested approach if you want to create a quick intro:

addSlide(AppIntroFragment.createInstance(    title="The title of your slide",    description="A description that will be shown on the bottom",    imageDrawable=R.drawable.the_central_icon,    backgroundDrawable=R.drawable.the_background_image,    titleColorRes=R.color.yellow,    descriptionColorRes=R.color.red,    backgroundColorRes=R.color.blue,    titleTypefaceFontRes=R.font.opensans_regular,    descriptionTypefaceFontRes=R.font.opensans_regular,))

All the parameters are optional, so you're free to customize your slide as you wish.

If you need to programmatically create several slides you can also use theSliderPage class.This class can be passed toAppIntroFragment.createInstance(sliderPage: SliderPage) that will createa new slide starting from that instance.

If you need further control on the customization of your slide, you can use theAppIntroCustomLayoutFragment.This will allow you pass your custom Layout Resource file:

AppIntroCustomLayoutFragment.newInstance(R.layout.intro_custom_layout1)

This allows you to achieve complex layout and include your custom logic in the Intro (see alsoSlide Policy):

AppIntro offers several configuration option to help you customize your onboarding experience.

AppIntro comes with a set ofSlide Transformer that you can use out of the box to animate your Slide transition.

Slide Transformers	Slide Transformers
Fade	Zoom
Flow	Slide Over
Depth	Parallax

You can simply callsetTransformer() and pass one of the subclass of the sealed classAppIntroPageTransformerType:

setTransformer(AppIntroPageTransformerType.Fade)setTransformer(AppIntroPageTransformerType.Zoom)setTransformer(AppIntroPageTransformerType.Flow)setTransformer(AppIntroPageTransformerType.SlideOver)setTransformer(AppIntroPageTransformerType.Depth)// You can customize your parallax parameters in the constructors.setTransformer(AppIntroPageTransformerType.Parallax(                titleParallaxFactor=1.0,                imageParallaxFactor=-1.0,                descriptionParallaxFactor=2.0))

You can also provide your custom Slide Transformer (implementing theViewPager.PageTransformer interface) with:

setCustomTransformer(ViewPager.PageTransformer)

AppIntro offers the possibility to animate thecolor transition between two slides background.This feature is disabled by default, and you need to enable it on your AppIntro with:

isColorTransitionsEnabled=true

Once you enable it, the color will be animated between slides with a gradient.Make sure you provide abackgroundColor parameter in your slides.

If you're providing custom Fragments, you can let them support the color transition by implementingtheSlideBackgroundColorHolder interface.

AppIntro is shipped with two top-level layouts that you can use.The default layout (AppIntro) has textual buttons, while the alternativelayout has buttons with icons.

To change the Window layout, you can simply change your superclass toAppIntro2.The methods to add and customize the AppIntro are unchanged.

classMyCustomAppIntro :AppIntro2() {// Same code as displayed in the `Basic Usage` section of this README}

Page	AppIntro	AppIntro2
standard page
last page

AppIntro supports two indicators out of the box to show the progress of the Intro experience to the user:

• DotIndicatorController represented with a list of Dot (the default)
• ProgressIndicatorController represented with a progress bar.

DotIndicator	ProgressIndicator

Moreover, you can supply your own indicator by providing an implementation of theIndicatorController interface.

You can customize the indicator with the following API on theAppIntro class:

// Toggle Indicator VisibilityisIndicatorEnabled=true// Change Indicator ColorsetIndicatorColor(    selectedIndicatorColor= getColor(R.color.red),    unselectedIndicatorColor= getColor(R.color.blue))// Switch from Dotted Indicator to Progress IndicatorsetProgressIndicator()// Supply your custom `IndicatorController` implementationindicatorController=MyCustomIndicator(/* initialize me*/)

If you don't specify any customization, aDotIndicatorController will be shown.

AppIntro supports providing hapticvibration feedback on button clicks.Please note that youneed to specify the Vibration permission in your app Manifest(the library is not doing it). If you forget to specify the permission, the app will experience a crash.

<uses-permissionandroid:name="android.permission.VIBRATE" />

You can enable and customize the vibration with:

// Enable vibration and set duration in msisVibrate=truevibrateDuration=50L

AppIntro supports aWizard mode where the Skip button will be replaced with the back arrow.This comes handy if you're presenting a Wizard to your users with a set of steps they need to do,and they might frequently go back and forth.

You can enable it with:

isWizardMode=true

If you want to display your Intro with a fullscreen experience, you can enable theImmersive mode. This willhide both theStatus Bar and theNavigation Bar and the user will have to scroll from the top of the screen toshow them again.

This allows you to have more space for your Intro content and graphics.

You can enable it with:

setImmersiveMode()

You can lock the System Back button if you don't want your user to go back from intro.This could be useful if you need to request permission and the Intro experience is not optional.

If this is the case, please set to true the following flag:

isSystemBackButtonLocked=true

You can customize theStatus Bar, and theNavigation Bar visibility & color with the following methods:

// Hide/Show the status BarshowStatusBar(true)// Control the status bar colorsetStatusBarColor(Color.GREEN)setStatusBarColorRes(R.color.green)// Control the navigation bar colorsetNavBarColor(Color.RED)setNavBarColorRes(R.color.red)

By default, the slides use the whole size available in the screen, so it might happen that thebottom bar overlaps the content of the slide if you have set the background color to anon-transparent one.If you want to make sure that the bar doesn't overlap the content, use thesetBarMargin functionas follows:

setBarMargin(true)

AppIntro simplifies the process of requestingruntime permissions to your user.You can integrate one or more permission request inside a slide with theaskForPermissions method inside your activity.

Please note that:

• slideNumber is in aOne-based numbering (it starts from 1)
• You can specify more than one permission if needed
• You can specify if the permission is required. If so, users can't proceed if he denies the permission.

// Ask for required CAMERA permission on the second slide.askForPermissions(    permissions= arrayOf(Manifest.permission.CAMERA),    slideNumber=2,     required=true)// Ask for both optional ACCESS_FINE_LOCATION and WRITE_EXTERNAL_STORAGE// permission on the third slide.askForPermissions(    permissions= arrayOf(Manifest.permission.ACCESS_FINE_LOCATION,Manifest.permission.WRITE_EXTERNAL_STORAGE    ),    slideNumber=3,     required=false)

Should you need further control on the permission request, you can override those two methods on theAppIntro class:

overridefunonUserDeniedPermission(permissionName:String) {// User pressed "Deny" on the permission dialog}overridefunonUserDisabledPermission(permissionName:String) {// User pressed "Deny" + "Don't ask again" on the permission dialog}

If you want to restrict navigation between your slides (i.e. the user has to toggle a checkbox in order to continue),theSlidePolicy feature might help you.

All you have to do is implementSlidePolicy in your slides.

This interface contains theisPolicyRespected property and theonUserIllegallyRequestedNextPage methodthat you must implement with your custom logic

classMyFragment :Fragment(), SlidePolicy {// If user should be allowed to leave this slideoverrideval isPolicyRespected:Boolean        get()=false// Your custom logic here.overridefunonUserIllegallyRequestedNextPage() {// User illegally requested next slide.// Show a toast or an informative message to the user.    }}

You can find a full working example ofSlidePolicy in theexample app - CustomSlidePolicyFragment.kt

AppIntro comes with asample app full of examples and use case that you can use as inspiration for your project. You can find it inside the/example folder.

You can get adebug APK of the sample app from thePre Merge GitHub Actions job as anoutput artifact here.

Do you want to help AppIntro becoming international 🌍? We are more than happy!AppIntro currently supportsthe following languages.

To add a new translation just add a pull request with a newstrings.xml file inside avalues-xx folder (wherexx is atwo-letter ISO 639-1 language code).

In order to provide the translation, your file needs to contain the following strings:

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

An updated version of the English version translation isavailable here.

If a translation in your language is already available, please check it and eventually fix it (all the strings should be listed, not just a subset).

Development of AppIntro happens on themain branch. You can getSNAPSHOT versions directly from JitPack if needed.

repositories {    maven { url"https://jitpack.io" }}

dependencies {  implementation"com.github.AppIntro:AppIntro:main-SNAPSHOT"}

⚠️ Please note that the latest snapshot might beunstable. Use it at your own risk⚠️

We're offering support for AppIntro on the#appintro channel on KotlinLang Slack. Come and join the conversation over there. If you don't have access to KotlinLang Slack, you canrequest access here.

We're looking for contributors! Don't be shy. 👍 Feel free to open issues/pull requests to help me improve this project.

• When reporting a new Issue, make sure to attachScreenshots,Videos orGIFs of the problem you are reporting.
• When submitting a new PR, make sure tests are all green. Write new tests if necessary.

AppIntro is currently developed and maintained by theAppIntro GitHub Org. When submitting a new PR, please ping one of:

• @paolorotolo
• @cortinico

AppIntro is not relying on any third party library other than those from AndroidX:

• androidx.appcompat:appcompat
• androidx.annotation:annotation
• androidx.constraintlayout:constraintlayout

    Copyright (C) 2015-2020 AppIntro Developers    Licensed under the Apache License, Version 2.0 (the "License");    you may not use this file except in compliance with the License.    You may obtain a copy of the License at       http://www.apache.org/licenses/LICENSE-2.0    Unless required by applicable law or agreed to in writing, software    distributed under the License is distributed on an "AS IS" BASIS,    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.    See the License for the specific language governing permissions and    limitations under the License.

If you are using AppIntro in your app and would like to be listed here, please open a pull request and we will be more than happy to include you: