MiLibrisReaderSDK is the new miLibris reading SDK (previously called MLPDFReaderSDK). It includes the MLFoundation library which allows unpacking miLibris contents.
- Prerequisites
- Implementation
- Customization
- Sample project
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.
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 {
def miLibrisReader = "1.17.4"
api("com.milibris:one-reader:$miLibrisReader") { //If you ever have conflict with the version used in our library add this line
exclude group: "androidx.lifecycle"
}
api "com.milibris:milibris-reader:$miLibrisReader"
}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> By default, the SDK will communicate with miLibris production environment. To change the target, you can override the base URL in your manifest as below
<application....>
<meta-data android:name="com.milibris.api.v4.baseUrl" android:value="TARGET_BASE_URL" />
</application> 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
Refer to the miLibris API documentation to obtain a ticket for the issue you want to download, in the x-ml-pdf format.
You can then download the complete archive with the following URL: https://content.milibris.com/access/%@/download.complete (replace %@ with the mid of your ticket).
The JWT token returned by the API can be ignored.
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()
}
} 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(
context = this,
readerSettings = ReaderSettings(),
productRepository = productRepo,
readerListener = ORListener(dataSource = productRepo, "issueMid", this),
searchProvider = CustomSearchProvider(), // @see Search publication optional feature
sharedElementImageUrl = coverImageURL,
sharedElementRatio = coverRatio
)
)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
isSummaryEnabled = true
isPrintEnabled = true
}To allow users to print currently displayed pages we enable the ReaderSettings isPrintEnabled option.
This feature is disabled by default.
To enable searching in a publication, we are providing a provider:
OneReaderActivity.newIntent(
searchProvider = CustomSearchProvider(),
)This object implements the SearchProvider interface:
interface SearchProvider {
fun search(searchText: String, completion: (Result<SearchResponse>) -> Unit)
}The search result can be:
- a list of matching results
SearchResponseItem - an empty list to present a "no result" screen
- a failure to present a "technical error" screen
Each SearchResponseItem must describe a SearchResponseItemArticle and a list of highlights String.
For now:
- only the first
highlightis presented. - the
SearchResponsesuggestionsare not used.
By default, without any SearchProvider provided, this feature is disabled.
The reader can present a page as an interstitial advert when an issue is opened.
To enable this feature, the reader must be provided a PageAdRepository implementation.
The miLibris reader includes a default one that allows the interstitial to be shown the first time an issue is opened:
OneReaderActivity.newIntent(
productRepository = productRepo,
pageAdRepository = MiLibrisPageAdRepository(productRepository),
)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()
}
}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) {}
// ....
}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
}
}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()
}
}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
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
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 />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.
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