Skip to content

previewImage ​

Preview Image ​

This method opens the App-side image preview page based on the list of image URLs passed in by the SDK, and displays the specified images. Common use cases include image viewing, screenshot preview, album image preview, and moment image preview.


Method Declaration ​

java
/**
 * Preview image
 *
 * @param handle The state handle used to return the processing result to the SDK
 * @param params Request parameters
 */
void previewImage(SUDOPStateHandle handle, SUDOPPreviewImageParams params);

Parameters ​

SUDOPPreviewImageParams ​

java
public class SUDOPPreviewImageParams implements Serializable {
    /**
     * URL of the currently displayed image
     */
    public String current;

    /**
     * List of image URLs to preview
     */
    public String[] urls;
}
FieldTypeDescription
currentStringURL of the image to display first
urlsString[]List of image URLs to preview

Parameter Values ​

current ​

current indicates the image displayed by default after opening the preview page.

Example:

java
params.current = "https://example.com/image_1.jpg";

If current is empty, the App can display the first image in urls by default.


urls ​

urls indicates the list of image URLs that can be previewed.

Example:

java
params.urls = new String[]{
        "https://example.com/image_1.jpg",
        "https://example.com/image_2.jpg",
        "https://example.com/image_3.jpg"
};

Depending on the App implementation, image URLs may support the following types:

  • Network image URLs, for example https://example.com/image.jpg
  • Local file paths, for example /data/user/0/com.xxx.xxx/cache/image.jpg
  • file:// URIs
  • content:// URIs

The actually supported URL types depend on the App's image loading framework or preview page implementation.


Return Value ​

Return the call result to the SDK via SUDOPStateHandle.

Call Success ​

When the image preview page is successfully opened, call:

java
handle.success(dataJson);

The example implementation does not need to return business data, so it returns null directly:

java
handle.success(null);

Call Failure ​

If the image preview page cannot be opened, or the parameters are abnormal, you can call:

java
handle.failure(retCode, retMsg);

Example:

java
handle.failure(-1, "previewImage params invalid");
ParameterTypeDescription
retCodeintError code; 0 indicates success, non-0 indicates failure
retMsgStringError description

Runtime Behavior ​

  • Triggered by the SDK: When the SDK needs to preview images, it calls previewImage.
  • The App opens the image preview page: The App opens an image preview Activity or a custom page based on the passed-in current and urls.
  • Display current by default: The preview page should prioritize displaying the image corresponding to params.current.
  • Support switching between multiple images: If urls contains multiple images, the preview page can support swiping left and right to view them.
  • Immediate success callback: The example implementation first calls handle.success(null), then launches PreviewImageActivity.

Example Code ​

java
@Override
public void previewImage(SUDOPStateHandle handle, SUDOPPreviewImageParams params) {
    handle.success(null);
    PreviewImageActivity.start(context, params);
}

Example Implementation Logic ​

1. Return Call Success ​

java
handle.success(null);

In the example implementation, upon receiving the call, success is returned to the SDK immediately, indicating that the App has accepted the image preview request.


2. Launch the Image Preview Page ​

java
PreviewImageActivity.start(context, params);

The App side launches a custom image preview page and passes params into the page.

Since SUDOPPreviewImageParams implements Serializable, the parameters can be carried via an Intent:

java
Intent intent = new Intent(context, PreviewImageActivity.class);
intent.putExtra("params", params);
context.startActivity(intent);

text
SDK calls previewImage
        ↓
App validates params, urls, current
        ↓
Return the call result handle.success(null)
        ↓
Launch the image preview page
        ↓
The preview page loads the urls image list
        ↓
Locate and display the image corresponding to current
        ↓
User swipes to view or closes the page

FeatureDescription
Display the specified image by defaultPrioritize displaying the image corresponding to current
Multi-image swipingSupport swiping left and right through the urls image list
Image zoomingSupport pinch-to-zoom and double-tap-to-zoom
Long image adaptationSupport scrolling or proportionally scaled display of long images
Loading stateShow a loading indicator while a network image loads
Load failure promptShow a placeholder or error prompt when an image fails to load
Save imageSupport long-press to save to the album as needed by the business
Close previewSupport tapping back or a close button to exit the preview page

Parameter Validation Suggestions ​

It is recommended to perform basic validation before launching the preview page:

java
if (params == null || params.urls == null || params.urls.length == 0) {
    handle.failure(-1, "previewImage params invalid");
    return;
}

If current is empty or not in urls, you can display the first image by default:

java
if (params.current == null || !Arrays.asList(params.urls).contains(params.current)) {
    params.current = params.urls[0];
}

Common Failure Scenarios ​

Failure ScenarioSuggested Handling
params is emptyhandle.failure(-1, "previewImage params invalid")
urls is emptyhandle.failure(-1, "previewImage urls empty")
current is not in urlsDisplay the first image by default or return failure
Image URL format not supportedShow a load-failure placeholder
Network image fails to loadShow a load-failure prompt
Local image file does not existShow a load-failure prompt
Activity fails to launchhandle.failure(-1, "previewImage start activity fail")

Notes ​

  • Callback required: After the method is called, you should notify the SDK of the call result via handle.success(...) or handle.failure(...).
  • Example returns success immediately: The example implementation first calls handle.success(null) and then launches the Activity, indicating that the request has been accepted, not that the image is guaranteed to load successfully.
  • Image load failure may not call back the SDK: A single image failing to load in the preview page can generally just be indicated to the user within the page.
  • Perform UI operations on the main thread: UI operations such as launching an Activity, popping up dialogs, and previewing images should be performed on the main thread.
  • Supported URL types depend on the implementation: Whether network URLs, local paths, file://, and content:// are supported depends on the image loading framework and preview page implementation.
  • Serializable parameter passing limitation: If the image list is large, passing a large amount of data via Serializable is not recommended; consider using a global cache, Parcelable, or temporary storage.
  • Context requirement: If you use a non-Activity context to launch the page, you need to add FLAG_ACTIVITY_NEW_TASK to the Intent.
  • Security: When loading external URLs, pay attention to validating the protocol and source, to avoid the risk of loading untrusted resources.