Skip to content

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;
}
FieldTypeDescription
filePathStringImage 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);
ParameterTypeDescription
retCodeintError code; 0 indicates success, non-0 indicates failure
retMsgStringError 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.filePath is 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(...) or handle.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");
    }
}

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 ScenarioSuggested Handling
filePath is emptyhandle.failure(-1, "The filePath does not exist.")
File does not existhandle.failure(-1, "The filePath does not exist.")
A network image URL is passed inReturn failure; network paths are not supported
File is not a valid imageReturn failure and indicate an abnormal image format
No album or media write permissionRequest permission; return failure if the user denies it
System album write failedReturn failure with specific error information
An exception occurred during savingCatch the exception and return it via handle.failure

Notes ​

  • Callback required: Whether saving succeeds or fails, you must call handle.success(...) or handle.failure(...).
  • Only local paths supported: filePath must 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 MediaStore to save to the album, to adapt to the scoped storage mechanism.
  • Android 9 and below: You may need to request the WRITE_EXTERNAL_STORAGE permission.
  • 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 to saveImageToPhotosAlbum to avoid ambiguity in logs.