Android - Full Integration

ShipBook SDK for Android#

About ShipBook#

ShipBook gives you the power to remotely gather, search and analyze your user logs and exceptions in the cloud, on a per-user & session basis.

The SDK is written in Kotlin, but works perfectly well in Java. The following examples in this documentation are written in Java.


Requirements#

ShipBook works with min SDK version 19 (KITKAT)


Installation#

ShipBookSDK is available through mavenCentral.

To install it, simply add the following line to the dependencies in your build.gradle: implementation 'io.shipbook:shipbooksdk:1.+'


Integrating Shipbook into your code#

Add the following to your application file:

import io.shipbook.shipbooksdk.ShipBook

And add the following to onCreate():

ShipBook.start(this,"YOUR_APP_ID", "YOUR_APP_KEY")

Quick Implementation#

You can call all the usual Android logs, the only difference is that you should change the import from import android.util.Log to import io.shipbook.shipbooksdk.Log. for example:

import io.shipbook.shipbooksdk.Log
...
Log.e(TAG, "the log message") // Error log
Log.w(TAG, "the log message") // Warning log
Log.i(TAG, "the log message") // Info log
Log.d(TAG, "the log message") // Debug log
Log.v(TAG, "the log message") // Verbose log

Simpler Implementation#

ShipBook employs a simpler system for logs because the static logger causes the following issues:

  • Implementation is slower, especially in cases where the log is closed.
  • You need to add the word TAG for each log.

To have a log on each class you will need to create a logger:

import io.shipbook.shipbooksdk.ShipBook
...
// in the class
val log = ShipBook.getLogger("TAG")

The TAG should be named for the specific tag of your choice. The convention is to use the class name.

Usage of the log:

log.e("the log message") // Error log
log.w("the log message") // Warning log
log.i("the log message") // Info log
log.d("the log message") // Debug log
log.v("the log message") // Verbose log

Enable Shipbook debug logging#

If your logs weren't uploaded to Shipbook, or you're experiencing some other issue with Shipbook, you can enable Shipbook debug logging to track down the problem.

ShipBook.enableInnerLog(true)

Linking Shipbook to a User’s Information#

The SDK allows the option to associate each session with specific user information.

Register user:#

The best practice is to set registerUser before ShipBook.start. It will also work after this point however, it will require an additional api request.

ShipBook.registerUser("USER_ID",
"USER_NAME",
"FULL_NAME",
"USER_EMAIL",
"USER_PHONE_NUMBER",
"additional info")

The only parameter that must be entered is the userId. You may set all the other parameters to null.

Logout#

To logout the user, add the following code to your app’s logout function.

ShipBook.logout()

Screen#

To log the user’s screen information, add the following code

ShipBook.screen("SCREEN_NAME")

Using Wrappers with ShipBook#

If you are already using some kind of a logging system, you may want to write wrappers to send the logs to both systems.

You will need to add the wrapper class name to addWrapperClass

ShipBook.addWrapperClass(LogWrapper::class.java.name)

Integrating Shipbook with Crashlytics#

To integrate Shipbook with crashlytics just implement the completion callback of ShipBook.start as following:

ShipBook.start(this,"YOUR_APP_ID", "YOUR_APP_KEY", { sessionUrl ->
FirebaseCrashlytics.getInstance().setCustomKey("shipbookSession", sessionUrl)
})

Now you'll have in crashlytics a link to the logs of the specific session. The link is in the Keys tab of the a specific crash under the key ShipbookSession.


Integrating with Timber#

Just add the following code and it will work out of the box with timber.

ShipBook.addWrapperClass(Timber::class.java.name)
Timber.plant(object : Timber.Tree() {
override fun log(priority: Int, tag: String?, message: String, t: Throwable?) {
Log.message(tag, message, priority, t)
}
init {
ShipBook.addWrapperClass(this.javaClass.name)
}
})

Obfuscation with Shipbook#

In the case that the build is obfuscated to let all the functionality in Shipbook to work add the following lines to your Proguard

-keepattributes SourceFile,LineNumberTable # Keep file names and line numbers.