tencent cloud

Tencent Cloud Super App as a Service

ドキュメントTencent Cloud Super App as a Service

Custom Error UI

ダウンロード
フォーカスモード
フォントサイズ
最終更新日: 2026-08-26 10:16:46

Feature overview

Starting from version 2.4.3, internal SDK error prompts (Toasts/pop-ups) are centralized. Superapps can fully take over the error UI by implementing the MiniErrorUIProxy extension point. This allows you to customize prompt text, styles, and interactions, and eliminates the "duplicate prompts" conflict caused by the superapp's own callbacks.
After the superapp takes over, only the prompt UI is affected. SDK behaviors such as closing the container and reporting errors are not affected.

Extension point

MiniErrorUIProxy

public abstract class MiniErrorUIProxy {

/**
* Displays internal SDK error prompts.
*
* @param activity Specifies the current hosting Activity. The value can be null. Ensure that the superapp checks for null values.
* @param info Specifies the error context.
* @return Returns {@code true} if the superapp has displayed the UI itself and the SDK should skip the built-in UI; returns {@code false} to use the default SDK prompt.
*/
public boolean showError(Activity activity, MiniErrorInfo info) {
return false;
}

/**
* Indicates whether to suppress the built-in SDK prompt
when the error has been returned to the superapp via {@code ResultReceiver} ({@link MiniErrorInfo#reportedToHost} is true). Return true to eliminate duplicate prompts if the superapp has already displayed a prompt in the callback.
*
* @return Returns {@code true} to suppress the built-in prompt; returns {@code false} (default) to keep the existing behavior.
*/
public boolean suppressBuiltInWhenReported() {
return false;
}
}
Note:
The activity can be null or in the finishing state. Ensure that you check its status before performing operations.

MiniErrorInfo (Error context)

Field
Description
domain
Error domain, used to identify the phase where the error occurred. For valid values, see the constants below.
code
Error code, used to exactly match specific errors and display the corresponding UI.
msg
Default SDK error message. You can use it directly or ignore it.
appId
Mini program appid. The value can be empty if some pre-launch failures occur.
engineType
Engine type (mini program or mini game).
willFinish
Indicates whether the SDK will subsequently close the container. If the value is true , it is not recommended to display a Dialog. Use a Toast instead.
reportedToHost
Indicates whether the error has been returned to the superapp via ResultReceiver . If the value is true , the superapp may have already displayed the UI. You can use this with suppressBuiltInWhenReported() to suppress the built-in prompt and avoid duplicate prompts.

Domain

Constant
Description
DOMAIN_PRE_LAUNCH
Pre-launch phase
DOMAIN_LAUNCH
Launch phase
DOMAIN_RUNTIME
Runtime phase

Integration method

1. Inherit MiniErrorUIProxy to implement custom logic.
2. Register it to the SDK using the @ProxyService(proxy = MiniErrorUIProxy.class) annotation.

Example

@ProxyService(proxy = MiniErrorUIProxy.class)
public class MyErrorUIProxy extends MiniErrorUIProxy {

@Override
public boolean showError(Activity activity, MiniErrorInfo info) {
if (activity == null || activity.isFinishing()) {
return false; // The Activity is unavailable. Use the built-in SDK prompt.
}
// If willFinish is true, the SDK will close the container. A Dialog is not recommended.
if (info.willFinish) {
Toast.makeText(activity, info.msg, Toast.LENGTH_SHORT).show();
} else {
showCustomDialog(activity, info);
}
return true; // Taken over by the superapp.
}

@Override
public boolean suppressBuiltInWhenReported() {
return true; // The superapp has already displayed the prompt in the callback. Suppress the built-in prompt to avoid duplicate prompts.
}
}

Decision flow

Priority of SDK error prompt processing:
1. No Proxy registered: Uses the built-in prompt.
2. Error returned to the superapp AND suppressBuiltInWhenReported() returns true : Skips the built-in prompt to eliminate duplicate prompts.
3. showError() returns true : The superapp has taken over. Skips the built-in prompt.
4. Otherwise : Uses the built-in prompt.

Notes

Note: The activity can be null or in the finishing state. Ensure that you check its status before performing UI operations that require an Activity (such as displaying a Dialog). Also, check the info.willFinish value. If it is true , the SDK will close the container, and it is recommended to use a Toast instead.



ヘルプとサポート

この記事はお役に立ちましたか?

フィードバック