buglife-android: A Java repository from Buglife

Buglife is an awesome bug reporting SDK & web platform for Android apps. Here's how it works:

User takes a screenshot, or stops screen recording
User annotates their screenshot & writes feedback
Bug reports are pushed to your team's email/Jira/Slack/Asana/wherever you track bugs.

You can also find Buglife for iOS here.

	Main Features
👤	Free + no account required
📖	Open source
🏃🏽‍♀️	Fast & lightweight
🎨	Themeable
📩	Automatic caching & retry
🎥	Screen recording
📜	Custom form fields, with pickers & multiline text fields
ℹ️	Advanced logging, with debug / info / warning levels
📎	Custom attachments, including JSON & SQLite support

Installation

If you use targetSdkVersion version 29 or higher, you should add android:requestLegacyExternalStorage="true" into your AndroidManifest.xml.

<manifest ... >
  <!-- This attribute is "false" by default on apps targeting
       Android 10 or higher. -->
  <application android:requestLegacyExternalStorage="true" ... >
    ...
  </application>
</manifest>

Add buglife-android as a dependency to your app's build.gradle.

dependencies {
	implementation 'com.buglife.sdk:buglife-android:1.5.2'
}

Create an Application subclass in your project if you don't already have one. (And don't forget to add it to your app's AndroidManifest.xml.)
Add the following lines to the end of the onCreate() method in your app's Application subclass:
```
Buglife.initWithEmail(this, "you@yourdomain.com");
Buglife.setInvocationMethod(InvocationMethod.SCREENSHOT);
```
Be sure to replace you@yourdomain.com with your own email address; this is where bug reports will be sent to.

Got an account?

If you have a Buglife account already, you should initialize Buglife with your team's API key instead of your email:
```
Buglife.initWithApiKey(this, "YOUR_API_KEY");
Buglife.setInvocationMethod(InvocationMethod.SCREENSHOT);
```
Build & run on a device; take a screenshot to report a bug!
Submit a bug report from your device, then check your email for a link to the Buglife web dashboard!

Usage

Invocation

There are 2 different ways to invoke the bug reporter, enumerated by Buglife.InvocationMethod:

SHAKE: Invokes when the user shakes their device.

Buglife.setInvocationMethod(InvocationMethod.SHAKE);

SCREENSHOT: Invokes when the user manually takes a screenshot with their device.
```
Buglife.setInvocationMethod(InvocationMethod.SCREENSHOT);
```
NONE: Disables all except manual invocations.
```
Buglife.setInvocationMethod(InvocationMethod.NONE);
```
This may be preferable for production builds. In this case, we recommend embedding a hidden button somewhere in your app which manually presents the bug reporter, so that you can still collect logs & other information.

For both automatic invocations (SHAKE and SCREENSHOT), a screenshot of the current activity is captured & attached to the bug report draft.

We recommend using the screenshot invocation for most apps. Taking screenshots to report feedback comes naturally to most users, and screenshots are still saved to the user's device as expected.

Manual & Custom Invocations

You can manually present the bug reporter activity using:

Buglife.showReporter();

Unlike the SHAKE & SCREENSHOT invocations, manually presenting the bug reporter activity does not automatically capture & attach a screenshot to the bug report draft.

This is useful for situations where attaching a screenshot of the immediate application state doesn't make sense (for example, if you have a "Report Bug" option in your app's settings screen).

Manually capture & attach screenshots

You can capture a screenshot of your app at any moment using Buglife.getScreenshotBitmap(). You can then create an Attachment object from the generated bitmap, and add this to your bug report draft using the Buglife.addAttachment() method. For example:

// Capture a screenshot of the current activity
Bitmap screenshot = Buglife.getScreenshotBitmap();
// Create an Attachment object with the generated screenshot
Attachment attachment = new Attachment
		.Builder("Screenshot.png", Attachment.TYPE_PNG)
		.build(screenshot);
// Queue the Attachment for the next bug report draft
Buglife.addAttachment(attachment);
// Show the bug reporter activity. This will include the queued attachment
Buglife.showReporter();

User Identification

If your application stores a user’s email address, then typically you should simply set the user’s email address shortly after initializing Buglife:

String email = /** Current user's email */
Buglife.setUserEmail(email);

Alternatively, you may set a string representing the user’s name, database ID or other identifier:

String username = /** Current username */
Buglife.setUserIdentifier(username);

User Location

By default, if your app is granted location permissions, Buglife will include that location in the report. This is useful for tracking down location-relevant bugs, such as services that are erroneously offered or not offered based on location.

You can change this behavior with the following:

Buglife.setCollectLocationIfPossible(false);

If the app does not request a location permission or the user denies the request, Buglife will not collect or include location data.

Custom Attributes

Adding custom attributes

You can include custom attributes (i.e. key-value pairs) to your bug reports, as such:

Buglife.putAttribute("Artist", "2Pac");
Buglife.putAttribute("Song", "California Love");

Removing attributes

To clear an attribute, set its value to null.

Buglife.putAttribute("Artist", null);

Screen Recording

Buglife can be used to record a user's screen, and attach the recording to a bug report. Screen recording is initiated programmatically, like such:

Buglife.startScreenRecording();
Here's how the complete screen recording flow works:

The screen recording flow is initiated using Buglife.startScreenRecording();
The user is shown an OS-level prompt requesting permission to record the screen.
Once granted, Buglife immediately begins recording the screen.
Screen recording will progress for up to 30 seconds. If the user wishes to stop screen recording earlier, they may do so by tapping the floating Record button.
The Buglife reporter UI is automatically shown with the recording attached.

Learn more

Check out the Buglife Android guide for configuration & customization options.

License

Copyright (C) 2017-2019 Buglife, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0
    
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Buglife/buglife-android