Skip to main content

ShipBook SDK for iOS 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.

Requirements​

ShipBook works with Swift 5+, Objective-C and from iOS 12.

Installation​

ShipBookSDK is available through Swift Package Manager.

In Xcode, select File > Add Package Dependencies and enter https://github.com/ShipBook/ShipBookSDK-iOS.git.

Integrating ShipBook into your code​

In your AppDelegate file, add the following:

  import ShipBookSDK

Then, add the following to application(_:didFinishLaunchingWithOptions:):

ShipBook.start(appId:"YOUR_APP_ID", appKey:"YOUR_APP_KEY")

To have a log on each class you need to create a logger.
For Example, in MainViewController:

import ShipBookSDK

fileprivate let log = ShipBook.getLogger(MainViewController.self)

The 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

If you’d like to add a tag that isn't the name of the class you're using then you can add a custom tag:

import ShipBookSDK

fileprivate let log = ShipBook.getLogger("CUSTOM_TAG")

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(enable: 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(userId: "USER_ID",
                      userName: "USER_NAME",
                      fullName: "USER NAME",
                      email: "USER_EMAIL",
                      phoneNumber: "USER_PHONE_NUMBER",
                      additionalInfo: "STRING DICTIONARY OF KEY VALUE")

The only required parameter is userId.

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(name: "SCREEN_NAME")

The best practice is to add this code to viewWillAppear in the view controller.

Flush​

Flush all logs on the device and send them now to the server.

ShipBook.flush()

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 ShipBookSDK

class AnalyticsAppender: BaseAppender {
    var name: String

    required init(name: String, config: Config?) {
        self.name = name
    }

    func update(config: Config?) {}

    func push(log: BaseLog) {
        if let message = log as? Message {
            // Send to your analytics service
        }
    }

    func flush() {}
    func saveCrash(exception: Exception) {}
}

// Register before start
ShipBook.registerAppender(type: "AnalyticsAppender", appenderClass: AnalyticsAppender.self)

ShipBook.start(appId: "YOUR_APP_ID", appKey: "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.

Additional Information​

Automatically Importing ShipBookSDK​

If you don’t want to manually add import ShipBookSDK to each source file, you may insert the following code to the AppDelegate file:

import ShipBookSDK
public typealias ShipBook = ShipBookSDK.ShipBook

Static Function Alternative to getLogger​

You may use a static function in place of getLogger. This is not recommended and the caveats are listed below. When a static function activates the logger, the tag will become the filename. The usage of the log:

The 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

As mentioned, working with this static logger isn't ideal:

  • Performance is slower, especially in cases where the log is closed
  • The log’s information is less detailed. Ideally, you should create a logger for each class.
  • The Log name can have a name collision with a local Log class.

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.

When creating the wrapper on the logs, you will need to implement all the parameters of each log.

For example a wrapper for log.e():

func e(_ msg:String,
       tag:String? = nil,
       function: String = #function,
       file: String = #file,
       line: Int = #line) {
  log.e(msg: msg, tag: tag, function: function,file: file,line: line)
}

You can also implement the function that is receiving all the messages: message():

func e(_ msg:String,
       tag:String? = nil,
       function: String = #function,
       file: String = #file,
       line: Int = #line) {
  log.message(msg: msg, severity: .Error, tag: tag, function: function,file: file,line: line)
}

The severity is an enum:

enum Severity : Int {
  case Off = 0
  case Error
  case Warning
  case Info
  case Debug
  case Verbose
}

Upload the dSYM file​

Shipbook needs the dSYM file for the application to produce human-readable stack traces of the crash.

  1. In Xcode, select your project from the Project Navigator.
  2. Click on the application target.
  3. Select the Build Phase tab in the Settings editor.
  4. Click the + icon in the upper left corner of the main panel.
  5. Select New Run Script Phase from the dropdown.
  6. In the script box, add the following lines: Don't forget to adjust appId and symbolsKey
appId="<YOUR_APP_ID>"
symbolsKey="<YOUR_SYMBOLS_KEY>"

echo $BUILT_PRODUCTS_DIR
echo UPLOADING...

buildProd=$BUILT_PRODUCTS_DIR
prodName=$PRODUCT_NAME
filePath=$buildProd'/'$prodName'.app.dSYM'
buildNumber=$CURRENT_PROJECT_VERSION
marketingVersion=$MARKETING_VERSION

curl -X POST -H "Authorization: Bearer $symbolsKey" -F "data=@$filePath/Contents/Resources/DWARF/$PRODUCT_NAME" \
"https://api.shipbook.io/v1/apps/$appId/upload/dsym?version=$marketingVersion&build=$buildNumber"
  1. Select for install builds only

3rd Party Integrations​

Firebase Crashlytics​

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

SwiftLog​

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

CocoaLumberjack​

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

SwiftBeaver​

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