# CustomActivityOnCrash

**Repository Path**: HarmonyOS-tpc/CustomActivityOnCrash

## Basic Information

- **Project Name**: CustomActivityOnCrash
- **Description**: CustomActivityOnCrash is an OHOS library allows launching a custom activity when the app crashes, instead of showing the hated "Unfortunately, X has stopped" dialog.
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2021-04-15
- **Last Updated**: 2023-04-17

## Categories & Tags

**Categories**: harmonyos-advanced

**Tags**: None

## README

# CustomActivityOnCrash

CustomActivityOnCrash : CustomActivityOnCrash is an OHOS library allows launching a **custom activity when the app crashes**, instead of showing the hated "Unfortunately, X has stopped" dialog.

# CustomActivityOnCrash includes :
* Launch custom error ability when the app crashes in Main & background thread.
* Launch default error ability, if custom error ability is not configured.

# Usage Instructions
A sample project which provides runnable code examples that demonstrate uses of the classes in this project is available in the entity/ folder.

### Launch custom error ability when the app crashes

Create custom view in layout as shown below :

```
<?xml version="1.0" encoding="utf-8"?>
<DirectionalLayout
    xmlns:ohos="http://schemas.huawei.com/res/ohos"
    ohos:height="match_parent"
    ohos:width="match_parent"
    ohos:alignment="horizontal_center"
    ohos:bottom_padding="$dimen:activity_vertical_margin"
    ohos:left_padding="$dimen:activity_horizontal_margin"
    ohos:orientation="vertical"
    ohos:right_padding="$dimen:activity_horizontal_margin"
    ohos:top_padding="$dimen:activity_vertical_margin">

    <ScrollView
        ohos:height="0vp"
        ohos:width="match_parent"
        ohos:match_viewport="true"
        ohos:weight="1">

        <DirectionalLayout
            ohos:height="match_content"
            ohos:width="match_parent"
            ohos:alignment="center"
            ohos:orientation="vertical">

            <Image
                ohos:height="match_content"
                ohos:width="match_content"
                ohos:component_description="@null"
                ohos:image_src="$media:customactivityoncrash_error_image"/>

            <Text
                ohos:height="match_content"
                ohos:width="match_content"
                ohos:text="$string:error_occurred"
                ohos:text_size="18vp"
                ohos:text_style="bold"/>

            <Button
                ohos:id="$+id:close_button"
                ohos:height="match_content"
                ohos:width="match_content"
                ohos:text="$string:close_app"
                ohos:text_size="15vp"
                ohos:top_margin="60vp"/>
        </DirectionalLayout>
    </ScrollView>

</DirectionalLayout>
```

Add a snippet like this to your `Ability` class to launch custom error ability :

```
@Override
public void onStart(Intent intent) {
   super.onStart(intent);
   ComponentContainer view = (ComponentContainer) LayoutScatter.getInstance(this).parse(ResourceTable.Layout_ability_main, null, false);
   setUIContent(view);

    CaocConfig.Builder.create()
        .bundleName("cat.ereza.customactivityoncrash.demo")
        .errorAbility("cat.ereza.customactivityoncrash.demo.CustomErrorAbility")
        .apply();
}
```

### Launch default error ability, if custom error ability is not configured

Add a snippet like this to your `Ability` class to launch default error ability from CustomActivityOnCrash library :

```
@Override
public void onStart(Intent intent) {
   super.onStart(intent);
   ComponentContainer view = (ComponentContainer) LayoutScatter.getInstance(this).parse(ResourceTable.Layout_ability_main, null, false);
   setUIContent(view);

    CaocConfig.Builder.create()
        .bundleName("cat.ereza.customactivityoncrash.demo")
        .apply();
}
```

###  App crash by throwing an uncaught exception

Force an app crash by throwing an uncaught exception to display custom error ability or default error ability view, using something like this in your code :

```
throw new RuntimeException("Boom!");
```

# Installation Instructions

1. For using CustomActivityOnCrash module in sample application, add below dependencies in "entry" module to generate hap :

    Modify entry build.gradle as below :
	```
	dependencies {
		implementation project(':library')
	}
	```

2. For using CustomActivityOnCrash in separate application, make sure to add the "CustomActivityOnCrash.har" in entry libs folder as mentioned below :

    Modify entry build.gradle as below :
    ```
    dependencies {
        implementation fileTree(dir: 'libs', include: ['*.jar', '*.har'])
    }
    ```

3. For using CustomActivityOnCrash from a remote repository in separate application, add the below dependencies :

    Modify entry build.gradle as below :
    ```
    dependencies {
    	implementation 'io.openharmony.tpc.thirdlib:CustomActivityOnCrash:1.0.1'
    }
    ```

# Incompatibilities
1. CustomActivityOnCrash library will not work with any custom UncaughtExceptionHandler set after initializing the library that does not call back to the original handler.
2. If your app initialization or error ability crash, there is a possibility of entering an infinite restart loop (this is checked by the library for the most common cases, but could happen in rarer cases).
3. The library has not been tested with multidex enabled. It uses Class.forName() to load classes. If you test it with such configuration, please provide feedback!
4. The library has not been tested with multiprocess apps. If you test it with such configuration, please provide feedback too!

# Disclaimers
1. CustomActivityOnCrash library will not avoid ANRs from happening.
2. CustomActivityOnCrash library will not catch native errors.

# License
```
Any contribution in order to make this library better will be welcome!

The library is licensed under the [Apache License 2.0](https://codehub-y.huawei.com/Projects-OpenSource-Gitee/CustomActivityOnCrash/files?ref=master&filePath=LICENSE&isFile=true).

The bug image used in the default error activity is licensed under CC-BY by Riff: https://www.sketchport.com/drawing/6119265933459456/lady-bug
If you use the image in your app, don't forget to mention that!
```