Skip to main content

ShipBook SDK for Android Log - Full Integration

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 Kotlin and 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)

Ignore Views

To ignore views from action events so that it won't log private information of these views, add the following code:

ShipBook.ignoreViews(R.id.view1, R.id.view2)

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.