Customize the splash page

IAPMiniprogram SDK shows a splash page upon the initial launch of a mini program. This ensures a smooth user experience because it allows time for the SDK to load the mini-program data. The super app can follow this guide to customize a splash page.

Default user experience

The default splash page includes the following two parts:

  • A loading page that shows the loading progress
  • An error page that describes the error when the launch fails

You can see examples of these two pages in the following table:

Loading page

Error page

1.png

1.png

Procedures

Take the following three steps to customize the splash page:

Step 1: Implement AbstractSplashFragment

Create a class that extends the AbstractSplashFragment class to define a custom splash fragment. This fragment has the loading, error, and exit events. Refer to the following sample code for the implementation:

copy
public static class CustomSplashFragment extends AbstractSplashFragment {
    private ImageView iconView;
    private TextView appName;
    private ProgressBar loadingView;
    private TextView desc;

    @Nullable
    @Override
    public View onCreateView(@NonNull LayoutInflater inflater, 
                             @Nullable ViewGroup container,
                             @Nullable Bundle savedInstanceState) {
        View view = inflater.inflate(R.layout.fragment_custom_splash, container, false);
        initView(view);
        return view;
    }

    private void initView(View view) {
        iconView = view.findViewById(R.id.iv_icon);
        appName = view.findViewById(R.id.tv_name);
        loadingView = view.findViewById(R.id.loading_view);
        desc = view.findViewById(R.id.tv_desc);
    }

    @Override
    public void updateLoadingInfo(SplashEntryInfo info) {
        if (info == null) {
            return;
        }
        ImageUtils.loadImage(info.iconUrl, new ImageListener() {
            @Override
            public void onImage(Bitmap bitmap) {
                iconView.setImageBitmap(bitmap);
            }
        });
        appName.setText(info.appName);
        desc.setText(info.desc);
        loadingView.setVisibility(View.VISIBLE);
    }

    @Override
    public void showError(String code, String message) {
        loadingView.setVisibility(View.GONE);
        desc.setText(message + "(" + code + ")");
    }

    @Override
    public void exit() {
        loadingView = null;
    }
}

For more information about the AbstractSplashFragment class, refer to AbstractSplashFragment.

When customizing the splash fragment, you can use the onCreateView method to inflate your custom layout file (which is fragment_custom_splash in this sample). The following sample code shows how to define the layout in XML:

copy
<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
  android:orientation="vertical" android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:layout_centerInParent="true">
        <ImageView
      android:layout_width="100dp"
      android:layout_height="100dp"
      android:id="@+id/iv_icon"
      android:layout_centerHorizontal="true"
      />

    <TextView
      android:layout_width="wrap_content"
      android:layout_height="wrap_content"
      android:layout_centerHorizontal="true"
      android:id="@+id/tv_name"
      android:layout_below="@id/iv_icon"
      android:layout_marginTop="10dp"
      />

    <TextView
      android:layout_width="wrap_content"
      android:layout_height="wrap_content"
      android:id="@+id/tv_desc"
      android:layout_below="@id/tv_name"
      android:layout_marginTop="10dp"
      android:layout_centerHorizontal="true"/>

    <ProgressBar
      android:id="@+id/loading_view"
      android:layout_width="wrap_content"
      android:layout_height="wrap_content"
      style="@style/Widget.AppCompat.ProgressBar"
      android:layout_centerHorizontal="true"
      android:layout_below="@id/tv_desc"
      android:layout_marginTop="10dp"/>
</RelativeLayout>

Step 2: Implement GriverSplashFragmentExtension

Create a class that implements the GriverSplashFragmentExtension interface to create a splash fragment that is defined in the previous step. Refer to the following sample code for the implementation:

copy
public class CustomSplashViewExtension implements GriverSplashFragmentExtension {
    @Override
    public AbstractSplashFragment createSplashFragment() {
        return new CustomSplashFragment();
    }
}

For more information about the interface, refer to GriverSplashFragmentExtension.

Step 3: Register GriverSplashFragmentExtension

After the SDK initialization logic, call the registerExtension API to register the implemented GriverSplashFragmentExtension interface to the SDK with the following sample code:

copy
Griver.registerExtension(new GriverExtensionManifest(GriverSplashFragmentExtension.class, new CustomSplashViewExtension()));

For how to call the registerExtension API, refer to registerExtension.

Interfaces and classes

AbstractSplashFragment

The AbstractSplashFragment class is used to customize a splash fragment. The following code shows the definition of this class:

copy
abstract class AbstractSplashFragment extends Fragment {
    public abstract void updateLoadingInfo(SplashEntryInfo info);
    public void updateProgress(SplashEntryInfo info) {}
    public abstract void showError(String code, String message);
    public abstract void exit();
    public void reload() {
        if (listener != null) {
            listener.onReload();
        }
    }
}

As we can see from the definition, the AbstractSplashFragment class provides the following five methods:

Method

Description

Required

updateLoadingInfo

The super app uses this method to get the latest information of the opened mini program and show it on a splash page. For more information, refer to updateLoadingInfo.

M

updateProgress

The super app uses this method to get the loading progress of the mini program and update it on a splash page. For more information, refer to updateProgress.

M

showError

The super app uses this method to show an error view on a splash page when the mini-program launch fails. For more information, refer to showError.

O

exit

The SDK calls this method to show the exit button on the splash page. This allows users to exit the loading progress.

M

reload

The SDK calls this method to show the reload button on the splash page. This allows users to reload the mini program when the launch fails.

O

updateLoadingInfo

The updateLoadingInfo method has the following input parameter whose value is passed by the SDK:

Field

Data type

Description

Required

info

SplashEntryInfo

The latest information of the opened mini program. For more information, refer to SplashEntryInfo.

M

updateProgress

The updateProgress method has the following input parameter whose value is passed by the SDK:

Field

Data type

Description

Required

info

SplashEntryInfo

The loading progress of the mini program. For more information, refer to SplashEntryInfo.

M

showError

The showError method has the following two input parameters whose values are passed by the SDK:

Field

Data type

Description

Required

code

String

The error code of the encountered error. For more information, refer to Errors.

M

message

String

The error message that describes the error code in detail. For more information, refer to Errors.

M

GriverSplashFragmentExtension

The GriverSplashFragmentExtension interface is used to create a splash page that is defined by the AbstractSplashFragment class. The following code shows the definition of this interface:

copy
public interface GriverSplashFragmentExtension extends GriverExtension {
    AbstractSplashFragment createSplashFragment();
}

As we can see from the definition, the GriverSplashFragmentExtension interface has the following method:

Method

Description

Required

createSplashFragment

The super calls this method to create a custom splash fragment. This fragment extends the AbstractSplashFragment class.

M

Appendices

SplashEntryInfo

The SplashEntryInfo model has the following parameters:

Field

Data type

Description

Required

appId

String

The ID of the mini program. This parameter is returned if the updateLoadingInfo method is called.

O

appName

String

The name of the mini program. This parameter is returned if the updateLoadingInfo method is called. Its value can be empty when the ID of the opened mini program is invalid.

O

iconUrl

String

The URL of the mini-program icon. This parameter is returned if the updateLoadingInfo method is called. Its value can be empty when the ID of the opened mini program is invalid.

O

desc

String

The description of the mini program. This parameter is returned if the updateLoadingInfo method is called. Its value can be empty for either of the following two scenarios:

  • The ID of the opened mini program is invalid.
  • The mini program does not have a description.

O

slogan

String

The slogan of the mini program. This parameter is returned if the updateLoadingInfo method is called. Its value can be empty for either of the following two scenarios:

  • The ID of the opened mini program is invalid.
  • The mini program does not have a slogan.

O

progress

Integer

The loading progress of the mini program. This parameter is returned if the updateProgress method is called.

Value range: 0-100

O

Errors

The following table lists the details of the errors that can happen when the mini-program launch fails:

Error code

Error message

Description

1001

Mini Program has been removed

The mini program is deleted from Mini Program Development Platform.

1002

Mini Program has been suspended

The mini program is removed from the super app.

10000

Unknown error

Unknown error.

10001

Mini program does not exist.

This might happen when the passed mini-program ID is invalid.

10002

Mini program unzip failed

Failed to unzip the mini-program package. This might happen when the downloaded package is damaged.

10003

Mini program fetch failed

Failed to obtain the mini-program metadata probably due to network issues.

10009

Mini program download failed

Failed to download the mini-program package probably due to network issues.

10010

Mini program preparation timed out

Failed to launch the mini program within the timeout threshold of 30 seconds, which is probably caused by network issues.

10030

Failed to load remote resources

Failed to download the remote resources that are required for running the mini program, which is probably caused by network issues.