Verify Android PDF Form and Annotation Rendering

Direct answer

A rendered PDF page is a visual projection, not a complete account of its form data or interactive behavior. When Android sends a rasterized page to OCR or vision, the result depends on the selected renderer and page appearance. Form widgets and annotations can be governed by distinct PDF structures and render controls. Do not assume a screen preview, print output, text parser, and model bitmap contain the same information. Define the needed view: visible appearance, base page, or separately parsed field value. This guide covers read-only rendering, not form filling, annotation edits, or authoritative field extraction. Android's PDF framework changed substantially with Android V, API 35. The updated PdfRenderer exposes getPdfFormType(), which can classify a document as no form, AcroForm, XFA foreground, or full XFA. That classification is a dispatch hint, not a field-value API, a guarantee that every XFA feature is supported, or evidence that a script has been evaluated. Prior to API 35, the framework's basic PdfRenderer surface was primarily page rendering. Record the device API and the exact class used; do not treat an AndroidX PDF library version, an extension version, and a platform API level as interchangeable labels. Rendering controls also have version boundaries. Platform RenderParams documents text and highlight flags at API 35; free-text and stamp flags are marked version 36.1 and S Extensions 18. Form-content modes are separately marked version 36.1 and S Extensions 19. The documented RENDER_FORM_CONTENT_DEFAULT differs by renderer: PdfRenderer includes forms by default when the app targets API 35 or higher, while PdfRendererPreV always includes them by default. These modes are usable only where the referenced API surface exists. Do not rewrite version/extension labels as a feature on every similarly numbered Android release. For AndroidX, pin the library and use its own documented defaults. Form type, widget value, and visible appearance are not interchangeable. A field may have a logical value while its appearance stream is stale, absent, or rendered differently. PDF/A guidance requires conforming documents to render fields according to appearance dictionaries; that rule is limited to PDF/A, not a guarantee for arbitrary files. A bitmap supports a claim about observed pixels for a pinned file and configuration, not the raw field value, script/calculation execution, or user intent. If a task needs an exact identifier or amount, use a dedicated parser and human review. Use controlled fixtures that isolate each layer: no form, empty and filled AcroForm, available XFA types, text annotation, highlight, and unsupported annotation. Store source hash, expected field value if known, visible appearance, form type, and a named reference raster. Render with explicit flags where supported and compare pixels or regions. Keep display and print modes separate; matching one mode does not prove another should match. An empty supported-annotation list is not evidence that the document has no annotations: PdfRenderer.Page.getPageAnnotations() is marked version 36.1, returns supported types only, and may be empty when other types exist. Its reference does not list S Extensions 18; do not copy a render flag's extension availability to this method. Render flags also do not promise to expose every object. Record form type, flags, page, bitmap dimensions, target SDK, API/extension version, and unsupported states. Preserve source bytes; a bitmap is not an edited, flattened, or metadata-cleaned PDF. Keep OCR and PDF appearance tests separate. First verify the visible region, then evaluate parsing or OCR against its own reference. A parser may find text when a widget looks blank; OCR sees pixels but not hidden field state. Report each separately and limit conclusions to the tested renderer, system, fixtures, and flags. This does not establish Cove PDF support, universal viewer agreement, complete XFA/script behavior, or OCR accuracy gains.

OCR misses a filled field in a rendered PDF page

A document-processing workflow receives a filled PDF. Text search finds a field label, but OCR over a PdfRenderer bitmap sees an empty box. The source may contain an AcroForm or XFA form, and the renderer configuration and target API have not been recorded.

Decision

Inspect the PDF form classification and the exact renderer surface, then compare the rendered pixels with a known fixture. Keep logical field parsing and visual OCR as distinct routes; do not write back to the selected document.

Expected outcome

The team can report whether the tested bitmap included the expected widget appearance and whether the format or API surface remained unsupported, without claiming general PDF form extraction.

Evidence to collect

The claim becomes reviewable only when the following evidence is attached to the same artifact and test run:

• Pinned renderer and source-byte identity
• Form/widget and annotation reference fixtures
• Separate parser and OCR result records

Task quality needs a versioned corpus and acceptance rules. Fluent sample output is not an accuracy result.

Implementation workflow

1. Pin the PDF and rendering implementation. Record source-byte identity, Android API, extension state, target SDK, platform or AndroidX renderer class, dependency version, page index, and display or print mode. Keep the original file unchanged.
2. Classify form and annotation state. On API 35 or higher, record getPdfFormType without treating it as field extraction. Check the exact class and member availability for getPageAnnotations and each render flag separately; do not infer an extension backport from a neighboring API. Unsupported XFA or annotation types remain explicit unsupported states.
3. Set the intended visual contract. Decide whether the task needs base page appearance, rendered form widgets, or selected supported annotations. Use only flags documented for the exact API or pinned library and record defaults rather than assuming them.
4. Compare a reference fixture matrix. Render no-form, empty and filled AcroForm, available XFA, and supported/unsupported annotation fixtures. Compare named screen and print outputs with saved reference regions and preserve the source PDF.
5. Evaluate OCR only after rendering. Check the expected widget pixels first, then evaluate OCR or downstream vision on that bitmap. Report parser text, field values, rendered appearance, and OCR as separate observations.

Keep each transition observable. A failure should identify the stage, artifact, runtime, and recovery action without logging private user content.

Acceptance criteria

• The record pins the PDF bytes, renderer class/version, platform API, relevant extension, target SDK, page, render mode, and available annotation/form flags.
• API 35 form-type classification is not described as field extraction; API 35, version 36.1, and S Extension members are distinguished, including the target-SDK-sensitive PdfRenderer versus PdfRendererPreV form default.
• Fixture tests distinguish base page, form widget appearance, supported annotations, display/print mode, and OCR output without mutating source bytes.
• No claim is made that rendering proves field-value correctness, script evaluation, universal PDF compatibility, Cove support, or improved OCR accuracy.

Decision table

Failure patterns to prevent

• Treating form-type classification as field extraction
• Assuming adjacent flags share extension availability
• Treating empty supported annotations as no annotations

Also prevent silent fallback, unpinned artifacts, missing cancellation, and conclusions that combine unlike configurations. Store unsuccessful runs alongside successful ones.

Minimum reproducibility record

Release checklist

• ☐ The primary query is answered without an unsupported number.
• ☐ Every artifact and runtime is pinned.
• ☐ The representative task and failure policy are explicit.
• ☐ Lifecycle, cancellation, cleanup, and fallback are tested.
• ☐ User-content and network boundaries are documented.
• ☐ Result wording applies only to the recorded configuration.
• ☐ The page links to raw method or evidence when results are added.

Sources and related evidence

• ML Kit text recognition
• Android privacy and security
• Android Developers — PDF viewer framework/API levels
• Android API — PdfRenderer form types
• Android API — RenderParams annotation and form rendering flags
• Android API — PdfRenderer.Page annotation and text content
• PDF Association — PDF/A form-field appearance behavior

Chinese deployment and troubleshooting content is organized in the .奇连 AI 端侧专题.

Frequently asked questions