Configure Android preview stitching

Preview stitching combines compatible captured parts of an Android screen into a longer preview. It can help you inspect a scrollable layout, but it cannot show content that CUX never captured.

Applies to native Android SDK 1.2.0. Stitching is off by default and requires compatible CUX processing. Confirm processing support with CUX before enabling it.

Start with a representative screen

Choose a test screen with the layout your app actually uses. Include fixed headers, footers or sticky controls if they are part of the journey.

Check ordinary screenshots and masking first. Enabling stitching is not necessary to verify your initial SDK installation.

Enable the option in your initializer

Add previewStitching = true to your existing initialization call:

import io.cux.analytics_sdk.CuxAnalytics
import io.cux.analytics_sdk.logger.CuxLogLevel

CuxAnalytics.init(
    context = application,
    token = "YOUR_MOBILE_PROJECT_TOKEN",
    logLevel = CuxLogLevel.Production,
    needConfirmToStart = true,
    previewStitching = true
)

Keep your existing consent choice; this example waits for resumeCollectingData(). Do not add a second initializer. Omission or false keeps stitching off.

The option permits stitching when the screen and CUX processing support it. It does not guarantee a stitched result. Where stitching is unavailable, CUX uses ordinary visible-area screenshots when screenshot capture is available.

Declare regions for an advanced layout

The released API can register existing content, fixed and sticky Views:

val previewRegions = CuxAnalytics.monitorPreviewRegions(
    contentView = scrollableContent,
    fixedTop = headerView,
    fixedBottom = footerView,
    stickyView = stickySearchView
)

These are your actual layout Views. Omit optional regions that do not exist. Confirm that your layout is supported before using this advanced recipe.

This registration gives your app responsibility for announcing changes to the regions' appearance. On the main thread, call:

previewRegions.contentChanged()

Call it before the first capture and before changed content can draw. This includes asynchronous image/text updates, horizontal content changes and custom rendering changes. Ordinary vertical scrolling alone is not a content change.

If you omit a required notification, content can be treated as compatible after it has changed. Do not adopt region registration unless your app can signal those changes correctly.

Close the registration when its owning UI is destroyed:

previewRegions.close()

Initialization, stopping collection or detaching the registered UI ends the registration. Re-register a new UI instance rather than reusing an ended registration.

Understand the limits

Stitching uses captured compatible content. It does not fill gaps, recover unseen content or promise a complete full-screen preview.

Complex layouts may produce a partial preview or ordinary screenshots. A screen name does not prove that two images have the same layout. Fixed and sticky regions also need compatible geometry.

Stitching does not activate the new native scroll analytics or establish element exposure rates.

Verify before enabling more screens

1. Confirm processing support with CUX.
2. Scroll naturally through the test screen and check the result.
3. Inspect fixed/sticky regions and whether interaction overlays align with the visible elements.
4. Change content, navigate away and return. Check that incompatible states are not combined.
5. Inspect masks and test app performance on representative devices.

Keep the option off if the result is unsuitable for your app. See stitching troubleshooting.