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
/**
* 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
public class SUDOPPreviewImageParams implements Serializable {
/**
* URL of the currently displayed image
*/
public String current;
/**
* List of image URLs to preview
*/
public String[] urls;
}| Field | Type | Description |
|---|---|---|
current | String | URL of the image to display first |
urls | String[] | List of image URLs to preview |
Parameter Values
current
current indicates the image displayed by default after opening the preview page.
Example:
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:
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://URIscontent://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:
handle.success(dataJson);The example implementation does not need to return business data, so it returns null directly:
handle.success(null);Call Failure
If the image preview page cannot be opened, or the parameters are abnormal, you can call:
handle.failure(retCode, retMsg);Example:
handle.failure(-1, "previewImage params invalid");| Parameter | Type | Description |
|---|---|---|
retCode | int | Error code; 0 indicates success, non-0 indicates failure |
retMsg | String | Error 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
currentandurls. - Display current by default: The preview page should prioritize displaying the image corresponding to
params.current. - Support switching between multiple images: If
urlscontains 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 launchesPreviewImageActivity.
Example Code
@Override
public void previewImage(SUDOPStateHandle handle, SUDOPPreviewImageParams params) {
handle.success(null);
PreviewImageActivity.start(context, params);
}Example Implementation Logic
1. Return Call Success
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
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:
Intent intent = new Intent(context, PreviewImageActivity.class);
intent.putExtra("params", params);
context.startActivity(intent);Recommended Implementation Flow
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 pageRecommended Preview Page Capabilities
| Feature | Description |
|---|---|
| Display the specified image by default | Prioritize displaying the image corresponding to current |
| Multi-image swiping | Support swiping left and right through the urls image list |
| Image zooming | Support pinch-to-zoom and double-tap-to-zoom |
| Long image adaptation | Support scrolling or proportionally scaled display of long images |
| Loading state | Show a loading indicator while a network image loads |
| Load failure prompt | Show a placeholder or error prompt when an image fails to load |
| Save image | Support long-press to save to the album as needed by the business |
| Close preview | Support 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:
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:
if (params.current == null || !Arrays.asList(params.urls).contains(params.current)) {
params.current = params.urls[0];
}Common Failure Scenarios
| Failure Scenario | Suggested Handling |
|---|---|
params is empty | handle.failure(-1, "previewImage params invalid") |
urls is empty | handle.failure(-1, "previewImage urls empty") |
current is not in urls | Display the first image by default or return failure |
| Image URL format not supported | Show a load-failure placeholder |
| Network image fails to load | Show a load-failure prompt |
| Local image file does not exist | Show a load-failure prompt |
| Activity fails to launch | handle.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(...)orhandle.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://, andcontent://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
Serializableis not recommended; consider using a global cache, Parcelable, or temporary storage. - Context requirement: If you use a non-Activity
contextto launch the page, you need to addFLAG_ACTIVITY_NEW_TASKto the Intent. - Security: When loading external URLs, pay attention to validating the protocol and source, to avoid the risk of loading untrusted resources.
