saveImageToPhotosAlbum
Save Image to the System Photo Album
This method saves a local image file on the App to the system photo album of the user's device. It is typically used for saving game screenshots, share posters, QR codes, record images, and similar scenarios.
The SDK passes in a local image file path. The App side needs to verify that the file exists and write the image into the system photo album. After saving completes, the result is returned to the SDK via SUDOPStateHandle.
Method Declaration
java
/**
* Save an image to the system photo album
*
* @param handle The state handle used to return the processing result to the SDK
* @param params Request parameters
*/
void saveImageToPhotosAlbum(
SUDOPStateHandle handle,
SUDOPSaveImageToPhotosAlbumParams params
);Parameters
SUDOPSaveImageToPhotosAlbumParams
java
public class SUDOPSaveImageToPhotosAlbumParams {
/**
* Image file path, can be a temporary file path or a permanent file path (local path); network paths are not supported
*/
public String filePath;
}| Field | Type | Description |
|---|---|---|
filePath | String | Image file path, can be a temporary or permanent file path; must be a local path, network paths are not supported |
Return Value
Return the save result to the SDK via SUDOPStateHandle.
Save Success
On save success, call:
java
handle.success(dataJson);This interface usually does not need to return business data on success; you can pass null or an empty string:
java
handle.success(null);Or:
java
handle.success("");Save Failure
On save failure, call:
java
handle.failure(retCode, retMsg);| Parameter | Type | Description |
|---|---|---|
retCode | int | Error code; 0 indicates success, non-0 indicates failure |
retMsg | String | Error description |
Example:
java
handle.failure(-1, "The filePath does not exist.");Runtime Behavior
- Triggered by the SDK: When the game or SDK needs to save a local image to the system photo album, it calls
saveImageToPhotosAlbum. - The App validates the file path: The App side needs to check whether
params.filePathis empty, whether the file exists, and whether it is a local file path. - The App writes to the system photo album: After validation passes, the App writes the corresponding image into the system photo album.
- Asynchronous or synchronous callback: After saving completes, the App needs to notify the SDK of the save result via
handle.success(...)orhandle.failure(...). - Permission handling: On some Android versions, saving to the album may require requesting storage or media permissions; the App should handle permission requests and compatibility logic itself.
Example Code
java
@Override
public void saveImageToPhotosAlbum(
SUDOPStateHandle handle,
SUDOPSaveImageToPhotosAlbumParams params
) {
File file;
if (params.filePath == null || !(file = new File(params.filePath)).exists()) {
handle.failure(-1, "The filePath does not exist.");
return;
}
boolean result = false;
try {
result = saveImageToGallery(context, file);
} catch (Exception e) {
handle.failure(-1, "saveImageToPhotsAlbum error:" + e);
return;
}
if (result) {
handle.success(null);
} else {
handle.failure(-1, "saveImageToPhotsAlbum fail");
}
}Recommended Implementation Flow
text
SDK calls saveImageToPhotosAlbum
↓
App validates params.filePath
↓
Check whether the file exists
↓
Check or request album/media storage permissions
↓
Save the image to the system photo album
↓
Save success: handle.success(null)
Save failure: handle.failure(retCode, retMsg)Common Failure Scenarios
| Failure Scenario | Suggested Handling |
|---|---|
filePath is empty | handle.failure(-1, "The filePath does not exist.") |
| File does not exist | handle.failure(-1, "The filePath does not exist.") |
| A network image URL is passed in | Return failure; network paths are not supported |
| File is not a valid image | Return failure and indicate an abnormal image format |
| No album or media write permission | Request permission; return failure if the user denies it |
| System album write failed | Return failure with specific error information |
| An exception occurred during saving | Catch the exception and return it via handle.failure |
Notes
- Callback required: Whether saving succeeds or fails, you must call
handle.success(...)orhandle.failure(...). - Only local paths supported:
filePathmust be a local image file path; network paths such as HTTP/HTTPS are not supported. - File existence check: Before saving, you must verify that the file exists, to avoid exceptions caused by invalid paths.
- Permission compatibility: Different Android versions have different album save permission requirements; the App needs to adapt according to the system version.
- Android 10 and above: It is recommended to use
MediaStoreto save to the album, to adapt to the scoped storage mechanism. - Android 9 and below: You may need to request the
WRITE_EXTERNAL_STORAGEpermission. - Avoid blocking the main thread: Image copying, writing to the album, and media library refreshing may be time-consuming; it is recommended to execute them on a worker thread.
- Accurate error messages: On failure, it is recommended to return a clear error reason to help the SDK or business side locate the problem.
- Method name spelling: The error message in the example is
saveImageToPhotsAlbum; in the actual implementation you can standardize it tosaveImageToPhotosAlbumto avoid ambiguity in logs.
