MiLibrisReaderSDK is the new miLibris reading SDK (previously called MLPDFReaderSDK). It includes the MLFoundation library which allows unpacking miLibris contents.
Please only open an issue if it concerns the usage of the reader SDK. For any other issue regarding the miLibris platform or API, contact miLibris support.
MiLibrisReaderSDK requires iOS 11 or later, Xcode 13 or later. The SDK is provided as a dynamic XCFramework.
Every app using the SDK must be configured with a licence key provided by miLibris. A licence key cannot be used in more than one application.
An example of an Xcode project with Swift Package Manager integration is available in this repository. To use it:
Requires CocoaPods >= 1.9
pod 'MiLibrisReaderSDK', '~> 1.0'
pod installAn example of an Xcode project with CocoaPods integration is available in this repository. To use it:
pod installRequires Carthage >= 0.38
binary "https://raw.githubusercontent.com/miLibris/ios-milibris-reader-sdk/main/MiLibrisReaderSDK.json" ~> 1.0
carthage update --use-xcframeworksAn example of an Xcode project with Carthage integration is available in this repository. To use it:
carthage update --use-xcframeworksAn example of an Xcode project with manual integration is available in this repository. To use it:
If using Swift Package Manager:
ios-milibris-reader-sdk packageIf using CocoaPods:
pod 'MiLibrisReaderSDK', '~> 1.0'
pod update MiLibrisReaderSDKIf using Carthage:
binary "https://raw.githubusercontent.com/miLibris/ios-milibris-reader-sdk/main/MiLibrisReaderSDK.json" ~> 1.0
carthage update --use-xcframeworksFirst remove the previous SDK from your project, depending on your installation method:
pod 'MLPDFReaderSDK', then run pod installMLPDFReaderSDK, then run carthage update, then remove references to the framework in your Xcode projectFollow the instructions in the previous sections to install the new SDK.
In your Swift code, replace import MLPDFReaderSDK with import MiLibrisReaderSDK.
Follow the instructions in the next sections to migrate your code to use the new SDK.
⚠️ The SDK is written in Swift and is not usable from Objective-C files.
The sample projects contain working examples of the following steps.
In order to read content with the SDK, your application will likely implement the following steps:
A complete archive can be unpacked with the MLArchive class. This can be done as a post-download step:
import MiLibrisReaderSDK
do {
// archiveURL: the file URL to the .complete file that was downloaded from the miLibris platform
// releaseURL: a file URL to an available directory where the content of the archive will be extracted
try MLArchive.extract(archiveURL, inDirectory: releaseURL)
} catch {
// something went wrong: maybe there is no archive at archiveURL, maybe the releaseURL directory cannot be written...
print("Error when unpacking content: \(error)")
}
Once an archive has been downloaded and extracted, it can be opened with a few lines of code:
import MiLibrisReaderSDK
class MyViewController: UIViewController {
func openReader() {
// Instantiate the reader
let reader = Reader(releasePath: releasePath, articlesLanguageCode: .frFR)
// Present it from a view controller of your app
reader.presentReaderViewController(from: self)
}
}
The reader is configured to display a tutorial the first time that it is opened on a new device. You can disable it you want:
import MiLibrisReaderSDK
class MyViewController: UIViewController, ReaderDelegate {
func openReader() {
// [...]
// Set this before presenting the reader
reader.readerTutorialProvider = nil
// [...]
}
}
For testing purposes or if you have a feature that resets tutorials in your app, you can add:
import MiLibrisReaderSDK
func resetTutorials() {
MiLibrisReaderTutorialProvider().resetTutorial()
}
}
If you are already displaying the cover page of the issue to open in your UI, you can provide the image view to the reader in order to have nice transitions when opening or closing the reader. To do so, you must implement the reader delegate and return your image view:
import MiLibrisReaderSDK
class MyViewController: UIViewController, ReaderDelegate {
func openReader() {
// [...]
// Set this before presenting the reader
reader.delegate = self
// [...]
}
// MARK: ReaderDelegate
var imageViewForReaderPresentation: UIImageView? {
// Provide an image view that is displaying the cover of the issue.
// It will be used for open and close transitions.
// If you return nil, a default cover transition will be used.
return coverImageView
}
}
When users close the reader and later open the same issue again, they might expect the reader to open at the last page that they consulted. You can implement this feature in two steps:
import MiLibrisReaderSDK
class MyViewController: UIViewController, ReaderDelegate {
private var lastSelectedPage: Int?
func openReader() {
// [...]
// Set this before presenting the reader
reader.delegate = self
reader.initialPageNumber = lastSelectedPage ?? 1
// [...]
}
// MARK: ReaderDelegate
func readerViewController(_ readerViewController: UIViewController, didMoveToPageNumbers pageNumbers: [Int]) {
print("Did move to page numbers \(pageNumbers)")
lastSelectedPage = pageNumbers.first
}
func didDismissReaderViewController(_ readerViewController: UIViewController) {
// Here you can persist lastSelectedPage for later use
}
}
Many components of the reader UI can be customized to match your brand. The SDK provides a method to quickly apply your brand color and logo:
import MiLibrisReaderSDK
class MyViewController: UIViewController {
func openReader() {
// [...]
// Set this before presenting the reader
reader.config.applyBranding(
mainTintColor: .red,
mainTintColorComplement: .white,
logoImage: UIImage(named: "myLogo"),
logoBackgroundColor: .white
)
// [...]
}
}
You can also (or in addition to the previous method) individually customize every element of the UI. To do so, mutate the reader.config struct before opening the reader. The complete reference can be found in Docs/config.md. For example:
import MiLibrisReaderSDK
class MyViewController: UIViewController {
func openReader() {
// [...]
// Set this before presenting the reader
reader.config.colors.background = .red
reader.config.articleReader.features.isTextToSpeechEnabled = false
// Apply the same changes to all navigation bars
reader.config.navigationBar.applyMyConfig()
reader.config.summary.navigationBar.applyMyConfig()
reader.config.articleReader.navigationBar.applyMyConfig()
reader.config.articleReader.summary.navigationBar.applyMyConfig()
// [...]
}
}
extension NavigationBarConfig {
mutating func applyMyConfig() {
colors.titleText = .blue
fonts.title = .custom(UIFont(name: "myfont", size: 12))
}
}
If your application already supports dark mode, it will also be available in the reader.
If not, you can still make it available in the reader with a few steps:
overrideUserInterfaceStyle = .light // disable dark mode
viewControllerToPresent.overrideUserInterfaceStyle = .light // disable dark mode
present(viewControllerToPresent, animated: true)
You can register a class as a delegate to the reader. This will allow you to receive various events from the reader, that you can then send to your analytics solution:
import MiLibrisReaderSDK
class MyViewController: UIViewController, ReaderDelegate {
func openReader() {
// [...]
// Set this before presenting the reader
reader.delegate = self
// [...]
}
// MARK: ReaderDelegate
func readerViewController(_ readerViewController: UIViewController, didMoveToPageNumbers pageNumbers: [Int]) {
print("Did move to page numbers \(pageNumbers)")
}
func articleReaderViewController(
_ articleReaderViewController: UIViewController, didOpenArticle article: ArticlePreview
) {
print("Did open article \(article.articleId): \(article.title)")
}
}
See the definition of ReaderDelegate for a complete list of events.
You can provide a sharing provider to the reader in order to add a "Share" button on articles. Your sharing provider is responsible for providing the content to share for an article.
import MiLibrisReaderSDK
class MyViewController: UIViewController {
func openReader() {
// [...]
// Set this before presenting the reader
reader.sharingProvider = MyWebsiteSharingProvider()
// [...]
}
}
class MyWebsiteSharingProvider: SharingProvider {
func articleSharingContent(article: ArticlePreview) throws -> SharingContent {
// You could use the miLibris article identifier or the article title to match with articles on your website
let url = URL(string: "https://www.mywebsite.com/article/\(article.articleId)")!
return SharingContent(url: url, title: article.title)
}
}
The SDK also provides the implementation for sharing an article with a miLibris web kiosk.
⚠️ Before implementing this protocol, contact miLibris support to make sure that the sharing feature is supported by your web kiosk.
import MiLibrisReaderSDK
class MyViewController: UIViewController {
func openReader() {
// [...]
// Set this before presenting the reader
let issueId = "milibris-issue-id" // The MID of the issue being opened, as returned by the miLibris API
reader.sharingProvider = MyMiLibrisSharingProvider(issueId: issueId)
// [...]
}
}
class MyMiLibrisSharingProvider: MiLibrisWebKioskSharingProvider {
var kioskBaseURL: URL {
return URL(string: "https://www.mywebkiosk.com")!
}
let issueId: String
init(issueId: String) {
self.issueId = issueId
}
}
You can provide a bookmark provider to the reader in order to add a "Bookmark" button on articles. Your bookmark provider is responsible for managing the on/off state of bookmarks.
The reader does not include a list of bookmarked articles. It should be developed in your app.
import MiLibrisReaderSDK
class MyViewController: UIViewController {
func openReader() {
// [...]
// Set this before presenting the reader
reader.bookmarkProvider = MyBookmarkProvider()
// [...]
}
}
class MyBookmarkProvider: BookmarkProvider {
// In a typical application, this list is persisted somewhere
var bookmarkedArticlesIds = Set<String>()
// MARK: BookmarkProvider
func isArticleBookmarked(_ article: ArticlePreview) -> Bool {
return bookmarkedArticlesIds.contains(article.articleId)
}
func setIsArticleBookmarked(
_ isBookmarked: Bool,
article: ArticlePreview,
from viewController: UIViewController,
actionSource: BookmarkActionSource
) -> Bool {
if isBookmarked {
bookmarkedArticlesIds.insert(article.articleId)
print("Added article to bookmarks: \(article.title)")
} else {
bookmarkedArticlesIds.remove(article.articleId)
print("Removed article from bookmarks: \(article.title)")
}
// Return true if the operation was successful, false otherwise.
return true
}
}
By default, the reader will print warnings and errors to the Xcode console. You can change the log level if you want to:
import MiLibrisReaderSDK
Logger.minLogLevel = .debug
You can also implement logging yourself, for example to plug the reader messages to your own logging solution:
import MiLibrisReaderSDK
Logger.shared = MyLogger.self
class MyLogger: LoggerType {
static func log(_ message: String, file: String, function: String, line: Int, level: LogLevel) {
print("[MYLOGGER] \(level.emoji) \(message)")
}
}
If you want to present your own article reader instead of the one provided by the SDK, you can do so using the reader delegate:
import MiLibrisReaderSDK
class MyViewController: UIViewController, ReaderDelegate {
func openReader() {
// [...]
// Set this before presenting the reader
reader.delegate = self
// [...]
}
// MARK: ReaderDelegate
func readerViewController(
_ readerViewController: UIViewController & ArticleReaderDelegate,
shouldDisplayArticle article: ArticlePreview
) -> Bool {
let myArticleViewController = MyArticleViewController()
myArticleViewController.article = article
myArticleViewController.delegate = readerViewController
readerViewController.present(myArticleViewController, animated: true)
return false
}
}
class MyArticleViewController: UIViewController {
var article: ArticlePreview?
weak var delegate: ArticleReaderDelegate?
}
If you want to allow users to print a single page or a double page of your publication, you can do so by updating the config:
import MiLibrisReaderSDK
class MyViewController: UIViewController {
func openReader() {
// [...]
// Set this before presenting the reader
reader.config.features.printEnabled = true
// [...]
}
}
If you want to allow the text-to-speech audio to continue while the app is in the background, you need to enable the audio background mode in your iOS project.
If you want to add a search interface for articles in the summary, you need to configure the miLibris API access with the same keys you use in your app:
import MiLibrisReaderSDK
class MyViewController: UIViewController, ReaderDelegate {
func openReader() {
// Instantiate the reader with the miLibris search API
let searchProvider = MiLibrisSearchProvider(
pointOfSaleMid: "<your_point_of_sale_mid>",
basicAuth: "<your_basic_auth>",
issueMid: "<issue_mid_being_opened>"
)
let reader = Reader(
releasePath: releasePath, articlesLanguageCode: .frFR, searchProvider: searchProvider
)
// [...]
}
}
By default some images in articles are cropped to better fit the templates. If you want to disable all image cropping you can add the following configuration:
import MiLibrisReaderSDK
class MyViewController: UIViewController {
func openReader() {
// [...]
// Set this before presenting the reader
reader.config.articleReader.features.forceLayout = .default
reader.config.articleReader.features.isImageCropEnabled = false
// [...]
}
}
You can quickly customize the article reader fonts to match your brand:
import MiLibrisReaderSDK
class MyViewController: UIViewController {
func openReader() {
// [...]
// Set this before presenting the reader
try reader.config.articleReader.articleReader.applyPrimaryFont(
regularFontName: "PlayfairDisplay-Regular",
blackFontName: "PlayfairDisplay-Black",
boldFontName: "PlayfairDisplay-Bold"
)
try reader.config.articleReader.applySecondaryFont(
regularFontName: "ComicNeue-Regular",
mediumFontName: "ComicNeue-Light",
semiBoldFontName: "ComicNeue-Bold"
)
try reader.config.articleReader.applyTertiaryFont(
regularFontName: "RobotoCondensed-Regular",
blackFontName: "RobotoCondensed-Black",
boldFontName: "RobotoCondensed-ExtraBold",
italicFontName: "RobotoCondensed-Italic"
)
// [...]
}
}
See the methods documentation in code for more info. In addition to this, you can also customize each UI component individually with the corresponding config properties.
| link |
| Stars: 1 |
| Last commit: 2 weeks ago |
Features
Improvements
Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics