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)

Linking to Your Backend​

To see this app's sessions and your Node.js backend's requests in one timeline, add the header from getSessionHeaders() to the requests your app sends to your backend. See Cross-App Session Linking.

Custom Appenders​

You can create custom appenders to route logs to additional destinations such as analytics services, local databases, or test harnesses. Register your custom appender before calling start().

import io.shipbook.shipbooksdk.Appenders.BaseAppender
import io.shipbook.shipbooksdk.Appenders.Config
import io.shipbook.shipbooksdk.Models.BaseLog
import io.shipbook.shipbooksdk.Models.Message

class AnalyticsAppender(name: String, config: Config?) : BaseAppender(name, config) {
    override fun update(config: Config?) {}

    override fun push(log: BaseLog) {
        if (log is Message) {
            // Send to your analytics service
        }
    }
}

// Register before start
ShipBook.registerAppender("AnalyticsAppender", AnalyticsAppender::class.java)

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

Once registered, your custom appender can be configured through the Shipbook console by its type name, and assigned to loggers with the desired severity level.

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.

3rd Party Integrations​

Firebase Crashlytics​

For integration with Firebase Crashlytics go to the following link: Firebase Crashlytics Integration

Timber​

For integration with Timber go to the following link: Timber Integration