WOPI for Mobile: Edit Documents on iOS and Android

Implementing WOPI for Mobile: Extending Document Editing to iOS and Android Apps

Enterprise mobile adoption has long since passed the point of return. Workforces that once relied on desktop and laptop access to corporate document management systems now expect to open, review, and edit documents from iOS and Android devices as a matter of course. For ISVs and enterprise software teams that have already invested in WOPI-based document editing on the web, the natural next step is extending that capability to mobile — and the path is more structured than many developers assume.

WOPI mobile integration for iOS and Android is not a simple port of your web implementation. Mobile platforms introduce distinct launch flows, URL scheme invocation patterns, authentication challenges specific to device-bound contexts, offline requirements, and network constraints that require thoughtful adaptation. This article provides a technical guide to each of these areas, drawing on the mobile-specific aspects of the WOPI protocol and the CSPP Plus programme’s requirements for mobile-capable implementations.

How Mobile WOPI Differs from Web WOPI

Before diving into implementation specifics, it is worth establishing the conceptual differences between web-based and mobile WOPI integration. On the web, your WOPI host provides a URL that the browser loads into an iframe, and Microsoft Office for the web (or another WOPI-compatible editor) renders the document in that frame. The host, the browser, and the editor all operate within the same HTTP session model.

On mobile, the flow is fundamentally different. Microsoft Office for iOS and Android are native applications, not browser-based renderers. When a user wants to open a document from your mobile application in Office, you are not launching a web page — you are invoking the Office native app via a platform-specific URL scheme, passing the document location and authentication context through that invocation. The WOPI host still serves the document, but the mobile app acts as an orchestrator rather than a container.

This distinction has several downstream implications:

App invocation replaces iframe embedding. Your mobile app constructs a URI that hands off control to the Office app. Return-to-app handling requires you to register your own URL scheme to receive control back after editing completes.
Authentication must be pre-established. Unlike web WOPI, where the user may authenticate inline as part of the editor load, mobile invocation typically requires authentication to be completed before the handoff, with a token passed to the WOPI endpoint.
Offline capability is a user expectation. Mobile users frequently encounter network interruptions. A mobile WOPI implementation that fails ungracefully on a train or in an underground car park will generate immediate negative feedback.

WOPI Discovery for Mobile Surfaces

WOPI discovery in a mobile context follows the same endpoint structure as web discovery — your WOPI host exposes a discovery XML document that Office applications use to determine what actions and file types are supported. However, mobile-specific urlsrc templates and action names are used alongside the familiar view and edit actions.

For CSPP Plus mobile document editing, your discovery document should include mobile-specific action entries. The action name mobileView is used for read-only document rendering on mobile, while mobileEdit signals support for full editing via the Office mobile apps. These entries follow the same XML structure as standard WOPI actions:

<action name="mobileEdit"
        requires="locks,update"
        urlsrc="https://word-edit.officeapps.live.com/we/wordeditorframe.aspx?
                ui=en-US&amp;rs=en-US&amp;wopisrc={WOPISrc}&amp;mobile=1"/>

The mobile=1 query parameter signals to the Office service that the requesting context is mobile, which influences how the service handles the session — including whether it returns mobile-optimised resources and whether it applies mobile-specific timeout policies.

Your CheckFileInfo response for mobile sessions should include several properties that are either specific to mobile contexts or more critical in mobile scenarios than on the web:

SupportsLocks: Required for editing operations, including mobile editing.
UserCanWrite: Controls whether the edit action is available to the current user.
CloseUrl: The URL the Office mobile app should navigate to (or invoke) when the user taps the close button. On mobile, this is typically a deep link back into your application rather than a web URL.
HostEditUrl and HostViewUrl: Used when the Office app needs to present a native URL to the user or return them to the host context.
BreadcrumbDocName and BreadcrumbFolderName: These are rendered in the Office mobile UI to show the document’s location context — more prominent on mobile than on desktop.

Platform-Specific Launch Flows

iOS: URL Schemes and Universal Links

On iOS, you invoke Office applications using registered URL schemes. Microsoft Office for iOS registers the ms-word:, ms-excel:, ms-powerpoint:, and ms-onenote: schemes. To open a document for editing, your iOS app constructs a URL of the following form:

ms-word:ofe|u|https://your-wopi-host.com/wopi/files/document-id

The components are:

ms-word: — The registered URL scheme for Microsoft Word on iOS.
ofe — The action code. ofe means “Open For Edit”. Use ofv for “Open For View”.
u| — Indicates that the next segment is the document URL.
https://your-wopi-host.com/wopi/files/document-id — The WOPI files endpoint URL for the document.

Before invoking this URL, verify that the Office application is installed using UIApplication.shared.canOpenURL(). If Office is not installed, surface an appropriate message — mobile users should not encounter a silent failure when tapping an edit button.

Return-to-app handling on iOS uses the |-delimited parameter block in the invocation URL:

ms-word:ofe|u|https://your-wopi-host.com/wopi/files/document-id|e|ms-yourapp://edit-complete

The |e| parameter specifies the URL your app registers to receive control when the user closes Office. Register this custom URL scheme in your iOS app’s Info.plist and handle it in your AppDelegate or SceneDelegate to update your UI appropriately (for example, refreshing the document list or showing a confirmation that changes were saved).

Universal Links offer a more robust alternative to custom URL schemes for return-to-app handling, particularly in enterprise deployments where IT policy may restrict custom scheme registration. With Universal Links, Office invokes a web URL you own, which your app intercepts via its Associated Domains entitlement. This pattern also works more reliably across iOS version updates.

Android: Intent-Based Invocation

On Android, Office applications are invoked via Android Intents rather than URL schemes. The pattern is conceptually similar but uses Android’s Intent system:

val intent = Intent(Intent.ACTION_VIEW).apply {
    data = Uri.parse("ms-word:ofe|u|https://your-wopi-host.com/wopi/files/document-id")
    setPackage("com.microsoft.office.word")
    addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
}

if (packageManager.resolveActivity(intent, 0) != null) {
    startActivity(intent)
} else {
    // Office not installed — redirect to Play Store or surface message
}

Setting the package explicitly with setPackage() ensures that the Intent resolves directly to the Office Word app rather than presenting the user with an app chooser. Use com.microsoft.office.excel and com.microsoft.office.powerpoint for Excel and PowerPoint respectively.

For return-to-app handling on Android, register your app as a handler for a custom scheme and pass it in the invocation URL using the same |e| parameter pattern as iOS. Alternatively, Android’s App Links (the Android equivalent of iOS Universal Links) can be used for more robust deep link handling in enterprise contexts.

Authentication Patterns for Mobile WOPI

MSAL for Mobile

Authentication is where mobile WOPI integration diverges most significantly from web-based patterns. In a web context, the user is typically already authenticated to your application in the browser, and a session cookie or bearer token flows naturally into the WOPI endpoint calls that the Office editor makes. On mobile, the Office app makes server-side WOPI calls on behalf of the user, and those calls must be authenticated independently of the mobile app session.

The recommended approach for CSPP Plus mobile document editing is to use Microsoft Authentication Library (MSAL) for iOS and Android to acquire an access token, then embed that token in the WOPI files URL as a query parameter or pass it via the access_token mechanism:

https://your-wopi-host.com/wopi/files/document-id?access_token=eyJ...

Your WOPI host validates this token on each request from the Office mobile app. The token should be scoped to the minimum permissions required for the WOPI operations the user will perform — read-only tokens for view actions, read-write tokens for edit actions.

MSAL on both iOS and Android supports the system browser and in-app browser tab authentication flows, which are required for modern Microsoft identity platform interactions. Avoid using embedded WebViews for authentication — Microsoft’s identity platform actively discourages this pattern, and it will not work correctly with conditional access policies that many enterprise customers have in place.

Token Expiry and Refresh in Mobile Contexts

Mobile WOPI sessions may run significantly longer than web sessions — a user might open a document on their phone, switch to another app for an extended meeting, and return to finish editing an hour later. Token expiry must be handled carefully.

Your WOPI host should validate token expiry on each request and return HTTP 401 when a token has expired, rather than allowing operations to proceed with a stale token. The WOPI client will surface an authentication error to the user, who can re-authenticate through your app. Design your token lifetimes and refresh flows accordingly — typically a one-hour access token lifetime with a refresh token valid for longer periods works well for mobile document editing sessions.

Biometric Authentication and Device-Bound Credentials

Enterprise mobile deployments increasingly require biometric authentication as part of the document access flow, particularly for regulated content. On iOS, this means integrating Face ID or Touch ID via the LocalAuthentication framework before initiating the WOPI handoff. On Android, the BiometricPrompt API provides equivalent functionality.

The recommended pattern is to gate the WOPI invocation URL behind a biometric check within your app, acquiring or refreshing the access token only after successful biometric authentication. The biometric authentication itself should not be part of the WOPI protocol flow — keep it within your application layer before the Office handoff begins. This separation ensures that cloud document editing security compliance requirements around authentication strength are met within your application boundary, where you have full control.

Handling Offline Capability

The Offline Document Cache

Enterprise users on mobile expect to access documents when connectivity is unreliable. A robust mobile WOPI implementation includes an offline document cache that allows previously opened documents to be accessed and edited without a live network connection.

The cache should store the complete binary document content along with a metadata record capturing the document identifier, the last-known server version identifier (from the X-WOPI-ItemVersion response header), and the cached timestamp. On iOS, this data belongs in the application’s sandboxed storage, not in iCloud-synced locations (unless explicitly designed for that). On Android, use internal storage rather than external storage for documents that may contain sensitive enterprise content.

When the user opens a cached document offline, your app serves the document from the local cache rather than making a WOPI GetFile call. The document can be opened in a local viewer or, where supported, a local editing mode — though full Office editing via the WOPI handoff requires network connectivity to the Office service.

Sync Conflict Resolution

When the user has made local edits to a cached document and network connectivity is restored, your application must synchronise those changes with the WOPI host. The protocol provides the X-WOPI-ItemVersion header to support optimistic concurrency — your host returns the current version on GetFile and CheckFileInfo responses, and your mobile app records this version when caching the document.

When syncing a locally edited document back to the server, the resolution flow should be:

Check the server version. Call CheckFileInfo to retrieve the current server version. Compare it with the version recorded at cache time.
Detect conflicts. If the server version has changed since the document was cached, a concurrent modification has occurred — another user or device has updated the document while the mobile user was working offline.
Apply a resolution strategy. Three strategies are commonly used:
- Last-writer-wins: Upload the local version regardless, overwriting the server version. Simple to implement but risks data loss if the server version contains important changes.
- User-prompted merge: Present the user with both the local version and the server version, and let them choose which to retain or manually merge. Appropriate for documents where data loss is unacceptable.
- Automatic merge: Attempt a programmatic merge of the two versions. Practical for structured data (such as Excel workbooks where conflicting edits are in different cell ranges) but complex to implement reliably for rich text documents.

For most enterprise mobile WOPI implementations, user-prompted merge with the option to retain either version is the safest default. Implement automatic last-writer-wins only if your user research confirms that simultaneous offline edits are rare in your use case and the cost of occasional data loss is acceptable.

A minimal conflict resolution UI should display the document name, the timestamp of the server version, and the timestamp of the local version, and offer two clear actions: keep local version (uploading it to the server) or keep server version (discarding local edits). Always give the user the option to download both versions as separate files before making their choice.

Performance Optimisation for Mobile Networks

Adaptive Chunk Sizing

If your WOPI host implements CSPP Plus chunked file transfer, mobile clients benefit disproportionately compared to desktop clients — mobile networks have higher latency, more variable bandwidth, and are more prone to interruptions that benefit from chunk-level retry rather than whole-file retry.

For mobile sessions, dynamically adjust your chunk size based on network conditions. iOS provides NWPathMonitor and Android provides ConnectivityManager to detect the active network interface (Wi-Fi versus cellular) and estimated bandwidth. On Wi-Fi, a 10 MB chunk size is appropriate. On cellular, reduce to 2–4 MB to limit the impact of individual chunk failures on the user experience.

Pass the detected network context to your WOPI host via a custom header or query parameter in the session initialisation request, and have the host respond with an appropriate MaxChunkSize recommendation. This server-driven approach allows you to adjust chunk sizing based on server-side load conditions as well as client network conditions.

Request Compression and Caching Headers

For CheckFileInfo responses, include Cache-Control headers that allow mobile clients and intermediate proxies to cache the response for short durations (30–60 seconds). Reducing the frequency of CheckFileInfo round-trips is particularly valuable on mobile, where each round-trip carries higher latency overhead than on a wired enterprise network.

For the GetFile response, implement support for the If-None-Match header using the X-WOPI-ItemVersion value as the ETag. If the Office mobile app requests a file that has not changed since the last request, respond with HTTP 304 Not Modified rather than retransmitting the full document. On cellular connections, avoiding a redundant multi-megabyte download can meaningfully improve the user experience.

Background Transfer Sessions

On iOS, use URLSession with a background configuration for document download and upload operations. This allows transfers to continue even if the user switches away from your app or the system suspends it. The WOPI PutFile operation — which saves the document back to your host — is particularly important to complete reliably, even if the user has switched to another app immediately after tapping Save in Office.

On Android, WorkManager with the appropriate network constraint (NetworkType.CONNECTED) provides equivalent background transfer capability, with automatic retry on network restoration.

// iOS: Configure a background URLSession for WOPI file transfers
let config = URLSessionConfiguration.background(
    withIdentifier: "com.yourapp.wopi-transfer"
)
config.isDiscretionary = false
config.sessionSendsLaunchEvents = true
let session = URLSession(configuration: config, delegate: self, delegateQueue: nil)

// Android: Schedule a PutFile sync using WorkManager
val syncRequest = OneTimeWorkRequestBuilder<WopiSyncWorker>()
    .setConstraints(
        Constraints.Builder()
            .setRequiredNetworkType(NetworkType.CONNECTED)
            .build()
    )
    .setInputData(workDataOf(
        "documentId" to documentId,
        "localPath" to localFilePath
    ))
    .build()
WorkManager.getInstance(context).enqueue(syncRequest)

Responsive UI Considerations

When presenting document lists, folder navigation, and document action menus in your mobile app, the WOPI operation state should be visible to the user. A document that is currently being synced to the server should show a progress indicator. A document that failed to sync should show an error badge with a retry action. A document that is available offline should show an offline badge so the user knows it is accessible without connectivity.

On tablets (both iOS iPadOS and Android large-screen devices), consider presenting the document list and the Office editing session in a split-view layout using Apple’s UISplitViewController or Android’s SlidingPaneLayout. This is particularly useful in CSPP Plus mobile document editing scenarios where users frequently switch between documents and navigate folder hierarchies.

Enterprise Deployment Considerations

For enterprise deployments, your mobile WOPI application will typically be distributed through managed app stores (Apple Business Manager or Android Enterprise) rather than consumer channels. This affects several aspects of your implementation:

App configuration via MDM: Support AppConfig (iOS) and Android Enterprise managed configurations to allow IT administrators to configure your WOPI host URL, authentication settings, and offline cache limits without requiring user input.
Data loss prevention policies: Ensure your app declares the appropriate managed app capabilities on both platforms to participate in MDM-enforced data loss prevention policies — for example, preventing users from sharing document content to unmanaged applications.
Conditional access compatibility: Test your authentication flow against Microsoft Entra ID conditional access policies, including device compliance requirements and app protection policies. MSAL handles most of this automatically, but integration testing in an MDM-managed environment is essential before enterprise rollout.

Cloud document editing security compliance in enterprise mobile contexts requires that you treat device trustworthiness as a variable — an unmanaged personal device presents a different risk profile than a corporate-issued device enrolled in an MDM solution. Use Entra ID’s device compliance signals, surfaced through conditional access, to gate access to sensitive document operations.

Getting Started with Your Mobile WOPI Integration

The mobile WOPI surface requires a different mindset to web-based WOPI implementation, but the effort is well-justified. Enterprise users’ expectations for mobile document access have been set by consumer applications, and meeting those expectations within a secure, managed WOPI deployment is achievable with the right architecture.

The key milestones for a production mobile WOPI implementation are:

Implement WOPI discovery entries for mobileView and mobileEdit actions.
Build the platform-specific launch flows (URL schemes on iOS, Intents on Android) with return-to-app handling.
Integrate MSAL for mobile authentication and handle token expiry and refresh.
Implement an offline document cache with sync conflict resolution.
Optimise chunk sizes and transfer patterns for mobile network conditions.
Test against enterprise MDM and conditional access configurations.

McKenna Consultants has implemented WOPI integrations across web, desktop, and mobile surfaces for ISVs and enterprise organisations in the UK and internationally. Our experience spans the full WOPI protocol — from foundational CheckFileInfo implementation through to CSPP Plus mobile document editing, coauthoring, geo-fencing, and zero trust security architecture. If you are planning a mobile extension to an existing WOPI integration, or building mobile document editing capability from scratch, contact our team to discuss your requirements and timeline.