Add link annotations to PDFs on Android

Nutrient Android SDK supports common types of link annotations, including page, web, and email links. Tapping on such a link will automatically invoke the saved action (see PDF actions), as well as the correct event, such as changing the page or opening a URL.

Custom link handling

You can add custom URI handling to your application using the DocumentListener#onPageClick method (see the document listeners guide for more information). The following code snippet can be used to detect any custom URI, like custom://my.custom.uri/with/1/parameter, or a standard web URL, like https://nutrient.io:

override fun onPageClick(document: PdfDocument, pageIndex: Int, event: MotionEvent?,
                         pagePosition: PointF?, clickedAnnotation: Annotation?): Boolean {
    var handled = false;

    // If no annotation was clicked, `clickedAnnotation` may be null.
    // Otherwise, check if the clicked annotation is a link annotation.
    if (clickedAnnotation is LinkAnnotation && clickedAnnotation.action is UriAction) {
        // Extract the URI of the annotation action.
        val uri : Uri = Uri.parse((clickedAnnotation.action as UriAction).uri)

        // You can now check if you would like to handle the URI yourself, e.g. by using
        // a `UriMatcher` or some custom logic.
        if (isCustomUri(uri)) {
            Toast.makeText(this, "We have detected a custom Uri!", Toast.LENGTH_SHORT).show();
            handled = true;
        }
    }

    return handled;
}

@Override
public boolean onPageClick(@NonNull PdfDocument document, int pageIndex, @Nullable MotionEvent event,
                           @Nullable PointF pagePosition, @Nullable Annotation clickedAnnotation) {
    boolean handled = false;

    // If no annotation was clicked, `clickedAnnotation` may be null.
    // Otherwise, check if the clicked annotation is a link annotation.
    if (clickedAnnotation != null && clickedAnnotation instanceof LinkAnnotation) {
        LinkAnnotation linkAnnotation = (LinkAnnotation) clickedAnnotation;

        // Every link annotation may have an action defined.
        final Action action = linkAnnotation.getAction();

        // Check if an action exists and if it is a `UriAction`.
        if (action != null && action instanceof UriAction) {
            // Extract the URI of the annotation action.
            Uri uri = Uri.parse(((UriAction) action).getUri());

            // You can now check if you would like to handle the URI yourself, e.g. by using
            // a `UriMatcher` or some custom logic.
            if (isCustomUri(uri)) {
                Toast.makeText(this, "We have detected a custom Uri!", Toast.LENGTH_SHORT).show();
                handled = true;
            }
        }
    }

    return handled;
}

Return true in onPageClick if you have handled the annotation click yourself. This will consume the event and keep Nutrient from invoking the default handler.

Autodetecting links

Nutrient is capable of analyzing the page contents and automatically adding links to URLs and phone numbers. This is slightly expensive since text needs to be parsed and analyzed, but it’s done in a background process, so in most cases, it’s not noticeably slower. Set PdfActivityConfiguration.Builder#automaticallyGenerateLinks(boolean) to true to enable detection for all supported types.

Note that autodetecting a link only works if there is no overlapping link annotation at the same location the autodetected link would be located at on a PDF page. This is done to avoid creating duplicate link annotations over text that already has a link annotation saved in the PDF.