BGABanner-Android: Auto-Scroll Banner and Onboarding Guide Library for Android

What BGABanner-Android Provides for Android Developers

BGABanner-Android is a Java library for Android that wraps the ViewPager component with two related use cases: infinite auto-scrolling banner carousels for displaying promotional or informational content, and sliding guide screens for app onboarding. Both use cases share the same BGABanner widget, configured differently.

The library handles the standard chores that accompany ViewPager-based banners: auto-play with configurable duration, pausing scroll on touch and resuming on release, indicator dots or numeric indicators with configurable positions, placeholder images during network load, and multiple transition animation presets. It also provides a built-in delegate pattern for click events on individual banner items, with duplicate-click protection already handled inside the library.

The library is hosted on Maven Central under the group ID cn.bingoogolapple. The license is Apache-2.0. It requires AndroidX and a minimum SDK level of 21.

Infinite Carousel, Guide Navigation, and Indicator Options

The README lists the core features as: guide/onboarding navigation, infinite cyclic scrolling on 1 or more pages, support for setting total page count from server-side data, configurable indicator position and ad text position, both image-based and numeric indicators, ViewPager transition animation variants, selecting a specific page programmatically, listening for item click events, placeholder image support during network loading, and synchronised scrolling of multiple ViewPager instances.

The indicator system is controlled by XML attributes. The position of the indicator dots can be set to top, bottom, left, or right. The indicator background, the dot drawable, and the spacing between dots are all configurable. A numeric indicator (showing, for example, "2 / 5") is available as an alternative to the dot indicator.

The touch handling is built into the component: touching the banner pauses auto-play, and releasing the touch resumes it. This is not something the developer needs to wire up separately.

The indicator position and the ad text caption position are configured independently through the XML attribute system. The `banner_indicatorGravity` attribute accepts gravity flags for placement; the custom attributes section of the README shows that `top` is one supported flag value. The `banner_pointContainerLeftRightPadding` attribute controls horizontal padding inside the indicator container. Individual dot spacing is set via `banner_pointLeftRightMargin`. These attributes let you reposition indicators without writing custom layout overrides. The transition effect between pages is declared once in XML via `banner_transitionEffect`; the README example uses `alpha`, which produces a fade rather than a standard slide.

Adding BGABanner-Android to an Android Project

The library requires AndroidX. Add `android.useAndroidX=true` to gradle.properties before using it. Then add the Gradle dependency:

implementation 'cn.bingoogolapple:bga-banner:latestVersion'

Replace `latestVersion` with the current version from the Maven Central artifact at central.sonatype.com/artifact/cn.bingoogolapple/bga-banner.

Next, add the BGABanner view to your layout XML. The following example configures it as an onboarding screen with a transparent indicator background, hollow dot drawables, and an alpha transition:

<cn.bingoogolapple.bgabanner.BGABanner
    android:id="@+id/banner_guide_content"
    style="@style/MatchMatch"
    app:banner_pageChangeDuration="1000"
    app:banner_pointAutoPlayAble="false"
    app:banner_pointContainerBackground="@android:color/transparent"
    app:banner_pointDrawable="@drawable/bga_banner_selector_point_hollow"
    app:banner_pointTopBottomMargin="15dp"
    app:banner_transitionEffect="alpha" />

The `banner_pageChangeDuration` attribute sets the auto-scroll interval in milliseconds. Setting `banner_pointAutoPlayAble` to false disables auto-play for a static guide screen.

Three Ways to Configure the Banner Data Source

The library provides three distinct data-source configuration methods depending on the content type.

The first approach uses a typed Adapter and is the recommended path for network images and for infinite scroll with fewer than three pages. Standard cyclic-scroll implementations in most ViewPager-based libraries require at least three pages to work correctly; the Adapter-based mode in this library handles the edge case of a single-page or two-page banner. The Adapter receives a model object and a pre-created view to fill. A Glide-based implementation loading network images with a placeholder looks like:

mContentBanner.setAdapter(new BGABanner.Adapter<ImageView, String>() {
    @Override
    public void fillBannerItem(BGABanner banner, ImageView itemView, String model, int position) {
        Glide.with(MainActivity.this)
                .load(model)
                .placeholder(R.drawable.holder)
                .error(R.drawable.holder)
                .centerCrop()
                .dontAnimate()
                .into(itemView);
    }
});

mContentBanner.setData(Arrays.asList("网络图片路径1", "网络图片路径2", "网络图片路径3"), Arrays.asList("提示文字1", "提示文字2", "提示文字3"));

The second approach passes a pre-built list of View objects and is intended for onboarding screens where each page has a distinct custom layout:

List<View> views = new ArrayList<>();
views.add(View.inflate(context, R.layout.layout_guide_one, null));
views.add(View.inflate(context, R.layout.layout_guide_two, null));
views.add(View.inflate(context, R.layout.layout_guide_three, null));
mContentBanner.setData(views);

The third approach passes local drawable resource IDs for pages that show only images:

BGALocalImageSize localImageSize = new BGALocalImageSize(720, 1280, 320, 640);
mContentBanner.setData(localImageSize, ImageView.ScaleType.CENTER_CROP,
        R.drawable.uoko_guide_background_1,
        R.drawable.uoko_guide_background_2,
        R.drawable.uoko_guide_background_3);

The BGALocalImageSize constructor takes max width, max height, min width, and min height, constraining the bitmap dimensions.

Click Events and Guide Screen Enter and Skip Buttons

Item click events use a delegate pattern. The BGABanner.Delegate interface provides a single onBannerItemClick callback that receives the banner, the item view, the model object, and the position:

mContentBanner.setDelegate(new BGABanner.Delegate<ImageView, String>() {
    @Override
    public void onBannerItemClick(BGABanner banner, ImageView itemView, String model, int position) {
        Toast.makeText(banner.getContext(), "点击了" + position, Toast.LENGTH_SHORT).show();
    }
});

The library handles duplicate-click prevention internally.

For guide screens, BGABanner manages the visibility of Enter and Skip buttons automatically. Pass the resource IDs and a GuideDelegate:

mContentBanner.setEnterSkipViewIdAndDelegate(R.id.btn_guide_enter, R.id.tv_guide_skip, new BGABanner.GuideDelegate() {
    @Override
    public void onClickEnterOrSkip() {
        startActivity(new Intent(GuideActivity.this, MainActivity.class));
        finish();
    }
});

If either the Enter or Skip button does not exist in the layout, pass 0 for that ID.

Limitations and Cases Where BGABanner-Android Does Not Fit

BGABanner-Android is a Java library. Teams working in Kotlin with Jetpack Compose will find that the library's View-based API sits awkwardly in a Compose project. Wrapping it in an AndroidView composable is possible but adds friction.

The minimum SDK is 21 and AndroidX is required. Projects targeting SDK levels below 21 or projects that have not migrated to AndroidX cannot use it.

The README does not document how the library handles configuration changes such as screen rotation during an active auto-play cycle, or what happens when the banner is in a RecyclerView that scrolls offscreen. The demo project is the recommended reference for edge cases: the README points to the demo/ directory for additional usage patterns, including Fresco integration via FrescoDemoActivity.

The library has no published changelog and no GitHub releases. The current version number must be checked on Maven Central rather than the repository itself.

BGABanner-Android vs. ViewPager2 and Maintenance Status

Android's Jetpack ViewPager2 is the SDK-native component for swipeable page content. ViewPager2 replaces the older ViewPager and supports both horizontal and vertical scrolling. The core difference from BGABanner-Android is that ViewPager2 provides the foundation but does not include auto-play, indicator dots, or placeholder image support out of the box. A developer who wants an auto-scrolling carousel with ViewPager2 must implement those features manually or combine it with TabLayout and a Handler.

BGABanner-Android bundles those features together, reducing the amount of boilerplate code. The trade-off is that it adds a third-party dependency and uses the older ViewPager internally, rather than ViewPager2. For new projects that prefer to stay on the official Jetpack stack, the additional setup cost of ViewPager2 with manual auto-play may be acceptable.

The last push to the repository was on 2026-07-27. The library is under the Apache-2.0 license. The Apache License permits use in commercial and open-source Android applications, requires preservation of the license text and copyright notice, but does not require derivative works to be open-source.

Editorial conclusion

BGABanner-Android is a practical library for Android teams that need a banner carousel or onboarding guide screen without writing the ViewPager boilerplate from scratch. It covers the common configurations through XML attributes and a three-method data-source API. Teams using Kotlin and Compose should evaluate whether Accompanist Pager or HorizontalPager is a better fit for their stack. Verify that your minimum SDK target is 21 or above and that AndroidX is enabled in your project before adding the dependency.

Frequently asked questions

Official sources

1. bingoogolapple/BGABanner-Android on GitHub
2. Issues
3. README