Deeplink Manager
Relevant source files
The following files were used as context for generating this wiki page:
The DeeplinkManager is a centralized component responsible for handling incoming URLs and navigating the user to specific content or sections within the put.io iOS application. It supports both custom URL schemes and Universal Links (HTTP/HTTPS) to provide seamless transitions from external sources—such as web browsers or other apps—directly into specific files, downloads, or settings pages.
The manager operates as a singleton, ensuring a unified entry point for all deep-linking logic. It integrates closely with the application's root navigation structure, specifically the MainTabBarController, to switch tabs and push or present view controllers as needed.
Sources: Putio/Common/Managers/DeeplinkManager.swift:8-10, Putio/AppDelegate.swift:105-117
Architecture and Integration
The Deep Link Manager is initialized and configured during the application lifecycle. It relies on a reference to the MainTabBarController to perform UI navigation. The AppDelegate acts as the primary receiver of deep link events from the iOS system and delegates them to the manager.
System Entry Points
The manager handles two main types of system callbacks:
- Custom URL Schemes: Handled via
application(_:open:sourceApplication:annotation:). - Universal Links: Handled via
application(_:continue:restorationHandler:)when the activity type isNSUserActivityTypeBrowsingWeb.
Sources: Putio/AppDelegate.swift:105-117
Navigation Logic Flow
The following diagram illustrates how an incoming URL is processed and routed to the correct UI component:
URL Handling and Routing
The handleURL(url:) function is the main entry point. It categorizes URLs based on their path prefixes and invokes specialized private handlers.
Supported Routes
| Path Pattern | Target Action | Components Involved |
|---|---|---|
/files/{id} | Navigates to the Files tab and presents a specific file. | PutioSDK, FilesViewController |
/downloads/{id} | Navigates to Downloads and opens a locally saved file. | PutioRealm, DownloadsViewController |
/history | Switches the UI to the History tab. | MainTabBarController |
/settings / /account | Switches the UI to the Account/Settings tab. | MainTabBarController |
/link | Switches to Account tab and pushes the Link Account view. | LinkAccountViewController |
Sources: Putio/Common/Managers/DeeplinkManager.swift:61-82, Putio/Common/Managers/DeeplinkManager.swift:106-120
ID Extraction
The manager uses regular expressions to extract numeric identifiers from URL paths. For example, the pattern /files/(.*) is used to capture the ID following the prefix.
private func extractIDFromPath(pattern: String, path: String) -> Int? {
guard let regex = try? NSRegularExpression(pattern: pattern, options: .caseInsensitive) else {
return nil
}
let matches = regex.matches(in: path, options: [], range: NSRange(location: 0, length: path.utf16.count))
guard let match = matches.first,
let swiftRange = Range(match.range(at: 1), in: path) else { return nil }
return Int(path[swiftRange])
}
Sources: Putio/Common/Managers/DeeplinkManager.swift:20-30
Content Presentation Logic
Deep links often require presenting content over the current UI state. The manager includes logic to handle dismissals of existing modal presentations before showing new content to avoid view controller hierarchy conflicts.
File and Download Presentation
- Remote Files: When a
/files/{id}link is received, the manager fetches the file metadata via thePutioSDK. Once retrieved, it instructs theFilesViewControllerto callpresentFile(file). - Downloaded Files: For
/downloads/{id}, the manager queries the localPutioRealmdatabase for aDownloadobject using the extracted ID as a primary key. If found, it usesDownloadsViewControllerto present the file.
Sources: Putio/Common/Managers/DeeplinkManager.swift:44-60, Putio/Common/Managers/DeeplinkManager.swift:84-104
Sequence: Handling a File Deeplink
Data Persistence Integration
The DeeplinkManager relies on the PutioRealm helper to access local download records. This is critical for the /downloads route, where the file must exist in the local database to be presented.
- Realm Context: When opening the database, the manager uses the context string
"DeeplinkManager.openDownloadedFile"for logging and diagnostics. - Primary Key: The ID extracted from the URL path is mapped directly to the
Downloadobject's primary keyid.
Sources: Putio/Common/Helpers/Realm.swift:45-53, Putio/Features/Downloads/DownloadModel.swift:49-51, Putio/Common/Managers/DeeplinkManager.swift:45-47
Conclusion
The DeeplinkManager provides a robust routing system that translates external URL requests into internal application states. By centralizing ID extraction, API coordination, and UI navigation logic, it ensures that deep links are handled consistently whether the app is being launched for the first time or resumed from the background.