Docs | inkPDF Portal

⚙️ Installation

Add the ink_pdf plugin to your pubspec.yaml. Since it is distributed via private Git, ensure your environment has SSH access to GitHub configured.

dependencies:
  ink_pdf:
    git:
      url: git@github.com:CodeShield-Solutions/inkPDF.git
      ref: main

Crucial Android Setup

Add the Flutter Maven repository to your app's android/build.gradle:

allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://storage.googleapis.com/download.flutter.io' }
    }
}

🚀 Usage

Import the package and use the InkPdfCanvas widget. It handles the heavy lifting of native rendering and security on-device.

import 'package:ink_pdf/ink_pdf.dart';

InkPdfCanvas(
  path: "/absolute/path/to/your/document.pdf", // or use 'url' for remote files
  userId: "user_123", // Optional: unique identifier
  password: "your_pdf_password", // Optional: if the PDF is encrypted
  initialPage: 5, // Optional: jump to page 5 on load
  annotationMode: 'export', // 'export' (XFDF) or 'merge' (Save directly to PDF)
  xfdf: '<?xml version="1.0" encoding="UTF-8"?><xfdf ...>', // Optional: load existing annotations
  watermark: {
    'text': 'user@example.com',
    'opacity': 0.3,
    'size': 20.0,
    'color': '#808080',
    'angle': -45.0,
    'position': 'all', // can be: center, all, top-left, etc.
  },
  onRenderCreated: (controller) {
    print("✅ Renderer Ready!");
    // You can save this controller to call methods like controller.saveAnnotations()
  },
  onMessage: (type, payload) {
    if (type == 'pageChange') {
      print("📖 Current Page: ${payload['page']} / ${payload['total']}");
    }
  },
)

🧰 API Reference

Parameter	Type	Default	Description
path	String?	null	Absolute local file path to the PDF.
url	String?	null	Remote URL pointing to a PDF.
userId	String?	null	Optional unique identifier for the user.
password	String?	null	PAID ONLYPassword for encrypted PDFs.
xfdf	String?	null	PAID ONLYInitial annotation data in XFDF format.
watermark	Map?	null	Configuration for secure overlays.
annotationMode	String?	'export'	PAID ONLY'export' (XFDF) or 'merge' (Burn into PDF).
initialPage	int?	1	PAID ONLYStarting page number (1-indexed).

🔍 Parameter Details

Secure Device Tracking (MAU)

inkPDF uses a Secure Hardware Fingerprint to track Monthly Active Users (MAU). This fingerprint is generated using a combination of hardware IDs (Serial Numbers, Platform UUIDs) and app identifiers, hashed via SHA-256.

Privacy & Security

Is any PII (Personally Identifiable Information) sent? No. Our SDK generates a one-way cryptographic hash of hardware properties. We never see or store the actual serial numbers or original device names.

1. Tamper-Resistant: Because the tracking is tied to the hardware and not a user-provided string, it cannot be spoofed by client-side code modifications.
2. Automated Resets: The MAU count for each device automatically resets at the beginning of every calendar month.
3. Fairness: This architecture ensures that both you and CodeShield have a verifiable, accurate, and secure metric for application usage.

path & url

Use path when the PDF is already downloaded or exists in the local file system. Must be an absolute path (e.g., /storage/emulated/0/...).
Use url to load a PDF directly from a web server. The viewer handles fetching and caching.

Requirement: One of these must be provided.

Watermark configuration

Prevent unauthorized captures by overlaying dynamic text across one or all pages.

text: Display string (e.g., 'User: John Doe').
opacity: 0.0 (hidden) to 1.0 (opaque). Default: 0.3.
position: Options: all (Default 3x3 grid), center, top-left, bottom-right, etc.

onRenderCreated & onMessage

onRenderCreated: Returns an InkPdfController. Use it to programmatically scroll or trigger manual saves.

onMessage: A powerful bridge for native events:

'viewerReady'

PDF fully loaded and UI active.

'saveAnnotations'

Returns XFDF string on every change.

Trial License Limitations

Parameters marked as PAID ONLY are enforced at the Native Binary level. If the SDK detects a Trial license, it will automatically filter out these parameters before rendering the document. This is a security measure to ensure that premium features like encrypted PDF support, XFDF injection, and custom watermarking are reserved for subscribed partners.

💾 Handling Annotations

inkPDF supports industry-standard XFDF format. This keeps user data separate from the document, enabling easy storage in your database.

1. Loading saved work

InkPdfCanvas(
  path: pdfPath,
  xfdf: savedXfdfString, // Re-load annotations from DB
)

2. Auto-Save with Bridge

onMessage: (type, payload) {
  if (type == 'saveAnnotations') {
    final String xfdf = payload.toString();
    database.save(docId, xfdf);
  }
}

🛠 Troubleshooting

Force Update

Fetch the latest native bindings and bug fixes from GitHub:

flutter pub upgrade ink_pdf

Nuclear Option

If build caches are corrupted on your machine:

flutter pub cache clean
flutter pub get

🔄 Version Enforcement & Mandatory Updates

A Note to Developers

"To maintain the security of document rendering and cross-platform compatibility, we occasionally release mandatory updates. If an update is mandatory, older versions of the plugin will be restricted from opening PDFs."

Action Required

Integrate this verify-check into your admin portal.

Monitoring Endpoint

Hit this endpoint periodically to stay synced with inkPDF's minimum requirements and update dates.

GET https://www.server.inkpdf.net/licenses/version-info

Expected Object API

latestVersion Current stable release
minVersion Version threshold for blocking
enforcementDate Cut-off date for old versions
blockLegacy Automatic Blocking status

Critical Enforcement Policy

Mandatory updates are critical. If your application's integrated plugin version is below our minimum threshold, users will see an 'Update Required' screen on their devices. We strictly recommend caching this data in your dashboard to avoid unplanned service interruptions for your users.