MiLibrisReaderSDK
MiLibrisReaderSDK is the new miLibris reading SDK (previously called MLPDFReaderSDK). It includes the MLFoundation library which allows unpacking miLibris contents.
Prerequisites
MiLibrisReaderSDK developed in Kotlin requires Android 5 or higher, and uses glide to load images as external library and other androidX libraries like ViewModel and appCompact.
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.
Setup
The library is available on our maven and can be added to your Android project as follow:
repositories {
google()
mavenCentral()
maven { url 'https://maven-android-sdk.milibris.net/' }
}
dependencies {
api("com.milibris:one-reader:1.0.4") { //If you ever have conflict with the version used in our libary add this line
exclude group: "androidx.lifecycle"
}
api("com.milibris:milibris-reader:1.0.4")
} In order for the SDK to work properly you need to add the licence key provided in your manifest as below
<application....>
<meta-data android:name="com.milibris.pdfreader.licencekey" android:value="YOUR_LICENCE_KEY" />
</application> Implementation
In order to read a content, your application will likely implement the following steps:
- Download a complete archive (with the *.complete extension) from the miLibris
platform. - Unpack the archive using MLFoundation
- Launch Reader to read the unpacked contents
Unpack a complete archive with MLFoundation
A complete archive can be easily unpacked with the MLFoundation library utilities (see
example below, extracting a sample.complete file in Android assets).
private fun unpackArchive() {
val foundationContext: com.milibris.foundation.FoundationContext =
com.milibris.foundation.Foundation.createContext(applicationContext)
try {
val archive: com.milibris.foundation.CompleteArchive =
com.milibris.foundation.CompleteArchive(
foundationContext,
assets.openFd("$pdfName.complete").createInputStream()
)
archive.unpackTo(File(getExternalFilesDir(null), pdfName))
} catch (e: Throwable) {
e.printStackTrace()
}
} Read unpacked contents
Once unpacked, you can open the content by starting OneReaderActivity:
// Initialize the reader to open the contents val productRepo = XmlPdfReaderDataSource(readerSettings) productRepo.init(applicationContext, contentPath)
startActivity(
OneReaderActivity.newIntent(
this,
ReaderSettings(),
productRepo,
ORListener(dataSource = productRepo, "issueMid", this),
coverImageURL,
coverRatio
)
) Customization
Optional Features
We are providing a ReaderSettings class where you can customize the reader as you please to enable or disable some features.
val readerSettings = ReaderSettings().apply {
isFaceCropEnabled = true
debugBoxes = true
targetPageNumber = targetPage
textToSpeechEnabled = true
shareEnabled = true
enableSummaryImages = true
logo = R.drawable.milibris
} Configure the reader tutorial
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:
val readerSettings = ReaderSettings().apply {
showReaderTutorials = false
} Or this way if you don't want the tutorial to be shown on previews for example
class ORListener(
private val dataSource: XmlPdfReaderDataSource
) : ReaderListener {
override fun canOpenTutorials(): Boolean {
return dataSource.materialParser.isPreview.not()
}
}Event tracking
If you want to track user events on reader you need to implement create your own class that implements The ReaderListener :
class ORListener : ReaderListener {
override fun onCloseButtonClickListener() {}
override fun onIssueRead() {}
override fun onIssuePageRead(pageNumber: Int, isCalledFromArticles: Boolean) {}
override fun onSummaryOpened(isOpenedFromArticles: Boolean) {}
// ....
}Resume reading at the last read page
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:
- Implement the ReaderListener to save the last page consulted by a user
- Open the reader with the last consulted page
private var targetPage: Int = 1
private fun openReader() {
startActivity(
OneReaderActivity.newIntent(
this,
ReaderSettings().apply {
targetPageNumber = targetPage
},
productRepo,
ORListener()
)
)
}
class ORListener : ReaderListener {
override fun onIssuePageRead(pageNumber: Int, isCalledFromArticles: Boolean) {
targetPage = pageNumber
}
}Provide article sharing functionality
You can provide a sharing provider to the reader in order to add a "Share" button on articles. Your will be responsible for providing the URL to share for an article.
- Activate sharing option in ReaderSettting by setting shareURl
- Implement your own sharing login in ReaderListener
- Open the reader with the last consulted page
val readerSetting = ReaderSettings().apply {
shareEnabled = true
}
class ORListener(
private val dataSource: XmlPdfReaderDataSource,
private val context: Context
) : ReaderListener {
override fun onShareClicked(article: IArticle) {
val milibrisArticle = dataSource.getMilibrisArticle(article)
val articleUrl = "${dataSource.readerSettings.shareUrl}/share/article/$issueMid/${milibrisArticle?.mid}"
val intentBuilder = ShareCompat.IntentBuilder(context)
.setType("text/plain")
.setText(articleUrl)
intentBuilder.startChooser()
}
}Customize logo
DisplayMode variants in article reader
While reading articles, user can change the DisplayMode to AUTO, LIGHT, or DARK.
To match this configuration, we can set a logo for each of these options.
val readerSetting = ReaderSettings().apply {
logo = R.drawable.milibris // AUTO
logoLight = R.drawable.milibris_light // LIGHT
logoDark = R.drawable.milibris_dark // DARK
}If logoLight and logoDark are not provided, logo will be used.
The AUTO mode relies on Android built-in configuration based drawable:
├── res
│ ├── drawable
│ │ ├── milibris.xml // Used in AUTO when OS is in light mode
│ │ ├── milibris_light.png
│ │ ├── milibris_dark.png
│ ├── drawable-night
│ │ ├── milibris.xml // Used in AUTO when OS is in dark mode
Override capsule
Logo appearance is defined by the ORLogo style:
<?xml version="1.0" encoding="utf-8"?>
<resources>
<style name="ORLogo">
<item name="android:layout_width">@dimen/or_logo_capsule_width</item> <!-- 100dp -->
<item name="android:layout_height">@dimen/or_logo_capsule_height</item> <!-- 36dp -->
<item name="android:padding">@dimen/half_margin</item> <!-- 8dp -->
<item name="android:background">@drawable/or_logo_capsule_background</item> <!-- background drawable -->
</style>
</resources>where android:background is overriden when DisplayMode changes to use:
@drawable/or_logo_capsule_stroke_color // AUTO
@drawable/or_logo_capsule_stroke_color_light.xml // LIGHT
@drawable/or_logo_capsule_stroke_color_dark.xml // DARKthese are simple corner rounded bordered shapes
Remove the capsule
To completely remove the capsule, you can override this style to remove the padding:
<?xml version="1.0" encoding="utf-8"?>
<resources>
<style name="ORLogo">
<item name="android:layout_width">@dimen/or_logo_capsule_width</item>
<item name="android:layout_height">@dimen/or_logo_capsule_height</item>
<item name="android:padding">0dp</item> <!-- set the padding to zero -->
<item name="android:background">@drawable/or_logo_capsule_background</item>
</style>
</resources>and override the three drawable resources used as background with empty drawables:
<?xml version="1.0" encoding="utf-8"?>
<selector />Apply your branding to the reader UI
Many components of the reader UI can be customized to match your brand, And for you to do that you just need to override the definition os some color and drawable ressources. The complete reference can be found in docs/config.md.
Sample project
A sample project is provided to help you implement the reader integration. It contains an example to unpack a complete archive and to open if with PdfReader class.
If your miLibris content has articles, you can implement your own sharing solution by adding your own code in onShareClicked() just like shown in this sample in the class ORListener