URL Scheme
About URL Scheme
This document describes custom URL scheme protocol supported by a family of iOS apps built on Offline Pages platform, including Offline Pages Pro, Offline Kiosk, Offline Forms, as well as custom enterprise apps. URL scheme protocol lets website owners and third-party application developers launch an app and perform high-level tasks, such as adding a page to download queue or displaying a previously downloaded page.
If you are unfamiliar with URL schemes, please read Apple documentation first.
All apps built on Offline Pages platform support custom URL scheme. However, they use different scheme identifiers, and the level of supported functionality varies from app to app. Refer to the command reference at the end of the document to see the level of support for each URL command.
Example
The following example URL can be used to launch Offline Pages app and add fictional URL http://www.myblog.com/ to the download queue using custom title “My blog”.
Example URL:
op-action://add?title=My+blog&url=http://www.myblog.com/Example HTML:
<a href="op-action://add?title=My+blog&url=http://www.myblog.com/">
Read my blog offline in Offline Pages app</a>Example Objective-C:
NSString *httpURL = [NSString stringWithString:@"http://www.myblog.com/"];
NSString *title= [NSString stringWithString:@"My blog"];
NSString *encodedTitle = [title stringByAddingPercentEscapesUsingEncoding:NSASCIIStringEncoding];
NSString *offlineURL = [NSString stringWithFormat:@"op-action://add?title=%@&url=%@", encodedTitle, httpURL];
NSURL *url = [NSURL URLWithString:offlineURL];
[[UIApplication sharedApplication] openURL:url];
URL structure
The following is overall structure of Offline Pages URL:
scheme_identifier://command_identifier?parametersCommand identifier and parameters are optional and can be omitted. When command identifier is not provided, the corresponding app launches, but it does not perform any action. For example, the following URL launches Offline Kiosk app without any further action:
op-action-kiosk://URL scheme identifiers
Scheme identifiers are app dependent. Each app built on Offline Pages platform only responds its own scheme identifier. The following table lists scheme identifiers supported by public Offline Pages apps:
| App Title | Scheme Identifier |
|---|---|
| Offline Pages, Offline Pages Pro | op-action |
| Offline Kiosk | op-action-kiosk |
| Offline Forms | op-action-forms |
URL commands
The following list describes URL commands that are currently supported by apps built on Offline Pages platform.
add command
Use add command to add URLs to app’s index of saved pages and (optionally) to the download queue. Only Offline Pages and Offline Pages Pro apps support add command. Note: Offline Kiosk and Offline Forms apps support deploy command instead which lets you import pre-formatted package and kiosk files.
| Parameter | Description |
|---|---|
| url | URL of the page to add. It can be one of the following protocols: file, http, and https. Other protocols are not allowed. This parameter is required. |
| force | When set to “1”, the app adds the page to the index even if there is already a page with the same URL. Otherwise, the app will first search for the URL in the index and only add the new page if there are no existing pages with same URL. (Optional.) |
| quiet | When set to “1”, the app does not open a new tab for the page. Otherwise, the app opens a new tab for the page. (Optional.) |
| delay | When set to “1”, the app only adds the page to the index, but not to the download queue. The user has to start download manually. If the parameter is not provided or set to value other than “1”, the app also adds the page to download queue. (Optional.) |
| title | URL-encoded title that is used for the page in the index. If not provided, the app extracts or infers the title from page content. (Optional.) |
| f | URL-encoded path to a destination folder for a new page. If not provided, the app will add the page to Inbox folder. (Optional.) |
| tags | Comma-separated list of tags for a new page. If any tag already contains comma characters, they can be escaped with backslashes. (Optional.) |
| r | When set to "1", the app marks a new page as read. (Optional.) |
| refresh | The approximate frequency of automatic refresh for a new page. It can be one of the following values: “hourly”, “daily”, “weekly”. When not provided, the app disables automatic refresh for the page. (Optional.) |
| refreshMode | Use this parameter to customize refresh strategy for a new page. The only allowed value is “thorough”. When not provided, the app uses default (quick) strategy for page refresh. (Optional.) |
| media | When set to “1”, the app enables download of embedded audio and video for a new page. (Optional.) |
| nojs | When set to “1”, the app disables JavaScript parsing and strips all JavaScript code from downloaded pages. Otherwise, JavaScript code is parsed and post-processed normally. (Optional.) |
| auto | When set to “1", the app uses globally shared site-specific rules for a new page. You can read more about site-specific rules in Offline Pages rules format documentation. (Optional.) |
| crawl | When provided, the app enables link crawler for a new page. The allowed values are “intelligent”, “firstLevel”, “website” and “custom”. Otherwise, the app disables link crawler. (Optional.) |
| maxPages | Use this parameter to limit link crawler to a specified number of pages. The valid range of values is 10-50000. This parameter is required when “crawl” parameter is set to “custom”, but is ignored otherwise. |
| numLevels | Use this parameter to limit link crawler to a specified link depth. The valid depth range is 1-5. This parameter is required when “crawl” parameter is set to “custom”, but is ignored otherwise. |
| externalLevels | Use this parameter together with “offsite” set to “1” to limit external pages to a specified link depth. The valid depth range is 1-5. (Optional.) |
| parents | When set to “1", the app’s link crawler finds and downloads pages that are located on the same host as the initial page but outside of its parent directory. Use this parameter together with “crawl” set to “custom”. (Optional.) |
| subdomains | When set to “1", the app’s link crawler finds and downloads pages from same second-level domain as the initial page, but on other third-level domains. Use this parameter together with “crawl” set to “custom”. (Optional.) |
| offsite | When set to “1", the app’s link crawler finds and downloads pages from unrelated domains and other websites. (Optional.) |
| ua | The user-agent that the app uses to download pages. The only allowed values are “Mac”, “iPhone”, and “iPad”. When not provided, the app chooses user-agent string that corresponds to the device it’s running on. (Optional.) |
Example:
op-action://add?title=My+blog&url=http://www.myblog.com/&ua=iPad&crawl=custom&maxPages=100&numLevels=1deploy command
Use deploy command to import a pre-formatted package or kiosk file into the app’s catalog. You can read more about package file format in package format documentation. Deploy command is supported by all apps.
| Parameter | Description |
|---|---|
| url | URL of a well-formatted XML file in Offline Pages package format. The app adds all pages contained in the package to the index and, when appropriate, to the download queue. The allowed URL protocols are file, http and https. Other protocols or file formats are not supported. (Required.) |
| delay | When set to “1”, the app adds pages contained in the packages to the index, but not to the download queue. delay parameter is only supported in Offline Pages and Offline Pages Pro apps. (Optional.) |
Example:
op-action://deploy?url=https://codiumlabs.com/offline/package.xmlview command
Use view command to open a page with the specified remote URL in any of supported browsers, including the app’s built-in browser.
| Parameter | Description |
|---|---|
| url | Remote URL of the page to open in browser. (Required.) |
| target | Browser to open the page in. The allowed values are “blank”, “modal”, “default”, “safari”, and “chrome”. “blank” value is only supported in Offline Pages and Offline Pages Pro apps. (Optional.) |
| cached | When set to “1”, the app attempts to open local version of the page instead of remote (original) pages. If local page is not available, the app opens remote (original) page intead. cached parameter is only supported in Offline Pages and Offline Pages Pro apps. (Optional.) |
Example:
op-action://view?url=https://codiumlabs.com/&cached=1&target=blank